extended-buffer 7.3.1 → 7.5.0

package/README.md

@@ -14,6 +14,90 @@ npm install extended-buffer
 
 ---
 
+## Browser usage (bundlers)
+
+`ExtendedBuffer` works in browsers **as long as a Buffer polyfill is available**. Most bundlers can use the `buffer`
+package as a drop-in implementation.
+
+Install the polyfill:
+
+```bash
+npm install buffer
+```
+
+If your bundler does not expose `Buffer` globally, add a small shim in your app entry:
+
+```ts
+import { Buffer } from "buffer";
+
+if (!globalThis.Buffer) {
+  globalThis.Buffer = Buffer;
+}
+```
+
+### Webpack 5
+
+```js
+// webpack.config.js
+const webpack = require("webpack");
+
+module.exports = {
+  resolve: {
+    fallback: {
+      buffer: require.resolve("buffer/")
+    }
+  },
+  plugins: [
+    new webpack.ProvidePlugin({
+      Buffer: ["buffer", "Buffer"]
+    })
+  ]
+};
+```
+
+### Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      buffer: "buffer"
+    }
+  },
+  optimizeDeps: {
+    include: ["buffer"]
+  }
+});
+```
+
+### Rollup
+
+```js
+// rollup.config.js
+import resolve from "@rollup/plugin-node-resolve";
+import commonjs from "@rollup/plugin-commonjs";
+import inject from "@rollup/plugin-inject";
+
+export default {
+  plugins: [
+    resolve({ browser: true, preferBuiltins: false }),
+    commonjs(),
+    inject({
+      Buffer: ["buffer", "Buffer"]
+    })
+  ]
+};
+```
+
+Notes:
+- BigInt read/write methods require a polyfill that supports Node’s BigInt Buffer APIs.
+- If your tooling already provides a Buffer global, you can skip the shim/inject steps.
+
+---
+
 ## Quick start
 
 ```ts
