bun-shared-memory 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.6] - 2026-11-02
+
+### Added
+
+- Support shared memory larger than 4 GiB. The single-`SharedArrayBuffer`
+  per-buffer architecture is replaced with a chunked `GrowableBuffer`: each
+  buffer is backed by multiple equal-size chunks (32 MiB default, power of
+  two), so a buffer can exceed the 4 GiB single-SAB limit. Offsets resolve
+  O(1) via bit shifts (`offset >> chunkShift`).
+- `SharedMemoryOptions.chunkSize` to configure the chunk size (the minimum
+  growth step).
+- Chunks are pre-allocated at construction (4 bytes each, with
+  `maxByteLength = chunkSize`) and activated on first access via
+  `SharedArrayBuffer.grow()`. Because `grow()` is visible across all workers
+  sharing a buffer, a worker can grow a chunk and every other worker sees it
+  immediately — no postMessage broadcast is needed for chunk activation.
+
+### Changed
+
+- `exportBuffers()`/`fromBuffers()` now pass chunk lists instead of a single
+  buffer; `fromBuffers` reuses the shared `SharedArrayBuffer`s directly (no
+  copy) so writes stay visible across workers. The chunk size is derived from
+  each buffer's `maxByteLength` (preserved across `postMessage`), not its
+  current 4-byte length.
+- Remove the 4 GiB cap on the per-buffer maximum in the `SharedMemory`
+  constructor (the chunked `GrowableBuffer` already bypasses the single-SAB
+  limit).
+
+### Performance
+
+- After defragmentation, unused chunks are marked inactive:
+  `GrowableBuffer.reset()` deactivates chunks beyond the compacted region so
+  the GC can reclaim their storage.
+- The chunked accessor adds an indirect `chunks[index].view` lookup on the
+  write hot path (the price of >4 GiB support): writes ~-15%, array writes
+  ~-20%. Reads are unchanged (lock-free cache path).
+
+## [0.1.5] - 2026-11-02
+
+### Changed
+
+- Replace the `Proxy` used for object `SharedRef`s with hard-baked
+  `Object.defineProperty` accessor getters/setters, so property reads skip the
+  Proxy trap on the hot path (~3× faster object property reads). Methods
+  (`read`/`write`/`update`/`key`/`buffer`) move to the prototype so the data
+  properties are the only own properties, keeping the JIT shape monomorphic
+  (~2× faster than having the methods as own properties). Arrays, primitives,
+  and unknown shapes still use the Proxy. Fixed shape is enforced via
+  `Object.preventExtensions` plus `configurable: false` accessors.
+- Optimize `copyValue` (the `read()` copy) with `Object.assign` + a `for...in`
+  array pass (~3.5× faster object `read()`).
+- Pass the initial value into `createSharedRef` so the object shape can be
+  baked at creation time.
+
+## [0.1.4] - 2026-11-01
+
+### Changed
+
+- Declare `"sideEffects": false` in `package.json` so bundlers can tree-shake
+  the library (the modules have no side effects on import).
+- Remove the `typescript` peer dependency. The library ships as TypeScript
+  source and runs natively in Bun; `bun check` is Bun's own type checker and
+  does not require the `typescript` package.
+
+## [0.1.3] - 2026-11-01
+
+### Added
+
+- Real-world benchmark (`bench/real-world/`) comparing shared memory against
+  live SQLite, MySQL, and Redis via an Elysia mini API.
+- Redis as a fourth benchmark methodology (in Docker).
+- Unix-socket transport for MySQL/Redis (Linux only; skipped on macOS).
+- Benchmark results written to `benchlogs/<timestamp>-<commit>-real.md`.
+- Real-world benchmark results and methodology documented in the README.
+
+### Changed
+
+- MySQL/Redis connections are established before the benchmark (not per
+  request) so connection setup is not measured as overhead.
+- The benchmark always runs both TCP and Unix-socket transports; the socket
+  run is skipped on macOS without error.
+
+## [0.1.2] - 2026-11-01
+
+### Changed
+
+- Unref the maintenance timer so the process can exit naturally.
+- Document `init()` as the first call and how to configure memory via `init()`.
+
+## [0.1.1] - 2026-11-01
+
+### Added
+
+- Repository metadata and npm publishing preparation.
+- README with package name and install instructions.
+
+### Changed
+
+- Optimize the read hot path: direct cache on the proxy target.
+- Optimize `Mutex`: skip notify when no worker is waiting.
+- Start the refcount coordinator/tracker automatically in `init()`.
+- Document the minimum Bun version (`>= 1.4.0`).
+
+## [0.1.0] - 2026-11-01
+
+### Added
+
+- Initial release: `Shared<T>` Proxy-based API over a 4-buffer shared memory
+  architecture (Index Table, DataTable, append-only StringTable, ArrayTable).
+- Atomics-based synchronization (`Mutex`, `Notifier`).
+- Per-key read cache with cross-worker invalidation and offset cache for
+  object property reads.
+- O(1) in-place `push`/`pop` with capacity-based array growth.
+- Benchmarks for all data types vs native.
+
+[0.1.6]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Kapsonfire/bun-shared-memory/releases/tag/v0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
   "type": "module",
   "sideEffects": false,
