@nxtedition/slice 1.0.1

package/lib/index.d.ts

@@ -0,0 +1,45 @@
+import util from 'node:util';
+export declare class Slice {
+    buffer: Buffer;
+    byteOffset: number;
+    byteLength: number;
+    maxByteLength: number;
+    static EMPTY_BUF: Buffer;
+    constructor(buffer?: Buffer<ArrayBufferLike>, byteOffset?: number, byteLength?: number, maxByteLength?: number);
+    reset(): void;
+    get length(): number;
+    copy(target: Uint8Array | Slice, targetStart?: number, sourceStart?: number, sourceEnd?: number): number;
+    compare(target: Uint8Array | Slice, targetStart?: number, targetEnd?: number, sourceStart?: number, sourceEnd?: number): -1 | 0 | 1;
+    write(string: string, offset?: number, length?: number, encoding?: BufferEncoding): number;
+    set(source: Buffer | Slice | null | undefined, offset?: number): void;
+    at(index: number): number;
+    test(expr: {
+        test: (buffer: Buffer, byteOffset: number, byteLength: number) => boolean;
+    }): boolean;
+    toString(encoding?: BufferEncoding, start?: number, end?: number): string;
+    toBuffer(start?: number, end?: number): Buffer;
+    [Symbol.toStringTag](): string;
+    [util.inspect.custom](depth: number, options: util.InspectOptionsStylized, inspect: typeof util.inspect): string;
+}
+/**
+ * A buddy allocator using XOR bitmap for efficient coalescing.
+ * Each bit tracks the XOR of a buddy pair's allocation state.
+ * When a bit is 0, both buddies have the same state (both free or both allocated).
+ * When a bit is 1, the buddies have different states.
+ */
+export declare class BuddyAllocator {
+    #private;
+    constructor(poolTotal?: number);
+    realloc(slice: Slice, byteLength: number): Slice;
+    get stats(): {
+        size: number;
+        padding: number;
+        ratio: number;
+        poolTotal: number;
+        poolUsed: number;
+        poolSize: number;
+        poolCount: number;
+        poolList: number[];
+    };
+    isFromPool(slice: Slice | null | undefined): boolean;
+}

package/lib/index.js

