Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[@types/bl] update bl types to v5 #52236

Merged
merged 12 commits into from
Apr 9, 2021
Merged

[@types/bl] update bl types to v5 #52236

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
77c02f5
[@types/bl] update bl types to v5
achingbrain Apr 7, 2021
5431b26
add package.json for bl
achingbrain Apr 7, 2021
da784f0
update dep path
achingbrain Apr 7, 2021
034ecf0
update dep path
achingbrain Apr 7, 2021
d5e5eb9
remove package.json
achingbrain Apr 7, 2021
5708bab
remove named exports
achingbrain Apr 7, 2021
ed63713
add missing methods and tests for those methods
achingbrain Apr 8, 2021
a014520
revert import type change and remove extra header
achingbrain Apr 9, 2021
92a8f4b
add BufferList to indexOf
achingbrain Apr 9, 2021
c1a8757
rename variables in tests so it is clearer what is going on
achingbrain Apr 9, 2021
3383b02
use interface for multiple inheritance
achingbrain Apr 9, 2021
da6f9c1
apply prettier
achingbrain Apr 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
45 changes: 45 additions & 0 deletions types/bl/BufferList.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
// Type definitions for BufferList v5.0
achingbrain marked this conversation as resolved.
Show resolved Hide resolved
// Project: https://github.com/rvagg/bl
// Definitions by: Bart van der Schoor <https://github.com/Bartvds>
// Francis Gulotta <https://github.com/reconbot>
// Ben Allfree <https://github.com/benallfree>
// Alex Potsides <https://github.com/achingbrain>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/// <reference types="node" />

declare class BufferList {
constructor(initialData?: Buffer | Buffer[] | BufferList | BufferList[] | string);

length: number;
append(buffer: Buffer | Buffer[] | BufferList | BufferList[] | string): BufferList;
get(index: number): number;
slice(start?: number, end?: number): Buffer;
shallowSlice(start?: number, end?: number): BufferList;
copy(dest: Buffer, destStart?: number, srcStart?: number, srcEnd?: number): Buffer;
duplicate(): BufferList;
consume(bytes?: number): void;
toString(encoding?: string, start?: number, end?: number): string;
indexOf(value: string | number | Uint8Array | BufferList | Buffer, byteOffset?: number, encoding?: string): number;
readDoubleBE(offset?: number): number;
readDoubleLE(offset?: number): number;
readFloatBE(offset?: number): number;
readFloatLE(offset?: number): number;
readInt32BE(offset?: number): number;
readInt32LE(offset?: number): number;
readUInt32BE(offset?: number): number;
readUInt32LE(offset?: number): number;
readInt16BE(offset?: number): number;
readInt16LE(offset?: number): number;
readUInt16BE(offset?: number): number;
readUInt16LE(offset?: number): number;
readInt8(offset: number): number;
readUInt8(offset: number): number;
readIntBE(offset: number): number;
readIntLE(offset: number): number;
readUIntBE(offset: number): number;
readUIntLE(offset: number): number;

static isBufferList(other: any): boolean;
}
export = BufferList;
31 changes: 30 additions & 1 deletion types/bl/bl-tests.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,31 @@
import BufferList = require('bl');
import BufferList from 'bl';
achingbrain marked this conversation as resolved.
Show resolved Hide resolved
import BufferListDeepExport from 'bl/BufferList';

var bl: BufferList;
var buffer: Buffer;
var offset: number;
var num: number;
var str: string;

BufferList.isBufferList({});

// has Duplex methods
bl.pause();
bl.resume();

var bufferListDeep = new BufferListDeepExport();

// is assignable
bufferListDeep = bl.duplicate();

// is not assignable as it lacks the Duplex methods
var bl2: BufferList;
bl2 = bufferListDeep; // $ExpectError

// does not have Duplex methods
bufferListDeep.pause(); // $ExpectError
bufferListDeep.resume(); // $ExpectError

bl = new BufferList();
bl = new BufferList(bl);
bl = new BufferList([bl]);
Expand Down Expand Up @@ -71,3 +91,12 @@ num = bl.readInt8(offset);
num = bl.readInt8(offset);
num = bl.readUInt8(offset);
num = bl.readUInt8(offset);
num = bl.readIntBE(offset);
num = bl.readIntLE(offset);
num = bl.readUIntBE(offset);
num = bl.readUIntLE(offset);

BufferList.isBufferList(bl); // $ExpectTrue
BufferList.isBufferList({}); // $ExpectFalse
BufferListDeepExport.isBufferList(bufferListDeep); // $ExpectTrue
BufferListDeepExport.isBufferList({}); // $ExpectFalse
67 changes: 39 additions & 28 deletions types/bl/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,49 @@
// Type definitions for BufferList v4.1
// Type definitions for BufferList v5.0
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are the v4 types still in widespread use and, if so, will they need to be updated (e.g. to fix bugs)? If so, it might be desirable to split out a separate directory for them (see the readme).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the readme:

If you intend to continue updating the older version of a library's type declarations, you may create a new subfolder (e.g. /v2/) named for the current (soon to be "old") version, and copy existing files from the current version to it.

Copy link
Contributor

