extended-buffer 7.3.0 → 7.4.0

package/README.md

@@ -44,12 +44,37 @@ The buffer stores a contiguous region of bytes. A separate **read pointer** trac
 ### 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:
+- `bufferView` — a **new `ExtendedBuffer` instance** that maps to the same bytes as `nativeBufferView` (**zero-copy**).  
+  The new instance starts with `pointer = 0`, so you can read/parse without consuming the parent buffer.
+
+If you need only unread bytes, you can derive it:
 
 ```ts
 const unread = b.nativeBufferView.subarray(b.pointer);
 ```
 
+Example: parse without touching the parent pointer:
+
+```ts
+import { ExtendedBuffer } from 'extended-buffer';
+
+const b = new ExtendedBuffer();
+b.writeString("OK");
+b.writeUInt16BE(1337);
+
+const v = b.bufferView;
+console.log(v.readString(2));   // "OK"
+console.log(v.readUInt16BE());  // 1337
+
+console.log(b.pointer);         // 0 (parent is untouched)
+```
+
+Notes:
+
+- `bufferView` shares memory with the parent. In-place mutations (e.g. `v.nativeBufferView[0] = 0xff`) will be visible in both.
+- The view usually has no spare head/tail capacity, so calling `v.write*()` will likely trigger a reallocation (copy) and then the two instances will diverge.
+
+
 ---
 
 ## Construction and options
@@ -60,6 +85,7 @@ type ExtendedBufferOptions = {
   capacityStep?: number;        // how much to grow when resizing
   nativeAllocSlow?: boolean;    // using Buffer.allocUnsafeSlow() when initializing ExtendedBuffer
   nativeReallocSlow?: boolean;  // using Buffer.allocUnsafeSlow() for further reallocations
+  initNativeBuffer?: Buffer;    // use an existing Buffer as the initial native buffer (no copy)
 };
 ```
 
@@ -81,6 +107,34 @@ const b = new ExtendedBuffer({
 });
 ```
 
+### Wrap an existing `Buffer` (`initNativeBuffer`)
+
+If you already have a Node.js `Buffer` (from a socket, file, etc.) and want to parse it with `ExtendedBuffer`
+**without copying**, pass it as `initNativeBuffer`.
+
+- The buffer is **not copied** — it becomes the internal `_nativeBuffer`.
+- The instance starts with `pointer = 0` and `length = initNativeBuffer.length`.
+
+```ts
+import { ExtendedBuffer } from 'extended-buffer';
+
+const packet = Buffer.from([0x00, 0x02, 0x4f, 0x4b]); // 2, "OK"
+
+const b = new ExtendedBuffer({ initNativeBuffer: packet });
+
+const len = b.readUInt16BE();
+console.log(b.readString(len)); // "OK"
+```
+
+You can also reuse an instance:
+
+```ts
+b.initExtendedBuffer(packet);
+```
+
+Note: when you construct from `initNativeBuffer`, the buffer is treated as already filled.
+If you later call `write*()`, it will typically require a reallocation (copy) to make room.
+
 ---
 
 ## Writing data
@@ -357,6 +411,7 @@ The library defines these error classes:
 - `ExtendedBufferError`
 - `ExtendedBufferTypeError`
 - `ExtendedBufferRangeError`
+- `ExtendedBufferUnsupportedError`
 
 Common error codes you may see:
 
@@ -365,6 +420,7 @@ Common error codes you may see:
 - `INVALID_INTEGER_SIZE_VALUE_TYPE`: size is not a safe integer
 - `INVALID_INTEGER_SIZE_VALUE_RANGE`: integer size not in `1…6`
 - `INVALID_INSTANCE_STATE`: internal invariant check failed
+- `INVALID_BUFFER_TYPE`: attempt write invalid buffer type
 - `VALUE_MUST_BE_AN_INTEGER`: value not a safe integer
 - `VALUE_MUST_BE_AN_UNSIGNED_INTEGER`: value is not a safe integer or less than 0
 - `VALUE_MUST_BE_AN_BIG_INTEGER`: value is not a `bigint`
@@ -398,10 +454,10 @@ In non-Node runtimes, `global` may not exist.
 ## Reference: full public API (names)
 
 Properties:
-- `length`, `capacity`, `pointer`, `nativeBufferView`
+- `length`, `capacity`, `pointer`, `nativeBufferView`, `bufferView`
 
 Core:
