@ad-sdk/bgd 0.0.1

package/allocators/buffer.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Copyright © 2026 Alerta Dino. All rights reserved.
+ *
+ * This code was released under the BSD 3-Clause License.
+ * See the "LICENSE" file under project root.
+ *
+ * @author (PUBLIC_ID) 1D-C2-9B-98-D6-C3-D6-AB
+ * @signphrase It was created on Earth by humans, although
+ *             I can't define what a "human" is.
+ */
+import { type ImplicitArrayBuffer, type WithImplicitCoercion } from "node:buffer";
+import { IDebugString } from "../lifecycle/debugger";
+import { IDisposable } from "../lifecycle/disposable";
+/**
+ * Provides a scoped wrapper around Node `Buffer` with
+ * explicit zeroization and access checks.
+ */
+export declare class MemoryBuffer<T extends ArrayBuffer | SharedArrayBuffer = ArrayBufferLike> implements IDisposable, IDebugString {
+    #private;
+    /**
+     * Allocates a new zero-filled `Buffer` in heap.
+     */
+    static alloc(sizeInBytes: number): MemoryBuffer<ArrayBuffer>;
+    /**
+     * Using `from()` method may allocate a oversized buffer.
+     *
+     * It also can share memory with an external resource when
+     * called with `ArrayBuffer` instance, invalidating disposal logic.
+     *
+     * @advice
+     * Prefer to use`alloc()` with specific needed memory size.
+     */
+    static from(string: WithImplicitCoercion<string>, encoding?: BufferEncoding): MemoryBuffer<ArrayBuffer>;
+    /**
+     * Using `from()` method may allocate a oversized buffer.
+     *
+     * It also can share memory with an external resource when
+     * called with `ArrayBuffer` instance, invalidating disposal logic.
+     *
+     * @advice
+     * Prefer to use`alloc()` with specific needed memory size.
+     */
+    static from(arrayOrString: WithImplicitCoercion<ArrayLike<number> | string>): MemoryBuffer<ArrayBuffer>;
+    /**
+     * Using `from()` method may allocate a oversized buffer.
+     *
+     * It also can share memory with an external resource when
+     * called with `ArrayBuffer` instance, invalidating disposal logic.
+     *
+     * @advice
+     * Prefer to use`alloc()` with specific needed memory size.
+     */
+    static from(array: WithImplicitCoercion<ArrayLike<number>>): MemoryBuffer<ArrayBuffer>;
+    static from<TArrayBuffer extends WithImplicitCoercion<ArrayBufferLike>>(arrayBuffer: TArrayBuffer, byteOffset?: number, length?: number): MemoryBuffer<ImplicitArrayBuffer<TArrayBuffer>>;
+    private constructor();
+    get byteLength(): number;
+    get byteOffset(): number;
+    get disposed(): boolean;
+    setByte(index: number, val: number): void;
+    getByte(index: number): number;
+    writeUint8(val: number, offset?: number): number;
+    writeInt8(val: number, offset?: number): number;
+    writeUint16(val: number, offset?: number, enc?: "BE" | "LE"): number;
+    writeInt16(val: number, offset?: number, enc?: "BE" | "LE"): number;
+    writeUint32(val: number, offset?: number, enc?: "BE" | "LE"): number;
+    writeInt32(val: number, offset?: number, enc?: "BE" | "LE"): number;
+    writeUint64(val: bigint, offset?: number, enc?: "BE" | "LE"): number;
+    writeInt64(val: bigint, offset?: number, enc?: "BE" | "LE"): number;
+    writeFloat(val: number, offset?: number, enc?: "BE" | "LE"): number;
+    writeDouble(val: number, offset?: number, enc?: "BE" | "LE"): number;
+    readUint8(offset?: number): number;
+    readInt8(offset?: number): number;
+    readUint16(offset?: number, enc?: "BE" | "LE"): number;
+    readInt16(offset?: number, enc?: "BE" | "LE"): number;
+    readUint32(offset?: number, enc?: "BE" | "LE"): number;
+    readInt32(offset?: number, enc?: "BE" | "LE"): number;
+    readUint64(offset?: number, enc?: "BE" | "LE"): bigint;
+    readInt64(offset?: number, enc?: "BE" | "LE"): bigint;
+    readFloat(offset?: number, enc?: "BE" | "LE"): number;
+    readDouble(offset?: number, enc?: "BE" | "LE"): number;
+    copy(target: Uint8Array | MemoryBuffer<ArrayBufferLike>, targetStart?: number, sourceStart?: number, sourceEnd?: number): number;
+    indexOf(value: string | number | Uint8Array | MemoryBuffer<ArrayBufferLike>, encoding: BufferEncoding): number;
+    indexOf(value: string | number | Uint8Array | MemoryBuffer<ArrayBufferLike>, byteOffset?: number, encoding?: BufferEncoding): number;
+    lastIndexOf(value: string | number | Uint8Array | MemoryBuffer<ArrayBufferLike>, encoding: BufferEncoding): number;
+    lastIndexOf(value: string | number | Uint8Array | MemoryBuffer<ArrayBufferLike>, byteOffset?: number, encoding?: BufferEncoding): number;
+    compare(target: Uint8Array | MemoryBuffer<ArrayBufferLike>, targetStart?: number, targetEnd?: number, sourceStart?: number, sourceEnd?: number): -1 | 0 | 1;
+    equals(other: Uint8Array | MemoryBuffer<ArrayBufferLike>): boolean;
+    reverse(): this;
+    toReversed(): MemoryBuffer<ArrayBuffer>;
+    subarray(start?: number, end?: number): MemoryBuffer<T>;
+    toString(enc?: BufferEncoding, start?: number, end?: number): string;
+    /**
+     * **ATTENTION:** If you use this function make sure that
+     * will not create an external reference of the buffer, or it'll
+     * invalidate the disposal logic resulting in a memory leak.
+     */
+    valueOf(secure?: true): Buffer;
+    /**
+     * **ATTENTION:** If you use this function make sure that
+     * will not create an external reference of the buffer, or it'll
+     * invalidate the disposal logic resulting in a memory leak.
+     */
+    valueOf(secure: false): Buffer | null;
+    /**
+     * Clear current buffer and free allocated memory.
+     *
+     * **ATTENTION:** It won't work if the `MemoryBuffer` was created
+     * from external memory. When you call `from()` with an `ArrayBuffer`
+     * instance, or something like this, the owner of memory reference is the
+     * external instance, so we can't dispose it.
+     */
+    dispose(): void;
+    $$debug(r?: true): string;
+    $$debug(r: false): void;
+}

