extended-buffer 7.4.0 → 7.5.1

package/README.md

@@ -14,6 +14,99 @@ 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";
+
+const globalScope: any =
+  typeof globalThis !== "undefined"
+    ? globalThis
+    : typeof self !== "undefined"
+      ? self
+      : typeof window !== "undefined"
+        ? window
+        : undefined;
+
+if (globalScope && !globalScope.Buffer) {
+  globalScope.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
@@ -316,6 +409,7 @@ Rules:
 
 - If the callback **returns normally**, changes are kept (committed).
 - If the callback **throws**, the buffer is restored (rolled back) and the error is re-thrown.
+- The callback must be **synchronous** (returned Promises are not awaited).
 - Transactions are **re-entrant**: nested `transaction()` calls do not create extra snapshots.
 
 What gets rolled back:
@@ -426,7 +520,7 @@ Common error codes you may see:
 - `VALUE_MUST_BE_AN_BIG_INTEGER`: value is not a `bigint`
 - `VALUE_MUST_BE_AN_UNSIGNED_BIG_INTEGER`: value is not a `bigint` or less than 0
 - `EXECUTION_ENVIRONMENT_NOT_SUPPORT_BIG_INT`: BigInt methods are not supported in the current runtime
-- `EXCEEDING_MAXIMUM_BUFFER_SIZE`: allocation exceeds Node’s `kMaxLength` or `os.totalmem()`
+- `EXCEEDING_MAXIMUM_BUFFER_SIZE`: allocation exceeds Node’s maximum buffer size (`kMaxLength` or `os.totalmem()` when available)
 
 ---
 
@@ -446,8 +540,8 @@ 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.
+`nodeGc()` calls `gc()` on the detected global object if it exists. In Node.js it requires starting the process with `--expose-gc`.
+In browsers/non-Node runtimes it simply no-ops.
 
 ---
 

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> {

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;
@@ -121,7 +132,6 @@ class ExtendedBuffer {
         if (this._transaction) {
             return callback();
         }
-        this.assertInstanceState();
         this._transaction = {
             pointer: this._pointer,
             pointerEnd: this._pointerEnd,
@@ -213,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

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 export type ExtendedBufferOptions = {
     capacity?: number;
     capacityStep?: number;

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,39 @@
 "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 totalMem = (function () {
+    try {
+        const req = typeof module !== 'undefined' && typeof module.require === 'function'
+            ? module.require.bind(module)
+            : typeof require === 'function'
+                ? require
+                : undefined;
+        if (!req) {
+            return undefined;
+        }
+        const os = req('os');
+        if (typeof (os === null || os === void 0 ? void 0 : os.totalmem) !== 'function') {
+            return undefined;
+        }
+        const result = os.totalmem();
+        return Number.isSafeInteger(result) && result > 0 ? result : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+})();
+const fallbackMaxLength = 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;
+const maxBufferSize = typeof totalMem === 'number' ? Math.min(fallbackMaxLength, totalMem) : fallbackMaxLength;
 (0, assert_unsigned_integer_1.assertUnsignedInteger)(maxBufferSize);
 function allocNativeBuffer(size, allocSlow) {
     (0, assert_unsigned_integer_1.assertUnsignedInteger)(size);
@@ -37,4 +42,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,16 +1,22 @@
 "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");
+const requiredMethods = [
+    'readBigUInt64LE',
+    'readBigUInt64BE',
+    'readBigInt64LE',
+    'readBigInt64BE',
+    'writeBigUInt64LE',
+    'writeBigUInt64BE',
+    'writeBigInt64LE',
+    'writeBigInt64BE'
+];
+const isSupported = typeof BigInt === 'function' &&
+    requiredMethods.every(method => typeof buffer_1.Buffer.prototype[method] === 'function');
 function assertSupportBigInteger() {
-    let isSupported = false;
-    try {
-        isSupported = typeof BigInt(0) === 'bigint';
-    }
-    catch (e) { }
-    if (!isSupported || typeof buffer_1.Buffer.prototype.readBigUInt64LE !== 'function') {
+    if (!isSupported) {
         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.4.0",
+  "version": "7.5.1",
   "description": "Node JS extended Buffer",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -16,9 +16,9 @@
   "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"
+    "prepack": "npm run build && npm run test"
   },
   "engines": {
     "node": ">=6.0.0"
@@ -59,6 +59,6 @@
     "chai": "^4.5.0",
     "mocha": "^6.2.3",
     "nyc": "^11.9.0",
-    "typescript": "^4.7.2"
+    "typescript": "^5.9.3"
   }
 }