@benallfree benallfree Apr 8, 2021 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@amcasey I'm one of the maintainers of this package; not sure if your suggestion is worthwhile only because @rvagg has expressed interest #52236 (comment) in moving this into bl as a first-class citizen and existing users can pin the @types/bl package version they need in the mean time.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@benallfree Creating an old-version directory is very optional and I was simply asking whether it would be beneficial for this package. Having said that, I'm not sure I understand how the comment you linked answers the question - first class types would be great but users of v4 would still consume @types/bl and might still want bug fixes for those types. If usage of v4 is limited or if the types are simple enough to be "obviously correct", then it's probably not worthwhile.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@amcasey Sorry yes I meant to say that I see your point and it could be valuable to maintain older versions. There are already known issues/shortcomings with the v4 typings, for example.

I was attempting to balance that against how much longer this package would need to be maintained, but now that I think about it more, I realize that this @types/bl package can really never be deprecated because older versions of bl still need it.

So I agree with you now :) We should folder-ize this package.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is necessary, at least not yet - the bump from v4 to v5 happened because the underlying buffer browser polyfill jumped from v5 to v6, removing ie11 and Safari < 10 support, not because there was any API breakage.

Would it be better to hold off creating folders until there's a release that breaks the API, give that if we create folders now the contents of v4 and v5 would be identical?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@achingbrain Hmm I agree with your point too! I'm good either way 👍

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@achingbrain I'm not sure I understand your suggestion. I think you're saying that users currently consuming bl@4 should start consuming @types/bl@5 because the APIs are compatible?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To reiterate though, I'm fine with not creating a v4 directory.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@amcasey yes, that’s what I’m saying - the APIs are compatible.

// Project: https://github.com/rvagg/bl
// Definitions by: Bart van der Schoor <https://github.com/Bartvds>
// Francis Gulotta <https://github.com/reconbot>
// Ben Allfree <https://github.com/benallfree>
// Alex Potsides <https://github.com/achingbrain>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/// <reference types="node" />

declare class BufferList {
constructor(initialData?: Buffer | Buffer[] | BufferList | BufferList[] | string);
import BufferList = require('./BufferList');
import { Duplex } from 'readable-stream';

length: number;
append(buffer: Buffer | Buffer[] | BufferList | BufferList[] | string): BufferList;
get(index: number): number;
slice(start?: number, end?: number): Buffer;
shallowSlice(start?: number, end?: number): BufferList;
copy(dest: Buffer, destStart?: number, srcStart?: number, srcEnd?: number): Buffer;
duplicate(): BufferList;
consume(bytes?: number): void;
toString(encoding?: string, start?: number, end?: number): string;
indexOf(value: string | number | Uint8Array | BufferList | Buffer, byteOffset?: number, encoding?: string): number;
readDoubleBE(offset?: number): number;
readDoubleLE(offset?: number): number;
readFloatBE(offset?: number): number;
readFloatLE(offset?: number): number;
readInt32BE(offset?: number): number;
readInt32LE(offset?: number): number;
readUInt32BE(offset?: number): number;
readUInt32LE(offset?: number): number;
readInt16BE(offset?: number): number;
readInt16LE(offset?: number): number;
readUInt16BE(offset?: number): number;
readUInt16LE(offset?: number): number;
readInt8(offset: number): number;
readUInt8(offset: number): number;
declare class BufferListStream extends Duplex {
constructor(initialData?: Buffer | Buffer[] | BufferList | BufferList[] | BufferListStream | BufferListStream[] | string);

length: number;
append(buffer: Buffer | Buffer[] | BufferList | BufferList[] | BufferListStream | BufferListStream[] | string): BufferListStream;
get(index: number): number;
slice(start?: number, end?: number): Buffer;
shallowSlice(start?: number, end?: number): BufferListStream;
copy(dest: Buffer, destStart?: number, srcStart?: number, srcEnd?: number): Buffer;
duplicate(): BufferListStream;
consume(bytes?: number): void;
toString(encoding?: string, start?: number, end?: number): string;
indexOf(value: string | number | Uint8Array | BufferListStream | Buffer, byteOffset?: number, encoding?: string): number;
readDoubleBE(offset?: number): number;
readDoubleLE(offset?: number): number;
readFloatBE(offset?: number): number;
readFloatLE(offset?: number): number;
readInt32BE(offset?: number): number;
readInt32LE(offset?: number): number;
readUInt32BE(offset?: number): number;
readUInt32LE(offset?: number): number;
readInt16BE(offset?: number): number;
readInt16LE(offset?: number): number;
readUInt16BE(offset?: number): number;
readUInt16LE(offset?: number): number;
readInt8(offset: number): number;
readUInt8(offset: number): number;
readIntBE(offset: number): number;
readIntLE(offset: number): number;
readUIntBE(offset: number): number;
readUIntLE(offset: number): number;

static isBufferList(other: any): boolean;
}
export = BufferList;

export = BufferListStream;
3 changes: 2 additions & 1 deletion types/bl/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@
],
"types": [],
"noEmit": true,
"forceConsistentCasingInFileNames": true
"forceConsistentCasingInFileNames": true,
"esModuleInterop": true
},
"files": [
"index.d.ts",
Expand Down