From 16eea5dc89da3b232e0af14fabb15b550c35893b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Sun, 13 Sep 2026 09:42:32 +0300 Subject: [PATCH 1/3] Fill TSDoc gaps: buffer field, read-method @returns/@throws, setter @param - Document the previously-undocumented public buffer field - Add @returns to every read* method, matching the write* methods - Add @throws (ERR_BUFFER_OUT_OF_BOUNDS) to every read* method and to readBytes/readString, instead of relying solely on the class-level doc - Add a @param tag to the position and houseKeepMs setters - Clarify insertBytes' @returns wording (always buffer.length) --- src/buffer-reader.ts | 122 ++++++++++++++++++++++++++++++++++++------- src/flexy-buffer.ts | 6 ++- 2 files changed, 109 insertions(+), 19 deletions(-) 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); From 2de22b4e31bcffbebf8498055f06aeec8308d47f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Sun, 13 Sep 2026 09:42:48 +0300 Subject: [PATCH 2/3] Bump docs/api.md baseline to the commit it now describes --- docs/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 From 1297e2a85def8a193e9cab26d9e8959ed24ef8bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Sun, 13 Sep 2026 09:43:02 +0300 Subject: [PATCH 3/3] 1.1.1 --- CHANGELOG.md | 4 ++-- package-lock.json | 4 ++-- package.json | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) 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/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,