package/allocators/buffer.js

@@ -0,0 +1,409 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MemoryBuffer = void 0;
+var _util = require("../util");
+var _errors = require("../errors");
+function _classPrivateMethodInitSpec(e, a) { _checkPrivateRedeclaration(e, a), a.add(e); }
+function _classPrivateFieldInitSpec(e, t, a) { _checkPrivateRedeclaration(e, t), t.set(e, a); }
+function _checkPrivateRedeclaration(e, t) { if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object"); }
+function _classPrivateFieldGet(s, a) { return s.get(_assertClassBrand(s, a)); }
+function _classPrivateFieldSet(s, a, r) { return s.set(_assertClassBrand(s, a), r), r; }
+function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); } /**
+ * Copyright © 2026 Alerta Dino. All rights reserved.
+ * 
+ * This code was released under the BSD 3-Clause License.
+ * See the "LICENSE" file under project root.
+ * 
+ * @author (PUBLIC_ID) 1D-C2-9B-98-D6-C3-D6-AB
+ * @signphrase It was created on Earth by humans, although
+ *             I can't define what a "human" is.
+ */
+var _BufRef = /*#__PURE__*/new WeakMap();
+var _MemoryBuffer_brand = /*#__PURE__*/new WeakSet();
+/** 
+ * Provides a scoped wrapper around Node `Buffer` with
+ * explicit zeroization and access checks.
+ */
+class MemoryBuffer {
+  /**
+   * Allocates a new zero-filled `Buffer` in heap.
+   */
+  static alloc(sizeInBytes) {
+    return new MemoryBuffer(Buffer.alloc(sizeInBytes));
+  }
+
+  /**
+   * Using `from()` method may allocate a oversized buffer.
+   * 
+   * It also can share memory with an external resource when
+   * called with `ArrayBuffer` instance, invalidating disposal logic.
+   * 
+   * @advice
+   * Prefer to use`alloc()` with specific needed memory size.
+   */
+
+  /**
+   * Using `from()` method may allocate a oversized buffer.
+   * 
+   * It also can share memory with an external resource when
+   * called with `ArrayBuffer` instance, invalidating disposal logic.
+   * 
+   * @advice
+   * Prefer to use`alloc()` with specific needed memory size.
+   */
+
+  /**
+   * Using `from()` method may allocate a oversized buffer.
+   * 
+   * It also can share memory with an external resource when
+   * called with `ArrayBuffer` instance, invalidating disposal logic.
+   * 
+   * @advice
+   * Prefer to use`alloc()` with specific needed memory size.
+   */
+
+  static from(arg_0, arg_1, arg_2) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new MemoryBuffer(Buffer.from(arg_0, arg_1, arg_2));
+  }
+  constructor(buf) {
+    _classPrivateMethodInitSpec(this, _MemoryBuffer_brand);
+    _classPrivateFieldInitSpec(this, _BufRef, void 0);
+    if (!Buffer.isBuffer(buf)) {
+      throw new _errors.BGDException(`[MemoryBuffer] Cannot construct a memory buffer with given 'typeof ${typeof buf}'`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    (0, _util.assert)(buf.byteLength === buf.length, "[MemoryBuffer] bytes-per-element=1");
+    _classPrivateFieldSet(_BufRef, this, buf);
+  }
+  get byteLength() {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this).byteLength;
+  }
+  get byteOffset() {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this).byteOffset;
+  }
+  get disposed() {
+    return _classPrivateFieldGet(_BufRef, this) == null;
+  }
+  setByte(index, val) {
+    if (typeof index !== "number" || isNaN(index)) {
+      throw new _errors.BGDException("[MemoryBuffer] Array index must be a unsigned integer", "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    if (typeof val !== "number" || isNaN(val)) {
+      throw new _errors.BGDException("[MemoryBuffer] The value \"byte\" must be a integer number", "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    _classPrivateFieldGet(_BufRef, this)[index] = val;
+  }
+  getByte(index) {
+    if (typeof index !== "number" || isNaN(index)) {
+      throw new _errors.BGDException("[MemoryBuffer] Array index must be a unsigned integer", "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this)[index];
+  }
+
+  // WRITE
+  writeUint8(val, offset) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this).writeUInt8(val, offset);
+  }
+  writeInt8(val, offset) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this).writeInt8(val, offset);
+  }
+  writeUint16(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeUInt16${enc}`](val, offset);
+  }
+  writeInt16(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeInt16${enc}`](val, offset);
+  }
+  writeUint32(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeUInt32${enc}`](val, offset);
+  }
+  writeInt32(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeInt32${enc}`](val, offset);
+  }
+  writeUint64(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeBigUInt64${enc}`](val, offset);
+  }
+  writeInt64(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeBigInt64${enc}`](val, offset);
+  }
+  writeFloat(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeFloat${enc}`](val, offset);
+  }
+  writeDouble(val, offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`writeDouble${enc}`](val, offset);
+  }
+  // END WRITE
+
+  // READ
+  readUint8(offset) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this).readUInt8(offset);
+  }
+  readInt8(offset) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this).readInt8(offset);
+  }
+  readUint16(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readUInt16${enc}`](offset);
+  }
+  readInt16(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readInt16${enc}`](offset);
+  }
+  readUint32(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readUInt32${enc}`](offset);
+  }
+  readInt32(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readInt32${enc}`](offset);
+  }
+  readUint64(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readBigUInt64${enc}`](offset);
+  }
+  readInt64(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readBigInt64${enc}`](offset);
+  }
+  readFloat(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readFloat${enc}`](offset);
+  }
+  readDouble(offset, enc = "LE") {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (enc !== "BE" && enc !== "LE") {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown byte encoding "${enc}", expecting little-endian (LE) or big-endian (BE)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this)[`readDouble${enc}`](offset);
+  }
+  // END READ
+
+  copy(target, targetStart, sourceStart, sourceEnd) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (target instanceof MemoryBuffer && _classPrivateFieldGet(_BufRef, target) == null) {
+      throw new _errors.BGDException("[MemoryBuffer] Access to target buffer is not allowed because it's already disposed", "ER_RESOURCE_DISPOSED" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this).copy(target instanceof MemoryBuffer ? _classPrivateFieldGet(_BufRef, target) : target, targetStart, sourceStart, sourceEnd // eslint-disable-line comma-dangle
+    );
+  }
+  indexOf(value, byteOffsetOrEnc, encoding) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (value instanceof MemoryBuffer && _classPrivateFieldGet(_BufRef, value) == null) {
+      throw new _errors.BGDException("[MemoryBuffer] Access to target buffer is not allowed because it's already disposed", "ER_RESOURCE_DISPOSED" // eslint-disable-line comma-dangle
+      );
+    }
+    if (!!byteOffsetOrEnc && typeof byteOffsetOrEnc !== "number" && !Buffer.isBuffer(byteOffsetOrEnc)) {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown element byte-offset (as \`${byteOffsetOrEnc}\`)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this).indexOf(value instanceof MemoryBuffer ? _classPrivateFieldGet(_BufRef, value) : value, byteOffsetOrEnc, encoding // eslint-disable-line comma-dangle
+    );
+  }
+  lastIndexOf(value, byteOffsetOrEnc, encoding) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (value instanceof MemoryBuffer && _classPrivateFieldGet(_BufRef, value) == null) {
+      throw new _errors.BGDException("[MemoryBuffer] Access to target buffer is not allowed because it's already disposed", "ER_RESOURCE_DISPOSED" // eslint-disable-line comma-dangle
+      );
+    }
+    if (!!byteOffsetOrEnc && typeof byteOffsetOrEnc !== "number" && !Buffer.isBuffer(byteOffsetOrEnc)) {
+      throw new _errors.BGDException(`[MemoryBuffer] Unknown element byte-offset (as \`${byteOffsetOrEnc}\`)`, "ER_INVALID_ARGUMENT" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this).lastIndexOf(value instanceof MemoryBuffer ? _classPrivateFieldGet(_BufRef, value) : value, byteOffsetOrEnc, encoding // eslint-disable-line comma-dangle
+    );
+  }
+  compare(target, targetStart, targetEnd, sourceStart, sourceEnd) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (target instanceof MemoryBuffer && _classPrivateFieldGet(_BufRef, target) == null) {
+      throw new _errors.BGDException("[MemoryBuffer] Access to target buffer is not allowed because it's already disposed", "ER_RESOURCE_DISPOSED" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this).compare(target instanceof MemoryBuffer ? _classPrivateFieldGet(_BufRef, target) : target, targetStart, targetEnd, sourceStart, sourceEnd // eslint-disable-line comma-dangle
+    );
+  }
+  equals(other) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    if (other instanceof MemoryBuffer && _classPrivateFieldGet(_BufRef, other) == null) {
+      throw new _errors.BGDException("[MemoryBuffer] Access to target buffer is not allowed because it's already disposed", "ER_RESOURCE_DISPOSED" // eslint-disable-line comma-dangle
+      );
+    }
+    return _classPrivateFieldGet(_BufRef, this).equals(other instanceof MemoryBuffer ? _classPrivateFieldGet(_BufRef, other) : other);
+  }
+  reverse() {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    _classPrivateFieldGet(_BufRef, this).reverse();
+    return this;
+  }
+  toReversed() {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    let buf = _classPrivateFieldGet(_BufRef, this).toReversed();
+    const res = MemoryBuffer.alloc(buf.byteLength);
+    for (let i = 0; i < buf.length; ++i) {
+      res.setByte(i, buf[i]);
+    }
+    buf.fill(0);
+    buf = null;
+    return res;
+  }
+  subarray(start, end) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return new MemoryBuffer(_classPrivateFieldGet(_BufRef, this).subarray(start, end));
+  }
+  toString(enc, start, end) {
+    _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+    return _classPrivateFieldGet(_BufRef, this).toString(enc, start, end);
+  }
+
+  /**
+   * **ATTENTION:** If you use this function make sure that
+   * will not create an external reference of the buffer, or it'll
+   * invalidate the disposal logic resulting in a memory leak.
+   */
+
+  /**
+   * **ATTENTION:** If you use this function make sure that
+   * will not create an external reference of the buffer, or it'll
+   * invalidate the disposal logic resulting in a memory leak.
+   */
+
+  valueOf(secure) {
+    if (_classPrivateFieldGet(_BufRef, this) == null) {
+      if (secure !== false) {
+        _assertClassBrand(_MemoryBuffer_brand, this, _CheckDisposed).call(this);
+      }
+      return null;
+    }
+    return _classPrivateFieldGet(_BufRef, this);
+  }
+
+  /**
+   * Clear current buffer and free allocated memory.
+   * 
+   * **ATTENTION:** It won't work if the `MemoryBuffer` was created
+   * from external memory. When you call `from()` with an `ArrayBuffer`
+   * instance, or something like this, the owner of memory reference is the
+   * external instance, so we can't dispose it.
+   */
+  dispose() {
+    if (_classPrivateFieldGet(_BufRef, this) != null) {
+      _classPrivateFieldGet(_BufRef, this).fill(0);
+      _classPrivateFieldSet(_BufRef, this, null);
+    }
+  }
+  $$debug(r) {
+    let msg = "";
+    if (_classPrivateFieldGet(_BufRef, this) == null) {
+      msg = "Buffer (__disposed__)";
+    } else {
+      msg = `Buffer (${_classPrivateFieldGet(_BufRef, this)?.byteLength}) `;
+      msg += `[ims=0xFF arraybuffer_size=${_classPrivateFieldGet(_BufRef, this).buffer.byteLength}]`;
+      if (_classPrivateFieldGet(_BufRef, this).byteLength >= 4) {
+        const left = [_classPrivateFieldGet(_BufRef, this)[0].toString(16), _classPrivateFieldGet(_BufRef, this)[1].toString(16)];
+        const right = [_classPrivateFieldGet(_BufRef, this).at(-2)?.toString(16), _classPrivateFieldGet(_BufRef, this).at(-1)?.toString(16)];
+        let moreInfo = "";
+        if (_classPrivateFieldGet(_BufRef, this).byteLength > 4) {
+          moreInfo = `... more ${_classPrivateFieldGet(_BufRef, this).byteLength - 4} bytes ... `;
+        }
+        msg += ` { ${left.map(i => `0x${i}`.toUpperCase()).join(", ")} ${moreInfo}${right.map(i => `0x${i}`.toUpperCase()).join(", ")} }`;
+      } else {
+        msg += ` { ${Array.from(_classPrivateFieldGet(_BufRef, this)).map(i => `0x${i.toString(16).toUpperCase()}`).join(", ")} }`;
+      }
+    }
+    if (r === false) {
+      console.log(msg);
+      return;
+    }
+    return msg;
+  }
+}
+exports.MemoryBuffer = MemoryBuffer;
+function _CheckDisposed() {
+  if (_classPrivateFieldGet(_BufRef, this) == null) {
+    throw new _errors.BGDException("[MemoryBuffer] Trying to access a slice of memory that has already disposed", "ER_RESOURCE_DISPOSED" // eslint-disable-line comma-dangle
+    );
+  }
+}