@@ -14,7 +14,8 @@
   },
   "files": [
     "index.ts",
-    "src/"
+    "src/",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "typecheck": "bun check",
@@ -46,8 +47,6 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "elysia": "^1.4.30",
-    "ioredis": "^6.0.0",
-    "mysql2": "^3.24.6"
+    "elysia": "^1.4.30"
   }
 }

package/src/growable-buffer.ts

@@ -35,33 +35,111 @@ export class SharedBudget {
 }
 
 /**
- * Growable SharedArrayBuffer helper.
+ * Growable shared memory backed by one or more SharedArrayBuffers (chunks).
  *
- * SharedArrayBuffer supports `grow(newLength)` when created with
- * `maxByteLength`. Growth preserves existing data, can only grow up to
- * `maxByteLength`, and cannot shrink. All workers sharing the buffer see the
- * growth immediately.
+ * A single SharedArrayBuffer can be at most 4 GiB, so a buffer that needs to
+ * grow beyond that is split into multiple chunks. Each chunk is its own
+ * SharedArrayBuffer (<= `chunkMax` bytes). Offsets are logical and continuous
+ * across chunks; access methods resolve an offset into (chunk, chunkOffset).
+ *
+ * All chunks are pre-allocated at construction with `maxByteLength = chunkSize`
+ * but only 4 bytes of actual storage. A chunk is "activated" (grown to its
+ * full `chunkSize`) on first access. Because `SharedArrayBuffer.grow()` is
+ * visible across all workers sharing the buffer, activation needs no
+ * postMessage broadcast.
  */