@@ -0,0 +1,462 @@
+import util from 'node:util'
+
+const EMPTY_BUF = Buffer.alloc(0)
+
+export class Slice {
+  buffer         = EMPTY_BUF
+  byteOffset         = 0
+  byteLength         = 0
+  maxByteLength         = 0
+
+  static EMPTY_BUF         = EMPTY_BUF
+
+  constructor(
+    buffer = Slice.EMPTY_BUF,
+    byteOffset = 0,
+    byteLength = buffer.byteLength,
+    maxByteLength = byteLength,
+  ) {
+    if (!(buffer instanceof Buffer)) {
+      throw new TypeError('buffer must be a Buffer')
+    }
+
+    if (byteOffset < 0 || !Number.isInteger(byteOffset)) {
+      throw new RangeError(`Invalid byteOffset: ${byteOffset}`)
+    }
+
+    if (byteLength < 0 || !Number.isInteger(byteLength)) {
+      throw new RangeError(`Invalid byteLength: ${byteLength}`)
+    }
+
+    if (
+      maxByteLength < byteLength ||
+      maxByteLength > buffer.byteLength ||
+      !Number.isInteger(maxByteLength)
+    ) {
+      throw new RangeError(`Invalid maxByteLength: ${maxByteLength}`)
+    }
+
+    this.buffer = buffer
+    this.byteOffset = byteOffset
+    this.byteLength = byteLength
+    this.maxByteLength = maxByteLength
+  }
+
+  reset()       {
+    this.buffer = Slice.EMPTY_BUF
+    this.byteOffset = 0
+    this.byteLength = 0
+    this.maxByteLength = 0
+  }
+
+  get length()         {
+    return this.byteLength
+  }
+
+  copy(
+    target                    ,
+    targetStart         ,
+    sourceStart         ,
+    sourceEnd         ,
+  )         {
+    if (target instanceof Slice) {
+      if (targetStart === undefined) {
+        targetStart = target.byteOffset
+      } else {
+        targetStart += target.byteOffset
+      }
+
+      target = target.buffer
+    }
+
+    if (sourceStart === undefined) {
+      sourceStart = this.byteOffset
+    } else {
+      sourceStart += this.byteOffset
+    }
+
+    if (sourceEnd === undefined) {
+      sourceEnd = this.byteLength + this.byteOffset
+    } else {
+      sourceEnd += this.byteOffset
+    }
+
+    if (this.buffer === target && sourceStart === targetStart) {
+      return sourceEnd - sourceStart
+    }
+
+    return this.buffer.copy(target, targetStart, sourceStart, sourceEnd)
+  }
+
+  compare(
+    target                    ,
+    targetStart         ,
+    targetEnd         ,
+    sourceStart         ,
+    sourceEnd         ,
+  )             {
+    if (target instanceof Slice) {
+      if (targetStart === undefined) {
+        targetStart = target.byteOffset
+      } else {
+        targetStart += target.byteOffset
+      }
+
+      if (targetEnd === undefined) {
+        targetEnd = target.byteLength + target.byteOffset
+      } else {
+        targetEnd += target.byteOffset
+      }
+
+      target = target.buffer
+    }
+
+    if (sourceStart === undefined) {
+      sourceStart = this.byteOffset
+    } else {
+      sourceStart += this.byteOffset
+    }
+
+    if (sourceEnd === undefined) {
+      sourceEnd = this.byteLength + this.byteOffset
+    } else {
+      sourceEnd += this.byteOffset
+    }
+
+    return this.buffer.compare(target, targetStart, targetEnd, sourceStart, sourceEnd)
+  }
+
+  write(string        , offset         , length         , encoding                 )         {
+    if (offset === undefined) {
+      offset = this.byteOffset
+    } else {
+      offset += this.byteOffset
+    }
+
+    if (length === undefined) {
+      length = this.byteLength + this.byteOffset - offset
+    }
+
+    return this.buffer.write(string, offset, length, encoding)
+  }
+
+  set(source                                   , offset         )       {
+    if (source == null) {
+      return
+    }
+
+    if (offset === undefined) {
+      offset = this.byteOffset
+    } else {
+      offset += this.byteOffset
+    }
+
+    source.copy(this.buffer, offset)
+  }
+
+  at(index        )         {
+    return index >= 0
+      ? this.buffer[this.byteOffset + index]
+      : this.buffer[this.byteOffset + this.byteLength + index]
+  }
+
+  test(expr   
+                                                                             
+   )          {
+    return expr.test(this.buffer, this.byteOffset, this.byteLength)
+  }
+
+  toString(encoding                 , start         , end         )         {
+    if (start === undefined) {
+      start = this.byteOffset
+    } else {
+      start += this.byteOffset
+    }
+
+    if (end === undefined) {
+      end = this.byteLength + this.byteOffset
+    } else {
+      end += this.byteOffset
+    }
+
+    return this.buffer.toString(encoding, start, end)
+  }
+
+  toBuffer(start         , end         )         {
+    if (start === undefined) {
+      start = this.byteOffset
+    } else {
+      start += this.byteOffset
+    }
+
+    if (end === undefined) {
+      end = this.byteLength + this.byteOffset
+    } else {
+      end += this.byteOffset
+    }
+
+    return start === 0 && end === this.buffer.byteLength
+      ? this.buffer
+      : this.buffer.subarray(start, end)
+  }
+
+  [Symbol.toStringTag]()         {
+    return this.toString()
+  }
+
+  [util.inspect.custom](
+    depth        ,
+    options                             ,
+    inspect                     ,
+  )         {
+    const bytes = []
+    for (let i = 0; i < this.byteLength; i++) {
+      bytes.push(this.buffer[this.byteOffset + i].toString(16).padStart(2, '0'))
+    }
+    return `Slice: "${this.toString()}" <${bytes.join(' ')}>`
+  }
+}
+
+/**
+ * A buddy allocator using XOR bitmap for efficient coalescing.
+ * Each bit tracks the XOR of a buddy pair's allocation state.
+ * When a bit is 0, both buddies have the same state (both free or both allocated).
+ * When a bit is 1, the buddies have different states.
+ */
+export class BuddyAllocator {
+  #size         = 0
+  #padding         = 0
+  #poolCount         = 0
+
+  #poolBuffer        
+  #poolTotal        
+  #minOrder        
+  #maxOrder        
+
+  // Free lists indexed by order - simple arrays with push/pop
+  #freeLists             = []
+
+  // XOR bitmap for coalescing - single contiguous buffer for cache locality
+  // Each order has a view into this buffer
+  // Bit = 0: both buddies same state, Bit = 1: different states
+  #bitmaps                = []
+  #bitmapBuffer                     = null
+
+  constructor(poolTotal = 128 * 1024 * 1024) {
+    // Handle invalid pool sizes gracefully - fall back to no pool
+    if (!Number.isFinite(poolTotal) || poolTotal <= 0) {
+      this.#poolBuffer = Buffer.allocUnsafe(0)
+      this.#poolTotal = 0
+      this.#minOrder = 3
+      this.#maxOrder = 0
+      return
+    }
+
+    // Round up to nearest power of 2
+    this.#maxOrder = Math.ceil(Math.log2(poolTotal))
+    this.#poolTotal = 1 << this.#maxOrder
+
+    // Minimum block size is 8 bytes (order 3)
+    this.#minOrder = 3
+
+    this.#poolBuffer = Buffer.allocUnsafe(this.#poolTotal)
+
+    // Calculate total bitmap size and offsets for each order
+    // Total pairs = 2^(maxOrder-minOrder) - 1, total words ≈ that / 32
+    let totalWords = 0
+    const offsets = []
+    for (let order = 0; order <= this.#maxOrder; order++) {
+      offsets.push(totalWords)
+      const numPairs = 1 << Math.max(0, this.#maxOrder - order - 1)
+      totalWords += Math.ceil(numPairs / 32)
+    }
+
+    // Allocate single contiguous buffer for all bitmaps
+    this.#bitmapBuffer = new ArrayBuffer(totalWords * 4)
+
+    // Create views into the buffer for each order
+    for (let order = 0; order <= this.#maxOrder; order++) {
+      this.#freeLists.push([])
+
+      const numPairs = 1 << Math.max(0, this.#maxOrder - order - 1)
+      const numWords = Math.ceil(numPairs / 32)
+      this.#bitmaps.push(new Uint32Array(this.#bitmapBuffer, offsets[order] * 4, numWords))
+    }
+
+    // Initially, the entire buffer is one free block at max order
+    this.#freeLists[this.#maxOrder].push(0)
+  }
+
+  realloc(slice       , byteLength        )        {
+    if (!Number.isInteger(byteLength) || byteLength < 0) {
+      throw new TypeError(`Invalid byteLength: ${byteLength}`)
+    }
+
+    if (slice == null) {
+      slice = new Slice()
+    } else if (!(slice instanceof Slice)) {
+      throw new TypeError('slice must be a Slice instance')
+    }
+
+    if (slice.byteLength === byteLength) {
+      return slice
+    }
+
+    const dstOrder = byteLength === 0 ? 0 : this.#getOrder(byteLength)
+
+    if (this.isFromPool(slice)) {
+      // Derive order from maxByteLength
+      const srcOrder = 31 - Math.clz32(slice.maxByteLength)
+
+      this.#size -= slice.byteLength
+      this.#padding -= slice.maxByteLength - slice.byteLength
+
+      if (srcOrder === dstOrder) {
+        slice.byteLength = byteLength
+        this.#size += slice.byteLength
+        this.#padding += slice.maxByteLength - slice.byteLength
+        return slice
+      }
+
+      // Free the old block
+      this.#freeBlock(slice.byteOffset, srcOrder)
+      this.#poolCount--
+    }
+
+    slice.reset()
+
+    if (byteLength === 0) {
+      return slice
+    }
+
+    const offset = this.#allocBlock(dstOrder)
+    if (offset == null) {
+      // Fall back to regular allocation
+      slice.buffer = Buffer.allocUnsafeSlow(byteLength)
+      slice.byteOffset = 0
+      slice.byteLength = byteLength
+      slice.maxByteLength = byteLength
+    } else {
+      slice.buffer = this.#poolBuffer
+      slice.byteOffset = offset
+      slice.byteLength = byteLength
+      slice.maxByteLength = 1 << dstOrder
+
+      this.#poolCount++
+      this.#size += byteLength
+      this.#padding += slice.maxByteLength - slice.byteLength
+    }
+
+    return slice
+  }
+
+  get stats() {
+    // Calculate free space from all free lists
+    let freeSpace = 0
+    for (let order = this.#minOrder; order <= this.#maxOrder; order++) {
+      freeSpace += this.#freeLists[order].length << order
+    }
+
+    const poolUsed = this.#poolTotal - freeSpace
+
+    return {
+      size: this.#size,
+      padding: this.#padding,
+      ratio: this.#size > 0 ? (this.#size + this.#padding) / this.#size : 1,
+      poolTotal: this.#poolTotal,
+      poolUsed,
+      poolSize: poolUsed,
+      poolCount: this.#poolCount,
+      poolList: this.#freeLists.map((list) => list.length),
+    }
+  }
+
+  isFromPool(slice                          )          {
+    return slice != null && slice.buffer === this.#poolBuffer
+  }
+
+  #toggleBit(offset        , order        )          {
+    if (order >= this.#maxOrder) {
+      return false
+    }
+    const pairIndex = offset >>> (order + 1)
+    const wordIndex = pairIndex >>> 5
+    const bitMask = 1 << (pairIndex & 31)
+    const bitmap = this.#bitmaps[order]
+    bitmap[wordIndex] ^= bitMask
+    return (bitmap[wordIndex] & bitMask) !== 0
+  }
+
+  #allocBlock(order        )                {
+    // Try to allocate from pool
+    if (order > this.#maxOrder || this.#poolTotal === 0) {
+      return null
+    }
+
+    // Find the smallest order with a free block
+    let currentOrder = order
+    while (currentOrder <= this.#maxOrder && this.#freeLists[currentOrder].length === 0) {
+      currentOrder++
+    }
+
+    if (currentOrder > this.#maxOrder) {
+      return null
+    }
+
+    // Pop the free block
+    const offset = this.#freeLists[currentOrder].pop() 
+
+    // Found block at exact order - just toggle and return
+    if (currentOrder === order) {
+      this.#toggleBit(offset, order)
+      return offset
+    }
+
+    // Split down to the requested order
+    while (currentOrder > order) {
+      currentOrder--
+      // Add buddy to free list
+      const buddyOffset = offset ^ (1 << currentOrder)
+      this.#freeLists[currentOrder].push(buddyOffset)
+      // Toggle bit - one buddy free, one allocated/kept
+      this.#toggleBit(offset, currentOrder)
+    }
+
+    return offset
+  }
+
+  #freeBlock(offset        , order        )       {
+    while (order < this.#maxOrder) {
+      // Toggle bit and check if we can coalesce
+      const isDifferent = this.#toggleBit(offset, order)
+
+      if (isDifferent) {
+        // Bit is now 1: buddy is allocated, can't coalesce
+        this.#freeLists[order].push(offset)
+        return
+      }
+
+      // Bit is now 0: both buddies are free, coalesce
+      // Remove buddy from free list
+      const buddyOffset = offset ^ (1 << order)
+      const idx = this.#freeLists[order].indexOf(buddyOffset)
+      if (idx !== -1) {
+        // Swap with last and pop for O(1) removal
+        const last = this.#freeLists[order].length - 1
+        this.#freeLists[order][idx] = this.#freeLists[order][last]
+        this.#freeLists[order].pop()
+      }
+
+      // Move up to parent level
+      offset = offset & ~(1 << order)
+      order++
+    }
+
+    // Reached max order
+    this.#freeLists[order].push(offset)
+  }
+
+  #getOrder(byteLength        )         {
+    return byteLength <= 1 << this.#minOrder ? this.#minOrder : 32 - Math.clz32(byteLength - 1)
+  }
+}

package/lib/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@nxtedition/slice",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
+    "prepublishOnly": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "test:ci": "node --test"
+  },
+  "devDependencies": {
+    "amaroc": "^1.0.1",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3"
+  },
+  "gitHead": "2517ca631e010f17f7ba8be4e1b854ad18cbd746"
+}