package/allocators/collection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright © 2026 Alerta Dino. All rights reserved.
+ *
+ * This code was released under the BSD 3-Clause License.
+ * See the "LICENSE" file under project root.
+ *
+ * @author (PUBLIC_ID) 1D-C2-9B-98-D6-C3-D6-AB
+ * @signphrase It was created on Earth by humans, although
+ *             I can't define what a "human" is.
+ */
+import { MemoryBuffer } from "./buffer";
+import { BGDException } from "../errors";
+import { Disposable } from "../lifecycle/disposable";
+import { type Either } from "../lifecycle/either";
+export declare class CollectionAllocator extends Disposable {
+    #private;
+    constructor(maxSize?: number);
+    get byteLength(): number;
+    get maxBytes(): number;
+    get freeBytes(): number;
+    alloc(size: number): Either<BGDException, MemoryBuffer>;
+    free(buf: MemoryBuffer): boolean;
+    dispose(): void;
+}

package/allocators/collection.js

@@ -0,0 +1,91 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CollectionAllocator = void 0;
+var _util = require("../util");
+var _buffer = require("./buffer");
+var _errors = require("../errors");
+var _disposable = require("../lifecycle/disposable");
+var _either = require("../lifecycle/either");
+function _classPrivateFieldInitSpec(e, t, a) { _checkPrivateRedeclaration(e, t), t.set(e, a); }
+function _checkPrivateRedeclaration(e, t) { if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object"); }
+function _classPrivateFieldGet(s, a) { return s.get(_assertClassBrand(s, a)); }
+function _classPrivateFieldSet(s, a, r) { return s.set(_assertClassBrand(s, a), r), r; }
+function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); } /**
+ * Copyright © 2026 Alerta Dino. All rights reserved.
+ * 
+ * This code was released under the BSD 3-Clause License.
+ * See the "LICENSE" file under project root.
+ * 
+ * @author (PUBLIC_ID) 1D-C2-9B-98-D6-C3-D6-AB
+ * @signphrase It was created on Earth by humans, although
+ *             I can't define what a "human" is.
+ */
+var _Size = /*#__PURE__*/new WeakMap();
+var _MaxBytes = /*#__PURE__*/new WeakMap();
+var _Disposed = /*#__PURE__*/new WeakMap();
+class CollectionAllocator extends _disposable.Disposable {
+  constructor(maxSize) {
+    if (typeof maxSize !== "undefined" && maxSize != null) {
+      (0, _util.assertType)("uint32", maxSize, "[CollectionAllocator] Max size must be a 32-bits unsigned integer");
+    }
+    super();
+    _classPrivateFieldInitSpec(this, _Size, void 0);
+    _classPrivateFieldInitSpec(this, _MaxBytes, void 0);
+    _classPrivateFieldInitSpec(this, _Disposed, void 0);
+    _classPrivateFieldSet(_Size, this, 0);
+    _classPrivateFieldSet(_MaxBytes, this, maxSize ?? -1);
+    _classPrivateFieldSet(_Disposed, this, false);
+  }
+  get byteLength() {
+    return _classPrivateFieldGet(_Size, this);
+  }
+  get maxBytes() {
+    return _classPrivateFieldGet(_MaxBytes, this);
+  }
+  get freeBytes() {
+    return _classPrivateFieldGet(_MaxBytes, this) - _classPrivateFieldGet(_Size, this);
+  }
+  alloc(size) {
+    if (_classPrivateFieldGet(_Disposed, this)) {
+      const err = new _errors.BGDException("[CollectionAllocator] The collection has already been disposed", "ER_RESOURCE_DISPOSED" // eslint-disable-line comma-dangle
+      );
+      return (0, _either.left)(err);
+    }
+    if (size + _classPrivateFieldGet(_Size, this) > _classPrivateFieldGet(_MaxBytes, this)) {
+      const err = new _errors.BGDException(`[CollectionAllocator] There's not enough space to alloc ${size} bytes`, "ER_BUFFER_OVERFLOW" // eslint-disable-line comma-dangle
+      );
+      return (0, _either.left)(err);
+    }
+    try {
+      const buf = _buffer.MemoryBuffer.alloc(size);
+      _classPrivateFieldSet(_Size, this, _classPrivateFieldGet(_Size, this) + buf.byteLength);
+      return (0, _either.right)(super._register(buf));
+    } catch (err) {
+      let e = err;
+      if (!(err instanceof _errors.BGDException)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        e = new _errors.BGDException(`[CollectionAllocator] Failed to allocate buffer due to: ${err?.message || String(err) || "Unknown error"}`);
+      }
+      return (0, _either.left)(e);
+    }
+  }
+  free(buf) {
+    const size = buf.byteLength;
+
+    /** _delete() removes the object reference and call dispose() from it */
+    const r = super._delete(buf);
+    if (r) {
+      _classPrivateFieldSet(_Size, this, _classPrivateFieldGet(_Size, this) - size);
+    }
+    return r;
+  }
+  dispose() {
+    super.dispose();
+    _classPrivateFieldSet(_Size, this, 0);
+    _classPrivateFieldSet(_Disposed, this, true);
+  }
+}
+exports.CollectionAllocator = CollectionAllocator;

package/allocators/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./buffer";
+export * from "./collection";
+export * from "./virtual-core";