@@ -44,12 +128,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 +169,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 +191,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
@@ -400,10 +538,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)`

package/dist/ExtendedBuffer.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type { ExtendedBufferOptions } from './ExtendedBufferOptions';
 import type { ExtendedBufferTransaction } from './ExtendedBufferTransaction';
 export declare class ExtendedBuffer<EBO extends ExtendedBufferOptions = ExtendedBufferOptions> {
@@ -18,7 +17,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

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExtendedBuffer = void 0;
 const buffer_1 = require("buffer");
@@ -29,6 +39,7 @@ const utils = __importStar(require("./utils"));
 const errors_1 = require("./errors");
 const DEFAULT_CAPACITY = 16 * 1024;
 const DEFAULT_CAPACITY_STEP = DEFAULT_CAPACITY;
+const globalScope = utils.getGlobalContext();
 class ExtendedBuffer {
     constructor(options) {
         var _a, _b;
@@ -38,7 +49,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 +75,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) ||
@@ -109,7 +132,6 @@ class ExtendedBuffer {
         if (this._transaction) {
             return callback();
         }
-        this.assertInstanceState();
         this._transaction = {
             pointer: this._pointer,
             pointerEnd: this._pointerEnd,
@@ -201,8 +223,8 @@ class ExtendedBuffer {
         return this;
     }
     nodeGc() {
-        if (typeof global.gc === 'function') {
-            global.gc();
+        if (typeof (globalScope === null || globalScope === void 0 ? void 0 : globalScope.gc) === 'function') {
+            globalScope.gc();
         }
         return this;
     }

package/dist/ExtendedBufferOptions.d.ts

@@ -3,4 +3,5 @@ export type ExtendedBufferOptions = {
     capacityStep?: number;
     nativeAllocSlow?: boolean;
     nativeReallocSlow?: boolean;
+    initNativeBuffer?: Buffer;
 };

package/dist/ExtendedBufferTransaction.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 export type ExtendedBufferTransaction = {
     pointer: number;
     pointerEnd: number;

package/dist/utils/alloc-native-buffer.d.ts

@@ -1,2 +1 @@
-/// <reference types="node" />
 export declare function allocNativeBuffer(size: number, allocSlow?: boolean): Buffer;

package/dist/utils/alloc-native-buffer.js

@@ -1,34 +1,17 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.allocNativeBuffer = void 0;
-const os = __importStar(require("os"));
+exports.allocNativeBuffer = allocNativeBuffer;
 const buffer_1 = require("buffer");
 const errors_1 = require("../errors");
 const assert_unsigned_integer_1 = require("./assert-unsigned-integer");
-const maxBufferSize = Math.min(buffer_1.kMaxLength, os.totalmem());
+const maxBufferSize = typeof buffer_1.kMaxLength === 'number'
+    ? buffer_1.kMaxLength
+    : typeof buffer_1.Buffer.kMaxLength === 'number'
+        ? buffer_1.Buffer.kMaxLength
+        : typeof ((_a = buffer_1.Buffer.constants) === null || _a === void 0 ? void 0 : _a.MAX_LENGTH) === 'number'
+            ? buffer_1.Buffer.constants.MAX_LENGTH
+            : Number.MAX_SAFE_INTEGER;
 (0, assert_unsigned_integer_1.assertUnsignedInteger)(maxBufferSize);
 function allocNativeBuffer(size, allocSlow) {
     (0, assert_unsigned_integer_1.assertUnsignedInteger)(size);
@@ -37,4 +20,3 @@ function allocNativeBuffer(size, allocSlow) {
     }
     return allocSlow ? buffer_1.Buffer.allocUnsafeSlow(size) : buffer_1.Buffer.allocUnsafe(size);
 }
-exports.allocNativeBuffer = allocNativeBuffer;

package/dist/utils/assert-big-integer.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertBigInteger = void 0;
+exports.assertBigInteger = assertBigInteger;
 const errors_1 = require("../errors");
 function assertBigInteger(value) {
     if (typeof value !== 'bigint') {
         throw new errors_1.ExtendedBufferTypeError('VALUE_MUST_BE_AN_BIG_INTEGER');
     }
 }
-exports.assertBigInteger = assertBigInteger;

package/dist/utils/assert-integer-size.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertIntegerSize = void 0;
+exports.assertIntegerSize = assertIntegerSize;
 const errors_1 = require("../errors");
 function assertIntegerSize(value) {
     if (!Number.isSafeInteger(value)) {
@@ -10,4 +10,3 @@ function assertIntegerSize(value) {
         throw new errors_1.ExtendedBufferRangeError('INVALID_INTEGER_SIZE_VALUE_RANGE');
     }
 }
-exports.assertIntegerSize = assertIntegerSize;

package/dist/utils/assert-integer.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertInteger = void 0;
+exports.assertInteger = assertInteger;
 const errors_1 = require("../errors");
 function assertInteger(value) {
     if (!Number.isSafeInteger(value)) {
         throw new errors_1.ExtendedBufferTypeError('VALUE_MUST_BE_AN_INTEGER');
     }
 }
-exports.assertInteger = assertInteger;

package/dist/utils/assert-support-big-integer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertSupportBigInteger = void 0;
+exports.assertSupportBigInteger = assertSupportBigInteger;
 const buffer_1 = require("buffer");
 const errors_1 = require("../errors");
 function assertSupportBigInteger() {
@@ -13,4 +13,3 @@ function assertSupportBigInteger() {
         throw new errors_1.ExtendedBufferUnsupportedError('EXECUTION_ENVIRONMENT_NOT_SUPPORT_BIG_INT');
     }
 }
-exports.assertSupportBigInteger = assertSupportBigInteger;

package/dist/utils/assert-unsigned-big-integer.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertUnsignedBigInteger = void 0;
+exports.assertUnsignedBigInteger = assertUnsignedBigInteger;
 const errors_1 = require("../errors");
 function assertUnsignedBigInteger(value) {
     if (typeof value !== 'bigint' || value < 0) {
         throw new errors_1.ExtendedBufferTypeError('VALUE_MUST_BE_AN_UNSIGNED_BIG_INTEGER');
     }
 }
-exports.assertUnsignedBigInteger = assertUnsignedBigInteger;

package/dist/utils/assert-unsigned-integer.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertUnsignedInteger = void 0;
+exports.assertUnsignedInteger = assertUnsignedInteger;
 const errors_1 = require("../errors");
 function assertUnsignedInteger(value) {
     if (!Number.isSafeInteger(value) || value < 0) {
         throw new errors_1.ExtendedBufferTypeError('VALUE_MUST_BE_AN_UNSIGNED_INTEGER');
     }
 }
-exports.assertUnsignedInteger = assertUnsignedInteger;

package/dist/utils/get-global-context.d.ts

@@ -0,0 +1 @@
+export declare function getGlobalContext(): NodeJS.Global | undefined;

package/dist/utils/get-global-context.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGlobalContext = getGlobalContext;
+function getGlobalContext() {
+    if (typeof globalThis !== 'undefined') {
+        return globalThis;
+    }
+    if (typeof self !== 'undefined') {
+        return self;
+    }
+    if (typeof window !== 'undefined') {
+        return window;
+    }
+    if (typeof global !== 'undefined') {
+        return global;
+    }
+    try {
+        return Function('return this')();
+    }
+    catch (_a) {
+        return undefined;
+    }
+}

package/dist/utils/index.d.ts

@@ -1,5 +1,6 @@
 export { assertInteger } from './assert-integer';
 export { assertBigInteger } from './assert-big-integer';
+export { getGlobalContext } from './get-global-context';
 export { assertIntegerSize } from './assert-integer-size';
 export { allocNativeBuffer } from './alloc-native-buffer';
 export { reallocNativeBuffer } from './realloc-native-buffer';

package/dist/utils/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertUnsignedBigInteger = exports.assertSupportBigInteger = exports.assertUnsignedInteger = exports.nativeBufferSubarray = exports.reallocNativeBuffer = exports.allocNativeBuffer = exports.assertIntegerSize = exports.assertBigInteger = exports.assertInteger = void 0;
+exports.assertUnsignedBigInteger = exports.assertSupportBigInteger = exports.assertUnsignedInteger = exports.nativeBufferSubarray = exports.reallocNativeBuffer = exports.allocNativeBuffer = exports.assertIntegerSize = exports.getGlobalContext = exports.assertBigInteger = exports.assertInteger = void 0;
 var assert_integer_1 = require("./assert-integer");
 Object.defineProperty(exports, "assertInteger", { enumerable: true, get: function () { return assert_integer_1.assertInteger; } });
 var assert_big_integer_1 = require("./assert-big-integer");
 Object.defineProperty(exports, "assertBigInteger", { enumerable: true, get: function () { return assert_big_integer_1.assertBigInteger; } });
+var get_global_context_1 = require("./get-global-context");
+Object.defineProperty(exports, "getGlobalContext", { enumerable: true, get: function () { return get_global_context_1.getGlobalContext; } });
 var assert_integer_size_1 = require("./assert-integer-size");
 Object.defineProperty(exports, "assertIntegerSize", { enumerable: true, get: function () { return assert_integer_size_1.assertIntegerSize; } });
 var alloc_native_buffer_1 = require("./alloc-native-buffer");

package/dist/utils/native-buffer-subarray.d.ts

@@ -1,2 +1 @@
-/// <reference types="node" />
 export declare function nativeBufferSubarray(buffer: Buffer, begin?: number, end?: number): Buffer;

package/dist/utils/native-buffer-subarray.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nativeBufferSubarray = void 0;
+exports.nativeBufferSubarray = nativeBufferSubarray;
 const buffer_1 = require("buffer");
 const sliceFallback = !(buffer_1.Buffer.allocUnsafe(1).subarray(0) instanceof buffer_1.Buffer);
 function nativeBufferSubarray(buffer, begin, end) {
     return sliceFallback ? buffer.slice(begin, end) : buffer.subarray(begin, end);
 }
-exports.nativeBufferSubarray = nativeBufferSubarray;

package/dist/utils/realloc-native-buffer.d.ts

@@ -1,2 +1 @@
-/// <reference types="node" />
 export declare function reallocNativeBuffer(buffer: Buffer, newSize: number, allocSlow?: boolean): Buffer;

package/dist/utils/realloc-native-buffer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reallocNativeBuffer = void 0;
+exports.reallocNativeBuffer = reallocNativeBuffer;
 const alloc_native_buffer_1 = require("./alloc-native-buffer");
 const assert_unsigned_integer_1 = require("./assert-unsigned-integer");
 function reallocNativeBuffer(buffer, newSize, allocSlow) {
@@ -12,4 +12,3 @@ function reallocNativeBuffer(buffer, newSize, allocSlow) {
     buffer.copy(newBuffer, 0, 0, Math.min(buffer.length, newBuffer.length));
     return newBuffer;
 }
-exports.reallocNativeBuffer = reallocNativeBuffer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extended-buffer",
-  "version": "7.3.1",
+  "version": "7.5.0",
   "description": "Node JS extended Buffer",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "npm run clean && node ./node_modules/.bin/tsc",
     "test": "node ./node_modules/.bin/mocha",
-    "coverage": "node ./node_modules/.bin/nyc --reporter=html --reporter=text ./node_modules/.bin/mocha",
+    "coverage": "node ./node_modules/.bin/nyc --reporter=lcov --reporter=html --reporter=text ./node_modules/.bin/mocha",
     "clean": "node -e \"['./dist', './coverage', './.nyc_output'].forEach(item => require('fs').rmSync(item, {recursive:true,force:true}));\"",
     "prepack": "npm run build"
   },
@@ -59,6 +59,6 @@
     "chai": "^4.5.0",
     "mocha": "^6.2.3",
     "nyc": "^11.9.0",
-    "typescript": "^4.7.2"
+    "typescript": "^5.9.3"
   }
 }