extended-buffer 6.1.0 → 7.0.0

package/README.md

@@ -1,105 +1,284 @@
 [![npm version](https://badge.fury.io/js/extended-buffer.svg)](https://badge.fury.io/js/extended-buffer)
-# node-extended-buffer
-Node JS extended Buffer
 
-### Install
+# ExtendedBuffer
+
+`ExtendedBuffer` is a growable binary buffer built on top of Node.js `Buffer`.
+It keeps an internal **read pointer** (similar to a stream cursor) and supports **appending** data at the end or **prepending** data at the start.
+
+---
+
+## Install
 ```bash
-npm install extended-buffer --save
+npm install extended-buffer
 ```
 
-### class ExtendedBuffer
-```typescript
-export interface ExtendedBufferOptions {
-    maxBufferLength?: number;
-}
+---
+
+## Quick start
+
+```ts
+import { ExtendedBuffer } from 'extended-buffer';
+
+const b = new ExtendedBuffer();
+
+b.writeString("OK");          // append
+b.writeUInt16BE(1337);        // append
+
+console.log(b.readString(2)); // "OK"
+console.log(b.readUInt16BE()); // 1337
+```
+
+---
+
+## Core concepts
+
+### Stored data vs readable data
+
+The buffer stores a contiguous region of bytes. A separate **read pointer** tracks how many bytes were already consumed.
 
-export declare class ExtendedBuffer {
-    _maxBufferLength: number;
-    _pointer: number;
-    _pointerStart: number;
-    _pointerEnd: number;
-    _nativeBuffer: Buffer;
-    constructor(options?: ExtendedBufferOptions);
-    static readonly maxSize: number;
-    static concat<T extends ExtendedBuffer>(this: new () => T, list: ExtendedBuffer[], totalLength?: number): T;
-    static zigZagEncode32(value: number): number;
-    static zigZagDecode32(value: number): number;
-    readonly length: number;
-    readonly nativeLength: number;
-    readonly buffer: Buffer;
-    _initEmptyBuffer(): this;
-    clean(): this;
-    getFreeSpaceStart(): number;
-    getFreeSpaceEnd(): number;
-    getFreeSpace(): number;
-    allocStart(byteLength: number): this;
-    allocEnd(byteLength: number): this;
-    getReadableSize(): number;
-    getWritableSize(): number;
-    _writeNativeBuffer(buffer: Buffer, unshift?: boolean): this;
-    gc(): this;
-    nodeGc(): this;
-    setPointer(pointer: number): this;
-    getPointer(): number;
-    offset(offset: number): this;
-    isReadable(byteLength?: number): boolean;
-    isWritable(byteLength?: number): boolean;
-    toString(encoding?: string, start?: number, end?: number): string;
-    writeBuffer(value: Buffer | ExtendedBuffer, unshift?: boolean): this;
-    writeString(string: string, encoding?: string, unshift?: boolean): this;
-    writeIntBE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeIntLE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUIntBE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUIntLE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt8(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt8(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt16BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt16LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt16BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt16LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt32BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt32LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt32BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt32LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeFloatBE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeFloatLE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeDoubleBE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeDoubleLE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeVarInt32(value: number, unshift?: boolean): this;
-    readBuffer(size: number, asNative?: boolean, bufferOptions?: ExtendedBufferOptions): this | Buffer;
-    readString(size: number, encoding?: string): string;
-    readIntBE(byteLength: number, noAssert?: boolean): number;
-    readIntLE(byteLength: number, noAssert?: boolean): number;
-    readUIntBE(byteLength: number, noAssert?: boolean): number;
-    readUIntLE(byteLength: number, noAssert?: boolean): number;
-    readInt8(noAssert?: boolean): number;
-    readUInt8(noAssert?: boolean): number;
-    readInt16BE(noAssert?: boolean): number;
-    readInt16LE(noAssert?: boolean): number;
-    readUInt16BE(noAssert?: boolean): number;
-    readUInt16LE(noAssert?: boolean): number;
-    readInt32BE(noAssert?: boolean): number;
-    readInt32LE(noAssert?: boolean): number;
-    readUInt32BE(noAssert?: boolean): number;
-    readUInt32LE(noAssert?: boolean): number;
-    readFloatBE(noAssert?: boolean): number;
-    readFloatLE(noAssert?: boolean): number;
-    readDoubleBE(noAssert?: boolean): number;
-    readDoubleLE(noAssert?: boolean): number;
-    readVarInt32(): number;
-    isReadableVarInt32(): boolean;
+- `length` — total stored bytes (**including already-read bytes**).
+- `getReadableSize()` — unread bytes remaining.
+- `pointer` / `getPointer()` — current read pointer (0…`length`).
+- `nativePointer()` — absolute index inside the underlying `Buffer` for the next read.
+
+### Views
+
+- `nativeBufferView` — a `Buffer` view of **all stored bytes** (from the start of stored data to the end).
+- If you need only unread bytes, you can derive it:
+
+```ts
+const unread = b.nativeBufferView.subarray(b.pointer);
+```
+
+---
+
+## Construction and options
+
+```ts
+type ExtendedBufferOptions = {
+  capacity?: number;      // initial native buffer size (bytes)
+  capacityStep?: number;  // how much to grow when resizing
+};
+```
+
+Defaults (from source):
+
+- `capacity`: `512 * 1024` bytes (512 KiB)
+- `capacityStep`: same as `capacity`
+
+Example:
+
+```ts
+const b = new ExtendedBuffer({ capacity: 64 * 1024, capacityStep: 16 * 1024 });
+```
+
+---
+
+## Writing data
+
+Most write methods accept an optional `unshift?: boolean`:
+
+- `unshift = false` (default): append to the end
+- `unshift = true`: prepend to the start
+
+### Buffers and strings
+
+```ts
+b.writeNativeBuffer(Buffer.from([1, 2, 3]));
+b.writeBuffer(Buffer.from([4, 5, 6]));      // alias that also accepts ExtendedBuffer
+b.writeString("hello", "utf8");
+```
+
+Prepend example:
+
+```ts
+b.writeString("payload");
+b.writeUInt16BE(7, true); // prepend length/header
+```
+
+### Integers
+
+Variable-width (size must be **1…6** bytes):
+
+```ts
+b.writeIntBE(-10, 3);
+b.writeUIntLE(5000, 4);
+```
+
+Fixed-width helpers:
+
+- `writeInt8`, `writeUInt8`
+- `writeInt16BE`, `writeInt16LE`, `writeUInt16BE`, `writeUInt16LE`
+- `writeInt32BE`, `writeInt32LE`, `writeUInt32BE`, `writeUInt32LE`
+
+### Floating point
+
+- `writeFloatBE`, `writeFloatLE` (4 bytes)
+- `writeDoubleBE`, `writeDoubleLE` (8 bytes)
+
+---
+
+## Reading data
+
+All `read*` methods **advance** the internal read pointer (consume bytes).
+If there aren’t enough readable bytes, they throw `ExtendedBufferRangeError('SIZE_OUT_OF_RANGE')`.
+
+### Checking before reading
+
+```ts
+if (b.isReadable(4)) {
+  const x = b.readUInt32BE();
 }
 ```
 
-### Example 1:
-```js
-const { ExtendedBuffer } = require('extended-buffer');
-const buffer = new ExtendedBuffer;
-console.log(buffer.length); // 0
-buffer.writeInt32LE(123).writeInt32LE(456).writeInt32LE(789);
-console.log(buffer.length); // 12
+### Read a native `Buffer` or another `ExtendedBuffer`
+
+```ts
+// Copy out as a native Buffer
+const chunk: Buffer = b.readBuffer(10, true);
+
+// Copy out as a new ExtendedBuffer (same capacity/capacityStep by default)
+const eb: ExtendedBuffer = b.readBuffer(10);
+```
+
+### Strings
 
-console.log(buffer.readInt32LE()); // 123
-console.log(buffer.readInt32LE()); // 456
-console.log(buffer.readInt32LE()); // 789
+```ts
+const s = b.readString(5, "utf8");
 ```
+
+### Integers
+
+Variable-width (size **1…6** bytes):
+
+```ts
+const a = b.readIntBE(3);
+const u = b.readUIntLE(4);
+```
+
+Fixed-width helpers:
+
+- `readInt8`, `readUInt8`
+- `readInt16BE`, `readInt16LE`, `readUInt16BE`, `readUInt16LE`
+- `readInt32BE`, `readInt32LE`, `readUInt32BE`, `readUInt32LE`
+
+### Floating point
+
+- `readFloatBE`, `readFloatLE`
+- `readDoubleBE`, `readDoubleLE`
+
+---
+
+## Pointer control (peeking / rewinding)
+
+### Save pointer, read, then restore (peek)
+
+```ts
+const p = b.pointer;
+const header = b.readUInt16BE();
+
+// decide what to do...
+b.setPointer(p); // rewind back to before header
+```
+
+### Move relative to current position
+
+```ts
+b.offset(4);   // skip 4 bytes
+b.offset(-2);  // go back 2 bytes (must stay within 0…length)
+```
+
+If you try to set the pointer outside `[0, length]`, it throws
+`ExtendedBufferRangeError('POINTER_OUT_OF_RANGE')`.
+
+---
+
+## Memory management
+
+### Discard already-read data
+
+If you continuously read from the buffer, you can drop the consumed prefix:
+
+```ts
+b.discardReadData();
+```
+
+This moves the internal start forward by the number of read bytes and resets `pointer` to `0`.
+
+### Shrink free capacity (`gc()`)
+
+```ts
+b.gc();
+```
+
+`gc()` first discards read data, then may shrink the underlying native `Buffer`
+when free space exceeds `capacityStep`.
+
+### Reset everything
+
+```ts
+b.clean(); // alias for initExtendedBuffer()
+```
+
+---
+
+## Errors
+
+The library defines these error classes:
+
+- `ExtendedBufferError`
+- `ExtendedBufferTypeError`
+- `ExtendedBufferRangeError`
+
+Common error codes you may see:
+
+- `SIZE_OUT_OF_RANGE` (reading more bytes than available)
+- `POINTER_OUT_OF_RANGE` (setting pointer outside `0…length`)
+- `INVALID_INTEGER_SIZE_VALUE_RANGE` (integer size not in `1…6`)
+- `EXCEEDING_MAXIMUM_BUFFER_SIZE` (allocation exceeds Node’s `kMaxLength`)
+- `INVALID_INSTANCE_STATE` (internal invariant check failed)
+
+---
+
+## Caveats
+
+### Prepending (`unshift`) after reading
+
+`unshift=true` prepends bytes by moving the internal start pointer, but the read pointer is **not adjusted** automatically.
+If you prepend after consuming bytes, you may get surprising results (e.g., some previously read bytes can become readable again, or newly prepended bytes may be skipped).
+
+A safe pattern is:
+
+```ts
+b.discardReadData();
+b.writeUInt16BE(123, true);
+```
+
+### `nodeGc()` is Node-specific
+
+`nodeGc()` calls `global.gc()` if it exists. In Node.js it requires starting the process with `--expose-gc`.
+In non-Node runtimes, `global` may not exist.
+
+---
+
+## Reference: full public API (names)
+
+Properties:
+- `length`, `capacity`, `pointer`, `nativeBufferView`
+
+Core:
+- `initExtendedBuffer()`, `assertInstanceState()`, `clean()`
+- `nativePointer()`, `getWritableSizeStart()`, `getWritableSizeEnd()`, `getWritableSize()`, `getReadableSize()`
+- `allocStart(size)`, `allocEnd(size)`
+- `writeNativeBuffer(buf, unshift?)`, `writeBuffer(bufOrEB, unshift?)`, `writeString(str, enc?, unshift?)`
+- Pointer: `setPointer(p)`, `getPointer()`, `offset(n)`, `isReadable(size)`
+- Maintenance: `discardReadData()`, `gc()`, `nodeGc()`
+
+Numbers:
+- Write: `writeIntBE/LE`, `writeUIntBE/LE`, `writeInt8`, `writeUInt8`,
+  `writeInt16BE/LE`, `writeUInt16BE/LE`, `writeInt32BE/LE`, `writeUInt32BE/LE`,
+  `writeFloatBE/LE`, `writeDoubleBE/LE`
+- Read: `readBuffer`, `readString`,
+  `readIntBE/LE`, `readUIntBE/LE`, `readInt8`, `readUInt8`,
+  `readInt16BE/LE`, `readUInt16BE/LE`, `readInt32BE/LE`, `readUInt32BE/LE`,
+  `readFloatBE/LE`, `readDoubleBE/LE`

package/dist/ExtendedBuffer.d.ts

@@ -1,81 +1,76 @@
 /// <reference types="node" />
-import { ExtendedBufferOptions } from './ExtendedBufferOptions';
+import type { ExtendedBufferOptions } from './ExtendedBufferOptions';
 export declare class ExtendedBuffer {
-    _pointer: number;
-    _pointerEnd: number;
-    _pointerStart: number;
-    _nativeBuffer: Buffer;
-    _maxBufferLength: number;
+    protected _pointer: number;
+    protected _pointerEnd: number;
+    protected _pointerStart: number;
+    protected _nativeBuffer: Buffer;
+    protected readonly _capacity: number;
+    protected readonly _capacityStep: number;
     constructor(options?: ExtendedBufferOptions);
-    static get maxSize(): number;
-    static concat<T extends ExtendedBuffer>(this: new (options?: ExtendedBufferOptions) => T, list: ExtendedBuffer[], totalLength?: number): T;
-    static zigZagEncode32(value: number): number;
-    static zigZagDecode32(value: number): number;
+    protected createInstance(options?: ExtendedBufferOptions): this;
     get length(): number;
-    get nativeLength(): number;
-    get buffer(): Buffer;
-    _initEmptyBuffer(): this;
+    get capacity(): number;
+    get pointer(): number;
+    get nativeBufferView(): Buffer;
+    initExtendedBuffer(): this;
+    assertInstanceState(): this;
     clean(): this;
-    getFreeSpaceStart(): number;
-    getFreeSpaceEnd(): number;
-    getFreeSpace(): number;
-    allocStart(byteLength: number): this;
-    allocEnd(byteLength: number): this;
-    getReadableSize(): number;
+    nativePointer(): number;
+    getWritableSizeStart(): number;
+    getWritableSizeEnd(): number;
     getWritableSize(): number;
-    _writeNativeBuffer(buffer: Buffer, unshift?: boolean): this;
+    allocStart(size: number): this;
+    allocEnd(size: number): this;
+    getReadableSize(): number;
+    writeNativeBuffer(buffer: Buffer, unshift?: boolean): this;
     gc(): this;
+    discardReadData(): this;
     nodeGc(): this;
     setPointer(pointer: number): this;
     getPointer(): number;
     offset(offset: number): this;
-    isReadable(byteLength: number): boolean;
-    isWritable(byteLength?: number): boolean;
-    toString(encoding?: string, start?: number, end?: number): string;
+    isReadable(size: number): boolean;
     writeBuffer(value: Buffer | ExtendedBuffer, unshift?: boolean): this;
-    writeString(string: string, encoding?: string, unshift?: boolean): this;
-    writeIntBE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeIntLE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUIntBE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUIntLE(value: number, byteLength: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt8(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt8(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt16BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt16LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt16BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt16LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt32BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeInt32LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt32BE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeUInt32LE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeFloatBE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeFloatLE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeDoubleBE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeDoubleLE(value: number, unshift?: boolean, noAssert?: boolean): this;
-    writeVarInt32(value: number, unshift?: boolean): this;
+    writeString(string: string, encoding?: BufferEncoding, unshift?: boolean): this;
+    writeIntBE(value: number, size: number, unshift?: boolean): this;
+    writeIntLE(value: number, size: number, unshift?: boolean): this;
+    writeUIntBE(value: number, size: number, unshift?: boolean): this;
+    writeUIntLE(value: number, size: number, unshift?: boolean): this;
+    writeInt8(value: number, unshift?: boolean): this;
+    writeUInt8(value: number, unshift?: boolean): this;
+    writeInt16BE(value: number, unshift?: boolean): this;
+    writeInt16LE(value: number, unshift?: boolean): this;
+    writeUInt16BE(value: number, unshift?: boolean): this;
+    writeUInt16LE(value: number, unshift?: boolean): this;
+    writeInt32BE(value: number, unshift?: boolean): this;
+    writeInt32LE(value: number, unshift?: boolean): this;
+    writeUInt32BE(value: number, unshift?: boolean): this;
+    writeUInt32LE(value: number, unshift?: boolean): this;
+    writeFloatBE(value: number, unshift?: boolean): this;
+    writeFloatLE(value: number, unshift?: boolean): this;
+    writeDoubleBE(value: number, unshift?: boolean): this;
+    writeDoubleLE(value: number, unshift?: boolean): this;
     readBuffer(size: number): this;
+    readBuffer(size: number, asNative: true): Buffer;
     readBuffer(size: number, asNative: false, bufferOptions?: ExtendedBufferOptions): this;
-    readBuffer(size: number, asNative: true, bufferOptions?: ExtendedBufferOptions): Buffer;
-    readBuffer(size: number, asNative?: boolean, bufferOptions?: ExtendedBufferOptions): this | Buffer;
-    readString(size: number, encoding?: string): string;
-    readIntBE(byteLength: number, noAssert?: boolean): number;
-    readIntLE(byteLength: number, noAssert?: boolean): number;
-    readUIntBE(byteLength: number, noAssert?: boolean): number;
-    readUIntLE(byteLength: number, noAssert?: boolean): number;
-    readInt8(noAssert?: boolean): number;
-    readUInt8(noAssert?: boolean): number;
-    readInt16BE(noAssert?: boolean): number;
-    readInt16LE(noAssert?: boolean): number;
-    readUInt16BE(noAssert?: boolean): number;
-    readUInt16LE(noAssert?: boolean): number;
-    readInt32BE(noAssert?: boolean): number;
-    readInt32LE(noAssert?: boolean): number;
-    readUInt32BE(noAssert?: boolean): number;
-    readUInt32LE(noAssert?: boolean): number;
-    readFloatBE(noAssert?: boolean): number;
-    readFloatLE(noAssert?: boolean): number;
-    readDoubleBE(noAssert?: boolean): number;
-    readDoubleLE(noAssert?: boolean): number;
-    readVarInt32(): number;
-    isReadableVarInt32(): boolean;
+    readString(size: number, encoding?: BufferEncoding): string;
+    readIntBE(size: number): number;
+    readIntLE(size: number): number;
+    readUIntBE(size: number): number;
+    readUIntLE(size: number): number;
+    readInt8(): number;
+    readUInt8(): number;
+    readInt16BE(): number;
+    readInt16LE(): number;
+    readUInt16BE(): number;
+    readUInt16LE(): number;
+    readInt32BE(): number;
+    readInt32LE(): number;
+    readUInt32BE(): number;
+    readUInt32LE(): number;
+    readFloatBE(): number;
+    readFloatLE(): number;
+    readDoubleBE(): number;
+    readDoubleLE(): number;
 }