-- `initExtendedBuffer()`, `assertInstanceState()`, `clean()`
+- `initExtendedBuffer(initNativeBuffer?)`, `assertInstanceState()`, `clean()`
 - `nativePointer()`, `getWritableSizeStart()`, `getWritableSizeEnd()`, `getWritableSize()`, `getReadableSize()`
 - `transaction(callback)`
 - `allocStart(size)`, `allocEnd(size)`
@@ -419,3 +475,7 @@ Numbers:
   `readInt16BE/LE`, `readUInt16BE/LE`, `readInt32BE/LE`, `readUInt32BE/LE`,
   `readBigInt64BE/LE`, `readBigUInt64BE/LE`,
   `readFloatBE/LE`, `readDoubleBE/LE`
+
+## License
+
+MIT

package/dist/ExtendedBuffer.d.ts

@@ -18,7 +18,8 @@ export declare class ExtendedBuffer<EBO extends ExtendedBufferOptions = Extended
     get capacity(): number;
     get pointer(): number;
     get nativeBufferView(): Buffer;
-    initExtendedBuffer(): this;
+    get bufferView(): this;
+    initExtendedBuffer(initNativeBuffer?: Buffer): this;
     assertInstanceState(): this;
     clean(): this;
     nativePointer(): number;

package/dist/ExtendedBuffer.js

@@ -38,7 +38,7 @@ class ExtendedBuffer {
         this._capacityStep = (_b = options === null || options === void 0 ? void 0 : options.capacityStep) !== null && _b !== void 0 ? _b : DEFAULT_CAPACITY_STEP;
         utils.assertUnsignedInteger(this._capacity);
         utils.assertUnsignedInteger(this._capacityStep);
-        this.initExtendedBuffer();
+        this.initExtendedBuffer(options === null || options === void 0 ? void 0 : options.initNativeBuffer);
     }
     createInstanceOptions(options) {
         return Object.assign({
@@ -64,15 +64,27 @@ class ExtendedBuffer {
     get nativeBufferView() {
         return utils.nativeBufferSubarray(this._nativeBuffer, this._pointerStart, this._pointerEnd);
     }
-    initExtendedBuffer() {
+    get bufferView() {
+        return this.createInstance({
+            initNativeBuffer: this.nativeBufferView
+        });
+    }
+    initExtendedBuffer(initNativeBuffer) {
         this._pointer = 0;
-        this._nativeBuffer = utils.allocNativeBuffer(this._capacity, this._nativeAllocSlow);
-        this._pointerStart = this._pointerEnd = Math.floor(this._capacity / 2);
+        if (initNativeBuffer) {
+            this._nativeBuffer = initNativeBuffer;
+            this._pointerStart = 0;
+            this._pointerEnd = this._nativeBuffer.length;
+        }
+        else {
+            this._nativeBuffer = utils.allocNativeBuffer(this._capacity, this._nativeAllocSlow);
+            this._pointerStart = this._pointerEnd = Math.floor(this._capacity / 2);
+        }
         this.assertInstanceState();
         return this;
     }
     assertInstanceState() {
-        if (!this._nativeBuffer ||
+        if (!buffer_1.Buffer.isBuffer(this._nativeBuffer) ||
             !Number.isSafeInteger(this._pointer) ||
             !Number.isSafeInteger(this._pointerStart) ||
             !Number.isSafeInteger(this._pointerEnd) ||
@@ -229,7 +241,10 @@ class ExtendedBuffer {
         if (value instanceof ExtendedBuffer) {
             return this.writeNativeBuffer(value.nativeBufferView, unshift);
         }
-        return this.writeNativeBuffer(value, unshift);
+        if (buffer_1.Buffer.isBuffer(value)) {
+            return this.writeNativeBuffer(value, unshift);
+        }
+        throw new errors_1.ExtendedBufferTypeError('INVALID_BUFFER_TYPE');
     }
     writeString(string, encoding, unshift) {
         const bytes = buffer_1.Buffer.from(string, encoding);

package/dist/ExtendedBufferOptions.d.ts

@@ -1,6 +1,8 @@
+/// <reference types="node" />
 export type ExtendedBufferOptions = {
     capacity?: number;
     capacityStep?: number;
     nativeAllocSlow?: boolean;
     nativeReallocSlow?: boolean;
+    initNativeBuffer?: Buffer;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extended-buffer",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Node JS extended Buffer",
   "type": "commonjs",
   "main": "./dist/index.js",