+interface Chunk {
+  buffer: SharedArrayBuffer;
+  view: DataView;
+  /** Whether the chunk has been grown to its full size. */
+  active: boolean;
+}
+
+/** Round `n` up to the next power of two (chunk sizes must be powers of two). */
+function nextPowerOfTwo(n: number): number {
+  if (n <= 0) return 1;
+  let p = 1;
+  while (p < n) p <<= 1;
+  return p;
+}
+
 export class GrowableBuffer {
-  readonly buffer: SharedArrayBuffer;
-  private view: DataView;
+  private chunks: Chunk[] = [];
   private readonly maxByteLength: number;
+  /** Fixed size of every chunk (the minimum growth step). */
+  readonly chunkSize: number;
+  /** log2(chunkSize), used for O(1) offset resolution via bit shifts. */
+  private readonly chunkShift: number;
   private readonly budget?: SharedBudget;
   private used = 0;
 
   constructor(
-    initialSizeOrBuffer: number | SharedArrayBuffer,
+    initialSizeOrBuffer: number | SharedArrayBuffer | SharedArrayBuffer[],
     maxByteLength: number,
     budget?: SharedBudget,
+    chunkSize = 32 * 1024 * 1024, // 32 MiB per chunk
   ) {
-    this.buffer =
-      typeof initialSizeOrBuffer === "number"
-        ? new SharedArrayBuffer(initialSizeOrBuffer, { maxByteLength })
-        : initialSizeOrBuffer;
-    this.view = new DataView(this.buffer);
     this.maxByteLength = maxByteLength;
     this.budget = budget;
-    this.budget?.add(this.buffer.byteLength);
+    if (typeof initialSizeOrBuffer === "number") {
+      this.chunkSize = Math.min(nextPowerOfTwo(chunkSize), maxByteLength);
+      this.chunkShift = Math.log2(this.chunkSize);
+      // Pre-allocate all chunks (4 bytes each, growable to chunkSize).
+      const chunkCount = Math.max(1, Math.ceil(maxByteLength / this.chunkSize));
+      for (let i = 0; i < chunkCount; i++) {
+        const buffer = new SharedArrayBuffer(4, {
+          maxByteLength: this.chunkSize,
+        });
+        this.chunks.push({
+          buffer,
+          view: new DataView(buffer),
+          active: false,
+        });
+      }
+    } else if (Array.isArray(initialSizeOrBuffer)) {
+      // Reconstruct from a list of chunks. Use the buffers directly (they are
+      // already shared via postMessage) so writes are visible across workers.
+      // All chunks are pre-allocated at 4 bytes with maxByteLength = chunkSize;
+      // the chunk size is derived from each buffer's maxByteLength (which is
+      // preserved across postMessage), not its current byteLength.
+      this.chunkSize = initialSizeOrBuffer[0]?.maxByteLength ?? chunkSize;
+      this.chunkShift = Math.log2(this.chunkSize);
+      for (const sab of initialSizeOrBuffer) {
+        this.chunks.push({
+          buffer: sab,
+          view: new DataView(sab),
+          active: sab.byteLength === this.chunkSize,
+        });
+        this.budget?.add(sab.byteLength);
+      }
+    } else {
+      // Reconstruct from a single existing buffer. Use it directly so writes
+      // are shared. Its size defines the chunk size (prefer maxByteLength so
+      // a pre-allocated 4-byte chunk is interpreted at its full size).
+      this.chunkSize =
+        initialSizeOrBuffer.maxByteLength ?? initialSizeOrBuffer.byteLength;
+      this.chunkShift = Math.log2(this.chunkSize);
+      this.chunks.push({
+        buffer: initialSizeOrBuffer,
+        view: new DataView(initialSizeOrBuffer),
+        active: initialSizeOrBuffer.byteLength === this.chunkSize,
+      });
+      this.budget?.add(initialSizeOrBuffer.byteLength);
+    }
+  }
+
+  /**
+   * Activate the chunk at `index` by growing it to its full size. Because
+   * `SharedArrayBuffer.grow()` is visible across all workers, no broadcast is
+   * needed. No-op if the chunk is already active.
+   */
+  private activate(index: number): void {
+    const chunk = this.chunks[index];
+    if (chunk === undefined || chunk.active) return;
+    chunk.buffer.grow(this.chunkSize);
+    chunk.view = new DataView(chunk.buffer);
+    chunk.active = true;
+    this.budget?.add(this.chunkSize);
   }
 
   /** Number of bytes written so far (used length, not buffer capacity). */
@@ -69,24 +147,49 @@ export class GrowableBuffer {
     return this.used;
   }
 
+  /** Total logical capacity across all chunks (active or not). */
+  get capacity(): number {
+    return this.chunks.length * this.chunkSize;
+  }
+
+  /** The list of SharedArrayBuffers backing this buffer (for export). */
+  get buffers(): SharedArrayBuffer[] {
+    return this.chunks.map((c) => c.buffer);
+  }
+
+  /** Number of chunks that have been activated (grown to full size). */
+  get activeChunkCount(): number {
+    return this.chunks.reduce((n, c) => n + (c.active ? 1 : 0), 0);
+  }
+
+  /**
+   * Resolve a logical offset into (chunk, offset within that chunk). All
+   * chunks are the same size, so this is O(1). Activates the chunk if it is
+   * not yet active.
+   */
+  private resolve(offset: number): { chunk: Chunk; off: number } {
+    const index = offset >> this.chunkShift;
+    const chunk = this.chunks[index];
+    if (chunk === undefined) {
+      throw new RangeError(`Offset ${offset} is beyond the buffer capacity`);
+    }
+    this.activate(index);
+    return { chunk, off: offset & (this.chunkSize - 1) };
+  }
+
   /** Ensure the buffer has room for at least `needed` bytes. */
   ensureCapacity(needed: number): void {
-    if (needed <= this.buffer.byteLength) return;
     if (needed > this.maxByteLength) {
       throw new RangeError(
         `Shared buffer capacity exceeded: need ${needed} bytes but max is ${this.maxByteLength}`,
       );
     }
-    let newSize = this.buffer.byteLength * 2;
-    while (newSize < needed) newSize *= 2;
-    if (newSize > this.maxByteLength) newSize = this.maxByteLength;
-    if (this.budget && !this.budget.tryGrow(this.buffer.byteLength, newSize)) {
-      throw new RangeError(
-        `Shared memory budget exceeded: growing to ${newSize} bytes would exceed the total budget`,
-      );
+    // All chunks are pre-allocated; just activate the ones needed to cover
+    // `needed`. grow() is visible across workers, so no broadcast is required.
+    const neededChunks = Math.ceil(needed / this.chunkSize);
+    for (let i = 0; i < neededChunks; i++) {
+      this.activate(i);
     }
-    this.buffer.grow(newSize);
-    this.view = new DataView(this.buffer);
   }
 
   /** Mark `n` bytes as used, after writing them at the current offset. */
@@ -96,15 +199,80 @@ export class GrowableBuffer {
 
   /**
    * Reset the used length to `n` bytes. Used by defragmentation after
-   * compacting live data to the front of the buffer. The underlying
-   * SharedArrayBuffer is not shrunk (it cannot be), but the tail beyond `n`
-   * is treated as free space for future writes.
+   * compacting live data to the front of the buffer. Chunks beyond the
+   * compacted region are marked inactive (their storage is released by the
+   * GC, which replaces them with fresh chunks).
    */
   reset(n: number): void {
     this.used = n;
+    const neededChunks = Math.ceil(n / this.chunkSize);
+    for (let i = neededChunks; i < this.chunks.length; i++) {
+      this.chunks[i]!.active = false;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Typed accessors (resolve offset -> chunk)
+  // -------------------------------------------------------------------------
+
+  getInt32(offset: number): number {
+    const index = offset >> this.chunkShift;
+    this.activate(index);
+    return this.chunks[index]!.view.getInt32(
+      offset & (this.chunkSize - 1),
+      true,
+    );
+  }
+
+  setInt32(offset: number, value: number): void {
+    const index = offset >> this.chunkShift;
+    this.activate(index);
+    this.chunks[index]!.view.setInt32(
+      offset & (this.chunkSize - 1),
+      value,
+      true,
+    );
   }
 
-  getView(): DataView {
-    return this.view;
+  getUint8(offset: number): number {
+    const index = offset >> this.chunkShift;
+    this.activate(index);
+    return this.chunks[index]!.view.getUint8(offset & (this.chunkSize - 1));
+  }
+
+  setUint8(offset: number, value: number): void {
+    const index = offset >> this.chunkShift;
+    this.activate(index);
+    this.chunks[index]!.view.setUint8(offset & (this.chunkSize - 1), value);
+  }
+
+  /** Read `length` bytes starting at `offset` into a fresh Uint8Array. */
+  readBytes(offset: number, length: number): Uint8Array {
+    const out = new Uint8Array(length);
+    let pos = offset;
+    let outPos = 0;
+    while (outPos < length) {
+      const { chunk, off } = this.resolve(pos);
+      const n = Math.min(length - outPos, this.chunkSize - off);
+      out.set(new Uint8Array(chunk.buffer, off, n), outPos);
+      outPos += n;
+      pos += n;
+    }
+    return out;
+  }
+
+  /** Write `bytes` starting at `offset`. */
+  writeBytes(offset: number, bytes: Uint8Array): void {
+    let pos = offset;
+    let srcPos = 0;
+    while (srcPos < bytes.byteLength) {
+      const { chunk, off } = this.resolve(pos);
+      const n = Math.min(bytes.byteLength - srcPos, this.chunkSize - off);
+      new Uint8Array(chunk.buffer, off, n).set(
+        bytes.subarray(srcPos, srcPos + n),
+      );
+      srcPos += n;
+      pos += n;
+    }
   }
 }