diff --git a/CHANGELOG.md b/CHANGELOG.md index cd3552f..60e29c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ ## Changelog -### [v1.1.0](https://github.com/panates/flexy-buffer/compare/v1.0.1...v1.1.0) - +### [v1.1.1](https://github.com/panates/flexy-buffer/compare/v1.1.0...v1.1.1) - #### 💬 General Changes -- Make position settable, avoid unneeded flush() timer resets @Eray Hanoğlu +- Fill TSDoc gaps: buffer field, read-method @returns/@throws, setter @param @Eray Hanoğlu - Bump docs/api.md baseline to the commit it now describes @Eray Hanoğlu diff --git a/docs/api.md b/docs/api.md index 855e284..e35e265 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,10 +1,10 @@ # flexy-buffer API Documentation diff --git a/package-lock.json b/package-lock.json index 0ec9d2b..36ccce4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "flexy-buffer", - "version": "1.1.0", + "version": "1.1.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "flexy-buffer", - "version": "1.1.0", + "version": "1.1.1", "license": "MIT", "dependencies": { "ts-gems": "^4.0.4", diff --git a/package.json b/package.json index 38ca0ea..ff5cee5 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "flexy-buffer", "description": "Flexible buffer for node.js and browser.", - "version": "1.1.0", + "version": "1.1.1", "author": "Panates", "license": "MIT", "private": true, diff --git a/src/buffer-reader.ts b/src/buffer-reader.ts index 07d9b42..93bf2d3 100644 --- a/src/buffer-reader.ts +++ b/src/buffer-reader.ts @@ -5,6 +5,11 @@ */ export class BufferReader { protected _position = 0; + /** + * The buffer being read from. Exposed directly so callers can inspect or + * patch its bytes directly (e.g. `buffer.writeUInt32BE(...)` to backpatch + * a value at an earlier offset) without going through the read cursor. + */ buffer: Buffer; /** @@ -30,12 +35,19 @@ export class BufferReader { return this._position; } + /** + * @param pos - Target position, clamped to [0, size]. + */ set position(pos: number) { this.moveTo(pos); } /** - * Reads a signed 8-bit integer + * Reads a signed 8-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 1 + * byte remains at the current position. */ readInt8(): number { this._checkReadable(1); @@ -45,7 +57,11 @@ export class BufferReader { } /** - * Reads an unsigned 8-bit integer + * Reads an unsigned 8-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 1 + * byte remains at the current position. */ readUInt8(): number { this._checkReadable(1); @@ -55,7 +71,11 @@ export class BufferReader { } /** - * Reads a signed, big-endian 16-bit integer + * Reads a signed, big-endian 16-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 2 + * bytes remain at the current position. */ readInt16BE(): number { this._checkReadable(2); @@ -65,7 +85,11 @@ export class BufferReader { } /** - * Reads an unsigned, big-endian 16-bit integer + * Reads an unsigned, big-endian 16-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 2 + * bytes remain at the current position. */ readUInt16BE(): number { this._checkReadable(2); @@ -75,7 +99,11 @@ export class BufferReader { } /** - * Reads a signed, little-endian 16-bit integer + * Reads a signed, little-endian 16-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 2 + * bytes remain at the current position. */ readInt16LE(): number { this._checkReadable(2); @@ -85,7 +113,11 @@ export class BufferReader { } /** - * Reads an unsigned, little-endian 16-bit integer + * Reads an unsigned, little-endian 16-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 2 + * bytes remain at the current position. */ readUInt16LE(): number { this._checkReadable(2); @@ -95,7 +127,11 @@ export class BufferReader { } /** - * Reads a signed, big-endian 32-bit integer + * Reads a signed, big-endian 32-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 4 + * bytes remain at the current position. */ readInt32BE(): number { this._checkReadable(4); @@ -105,7 +141,11 @@ export class BufferReader { } /** - * Reads an unsigned, big-endian 32-bit integer + * Reads an unsigned, big-endian 32-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 4 + * bytes remain at the current position. */ readUInt32BE(): number { this._checkReadable(4); @@ -115,7 +155,11 @@ export class BufferReader { } /** - * Reads a signed, little-endian 32-bit integer + * Reads a signed, little-endian 32-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 4 + * bytes remain at the current position. */ readInt32LE(): number { this._checkReadable(4); @@ -125,7 +169,11 @@ export class BufferReader { } /** - * Reads an unsigned, little-endian 32-bit integer + * Reads an unsigned, little-endian 32-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 4 + * bytes remain at the current position. */ readUInt32LE(): number { this._checkReadable(4); @@ -135,7 +183,11 @@ export class BufferReader { } /** - * Reads a signed, big-endian 64-bit integer + * Reads a signed, big-endian 64-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 8 + * bytes remain at the current position. */ readBigInt64BE(): BigInt { this._checkReadable(8); @@ -145,7 +197,11 @@ export class BufferReader { } /** - * Reads an unsigned, big-endian 64-bit integer + * Reads an unsigned, big-endian 64-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 8 + * bytes remain at the current position. */ readBigUInt64BE(): BigInt { this._checkReadable(8); @@ -155,7 +211,11 @@ export class BufferReader { } /** - * Reads a signed, little-endian 64-bit integer + * Reads a signed, little-endian 64-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 8 + * bytes remain at the current position. */ readBigInt64LE(): BigInt { this._checkReadable(8); @@ -165,7 +225,11 @@ export class BufferReader { } /** - * Reads an unsigned, little-endian 64-bit integer + * Reads an unsigned, little-endian 64-bit integer. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 8 + * bytes remain at the current position. */ readBigUInt64LE(): BigInt { this._checkReadable(8); @@ -175,7 +239,11 @@ export class BufferReader { } /** - * Reads a 32-bit, big-endian float + * Reads a 32-bit, big-endian float. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 4 + * bytes remain at the current position. */ readFloatBE(): number { this._checkReadable(4); @@ -185,7 +253,11 @@ export class BufferReader { } /** - * Reads a 32-bit, little-endian float + * Reads a 32-bit, little-endian float. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 4 + * bytes remain at the current position. */ readFloatLE(): number { this._checkReadable(4); @@ -195,7 +267,11 @@ export class BufferReader { } /** - * Reads a 64-bit, little-endian double + * Reads a 64-bit, big-endian double. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 8 + * bytes remain at the current position. */ readDoubleBE(): number { this._checkReadable(8); @@ -205,7 +281,11 @@ export class BufferReader { } /** - * Reads a 64-bit, big-endian double + * Reads a 64-bit, little-endian double. + * + * @returns The decoded value. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if fewer than 8 + * bytes remain at the current position. */ readDoubleLE(): number { this._checkReadable(8); @@ -219,6 +299,9 @@ export class BufferReader { * * @param len - Number of bytes to read. If omitted, reads through the end * of the buffer. + * @returns A `Buffer` view over the read bytes (not a copy). + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if `len` is given + * and that many bytes aren't available. */ readBytes(len?: number): Buffer { if (len) this._checkReadable(len); @@ -234,6 +317,9 @@ export class BufferReader { * @param len - Number of bytes to read. A negative length reads nothing * and returns an empty string. * @param encoding - Text encoding used to decode the bytes. + * @returns The decoded string. + * @throws An error with code 'ERR_BUFFER_OUT_OF_BOUNDS' if `len` is + * non-negative and that many bytes aren't available. */ readString(len: number, encoding?: BufferEncoding): string { if (len < 0) return ''; diff --git a/src/flexy-buffer.ts b/src/flexy-buffer.ts index afd4104..ff56764 100644 --- a/src/flexy-buffer.ts +++ b/src/flexy-buffer.ts @@ -57,6 +57,9 @@ export class FlexyBuffer extends BufferReader { return this._houseKeepMs; } + /** + * @param value - New idle interval in milliseconds. + */ set houseKeepMs(value: number) { this._houseKeepMs = value; if (this._houseKeepTimer) this._startHouseKeepTimer(); @@ -210,7 +213,8 @@ export class FlexyBuffer extends BufferReader { * the inserted bytes. * * @param buffer - Bytes to insert. - * @returns The number of bytes the buffer grew by to make room. + * @returns The number of bytes inserted (always `buffer.length`; `size` + * grows by the same amount). */ insertBytes(buffer: Buffer | number[]): number { const actual = buffer.length - Math.min(this.size - this._position, 0);