bun-shared-memory 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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).
 
+## [Unreleased]
+
+## [0.2.2] - 2026-11-05
+
+### Added
+
+- **`null` is now a supported shared value**. A new `TYPE_NULL` slot type
+  allows `null` to be stored and read anywhere — top-level, object property,
+  array element, nested object/array. `undefined` remains intentionally
+  unsupported.
+- **Nested objects and live `Shared` references**: an object property (or array
+  element) may now be another plain object, read lazily and mutated in place
+  (e.g. `doc.profile.meta.level++` writes directly to shared memory). Two new
+  slot types back this: `TYPE_OBJECT_REF` (a nested object block in the
+  DataTable) and `TYPE_KEY_REF` (a live reference to another shared key).
+- **Nested `Shared` values**: storing a `Shared` object inside another object
+  or array keeps a live reference, so both wrappers stay in sync (no copying).
+- **Nested arrays**: arrays may contain other arrays (stored recursively as
+  array-refs in the ArrayTable). `arr[0][1] = x`, `arr[0].push(...)`, etc.
+- **Defragmentation** remaps nested object references and rewrites their
+  property slots; the per-worker object-layout cache is re-validated against
+  the global layout version so it stays correct across a defrag.
+
+### Performance
+
+- Cache the key's **version-cell index in the read cache**, so cache-hit reads
+  skip the `versionCellIndex` arithmetic and go straight to
+  `Atomics.load(view, cached.cell)`.
+- Hoist **`getLayoutVersion`** inside lock-free writes: within a write (counter
+  > 0) the layout version cannot change, so read it once and reuse it for all
+  cached-offset and ArrayRef checks, saving 2–3 `Atomics.load` ops per write.
+  Array writes improved from ~37× to ~33× slower than native.
+
+### Fixed
+
+- Fix `copyBytes` in the defrag compactor so overlapping source/destination
+  ranges (a small string-value block compacting forward over the source region
+  of a later array block) are copied overlap-safely. This previously could
+  corrupt array contents after a defragmentation that involved interleaved
+  string-value and array blocks.
+
 ## [0.2.1] - 2026-11-04
 
 ### Performance
@@ -24,11 +65,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cache the key's version-cell index in the array proxy so writes bump the
   version without a per-write Map lookup. Object array-prop index writes
   dropped from ~33.9× to ~29× slower than native.
-- Real-world benchmark: the shared-memory "get user" endpoint improved from
-  ~4.18M to ~5.79M req/s (+39%), widening the gap over the comparison
-  backends (sqlite 6.2×→8.5×, redis 218×→302×, mysql 233×→322× slower than
+- Real-world benchmark: the shared-memory "get user" endpoint improved to
+  ~5.15M req/s, widening the gap over the comparison
+  backends (sqlite 9.9×, redis 76.5×, mysql 82.0× slower than
   shared memory).
 
+### Benchmark
+
+- Increase `SAMPLES_PER_WORKER` from 5 to 15 for more stable per-run statistics.
+- Increase `RUNS_PER_METHOD` from 3 to 5 for better CPU-contention filtering.
+- Increase warmup from 1,000 to 5,000 iterations so the JIT and DB caches
+  are fully warmed before measurement.
+- Add `?pool=8` to MySQL connection strings to avoid per-request connect overhead.
+- Add priming queries (`SELECT LIMIT 1` for MySQL, `PING` for Redis) so the
+  first measured request does not hit cold-connect latency.
+
 ## [0.2.0] - 2026-11-04
 
 ### Added

package/README.md

@@ -38,20 +38,20 @@ is benchmarked sequentially with 4 workers. See
 
 Measured on Linux (Bun 1.4.4, 100,000 requests per methodology, sorted by
 speed; MySQL/Redis benchmarked over both TCP and Unix socket; each methodology
-is the minimum over 3 runs × 5 samples to filter CPU-contention noise):
+is the minimum over 5 runs × 15 samples to filter CPU-contention noise):
 
 | Methodology | Transport | Requests | Elapsed (ms) | req/s     | vs. shared    |
 | ----------- | --------- | -------- | ------------ | --------- | ------------- |
-| `shared`    | —         | 100,000  | 21           | 4,876,492 | —             |
-| `sqlite`    | —         | 100,000  | 188          | 531,116   | 9.2× slower   |
-| `redis`     | socket    | 100,000  | 1,262        | 79,229    | 61.5× slower  |
-| `mysql`     | socket    | 100,000  | 1,605        | 62,322    | 78.2× slower  |
-| `redis`     | tcp       | 100,000  | 2,817        | 35,497    | 137.4× slower |
-| `mysql`     | tcp       | 100,000  | 2,976        | 33,602    | 145.1× slower |
-
-Shared memory is the fastest by a wide margin: ~9.2× faster than a live SQLite
-read and ~61–145× faster than live MySQL/Redis reads. Unix sockets are
-significantly faster than TCP for MySQL/Redis (~1.8×), but both remain far
+| `shared`    | —         | 100,000  | 19           | 5,154,977 | —             |
+| `sqlite`    | —         | 100,000  | 192          | 520,329   | 9.9× slower   |
+| `redis`     | socket    | 100,000  | 1,484        | 67,385    | 76.5× slower  |
+| `mysql`     | socket    | 100,000  | 1,591        | 62,865    | 82.0× slower  |
+| `redis`     | tcp       | 100,000  | 2,617        | 38,205    | 134.9× slower |
+| `mysql`     | tcp       | 100,000  | 3,133        | 31,922    | 161.5× slower |
+
+Shared memory is the fastest by a wide margin: ~9.9× faster than a live SQLite
+read and ~61–161× faster than live MySQL/Redis reads. Unix sockets are
+significantly faster than TCP for MySQL/Redis (~1.7–1.8×), but both remain far
 slower than shared memory.
 
 ## ✨ Features
@@ -90,7 +90,10 @@ See [SPEC.md](./SPEC.md) for the full specification.
 - **Allowed**: primitives (`number`, `string`, `boolean`), `bigint`, and arrays of these (mixed arrays allowed).
 - **BigInts** of any size are supported: values that fit in 64 bits are stored as a fast int64 slot; larger values are stored as their decimal string in the StringTable.
 - **Objects** have a **fixed shape**: once created, properties may not be added or removed — only their values can change.
-- **Not allowed**: nested objects, nested arrays, `null`, `undefined`.
+- **Nested objects and arrays** are supported: an object or array can contain other plain objects and arrays (read lazily, mutated in place).
+- **Nested `Shared` references**: a `Shared` object can be stored inside another object or array as a _live reference_ — both stay in sync (mutating either updates the same shared value). Self-references and mutual references are supported as long as the property exists in the object's initial fixed shape.
+- **`null` is allowed** as a value (top-level, object property, or array element).
+- **Not allowed**: `undefined`.
 
 ## Usage
 
@@ -123,6 +126,19 @@ const arr = Shared<number[]>("arr-1", [1, 2, 3]);
 arr.push(4);
 arr[0] = 99;
 
+// Nested objects are read lazily and mutated in place
+const doc = Shared("doc-1", {
+  profile: { name: "Alice", meta: { level: 3 } },
+});
+doc.profile.meta.level++;
+doc.profile.meta.level; // 4
+
+// Nested Shared values are live references that stay in sync
+const settings = Shared("settings-1", { theme: "dark" });
+const app = Shared("app-1", { settings });
+app.settings.theme = "light";
+settings.theme; // "light" (same shared value)
+
 // Primitives use read()/write()/update()
 const counter = Shared<number>("counter-1", 0);
 counter.write(42);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
   "type": "module",
   "sideEffects": false,

package/src/growable-buffer.ts

@@ -425,6 +425,41 @@ export class GrowableBuffer {
     Atomics.add(this.cursor, 0, BigInt(n));
   }
 
+  /**
+   * Grow a block in place by `extra` bytes when the space immediately after it
+   * is free (i.e. the block is the last allocated one, so its end equals the
+   * current used length). This lets a caller extend a block without leaving
+   * the old prefix as dead space.
+   *
+   * The cursor is advanced with a compare-exchange loop, so concurrent workers
+   * cannot allocate into the space being claimed: if another worker has
+   * reserved bytes after `endOffset`, the cursor no longer equals `endOffset`
+   * and this returns false, letting the caller fall back to a fresh
+   * allocation.
+   *
+   * @returns true if the block was grown in place, false if the space after it
+   *          is not free (caller must allocate a new block).
+   */
+  growInPlace(endOffset: number, extra: number): boolean {
+    if (extra <= 0) return true;
+    while (true) {
+      const current = Number(Atomics.load(this.cursor, 0));
+      if (current !== endOffset) return false;
+      const next = current + extra;
+      if (
+        Atomics.compareExchange(
+          this.cursor,
+          0,
+          BigInt(current),
+          BigInt(next),
+        ) === BigInt(current)
+      ) {
+        this.ensureCapacity(next);
+        return true;
+      }
+    }
+  }
+
   /**
    * Atomically reserve `size` bytes at the end of the buffer and return the
    * start offset. This is the lock-free bump-allocation primitive: the shared

package/src/memory.ts

@@ -56,6 +56,21 @@ export const TYPE_STRING_VALUE_REF = 7;
  * the a/b/c fields), avoiding a heap allocation and the string-table write.
  */
 export const TYPE_INLINE_STRING = 8;
+/**
+ * A nested object block stored in the DataTable. `a` is the DataTable byte
+ * offset of the object block (same layout as a top-level object).
+ */
+export const TYPE_OBJECT_REF = 9;
+/**
+ * A live reference to another shared key (used for nested `Shared` objects so
+ * changes stay in sync). `a` is the referenced key's stable Index Table index.
+ */
+export const TYPE_KEY_REF = 10;
+/**
+ * The `null` value. No payload in a/b/c — the presence of the slot's type is
+ * the entire value. `undefined` is intentionally still not representable.
+ */
+export const TYPE_NULL = 11;
 
 const SLOT_SIZE = 16;
 const OBJECT_HEADER = 16;
@@ -96,6 +111,12 @@ const slotView = new DataView(new ArrayBuffer(8));
 export interface StringRef {
   offset: number;
   length: number;
+  /**
+   * Reserved block size in the ArrayTable (>= ARRAY_HEADER + length). Only
+   * set for string values stored in the ArrayTable; used to grow a block in
+   * place when a string is overwritten with a longer one.
+   */
+  reserved?: number;
 }
 
 export interface ArrayRef {
@@ -159,7 +180,12 @@ export function stringRefSlot(ref: StringRef): ValueSlot {
 
 /** Encode a string value (in the ArrayTable) into a ValueSlot. */
 export function stringValueRefSlot(ref: StringRef): ValueSlot {
-  return { type: TYPE_STRING_VALUE_REF, a: ref.offset, b: ref.length, c: 0 };
+  return {
+    type: TYPE_STRING_VALUE_REF,
+    a: ref.offset,
+    b: ref.length,
+    c: ref.reserved ?? 0,
+  };
 }
 
 /** Encode a bigint stored as a decimal string into a ValueSlot. */
@@ -172,6 +198,21 @@ export function arrayRefSlot(ref: ArrayRef): ValueSlot {
   return { type: TYPE_ARRAY_REF, a: ref.offset, b: ref.count, c: ref.capacity };
 }
 
+/** Encode a reference to a nested object block (DataTable offset). */
+export function objectRefSlot(offset: number): ValueSlot {
+  return { type: TYPE_OBJECT_REF, a: offset, b: 0, c: 0 };
+}
+
+/** Encode a live reference to another shared key (by stable Index Table index). */
+export function keyRefSlot(index: number): ValueSlot {
+  return { type: TYPE_KEY_REF, a: index, b: 0, c: 0 };
+}
+
+/** Encode the `null` value. */
+export function nullSlot(): ValueSlot {
+  return { type: TYPE_NULL, a: 0, b: 0, c: 0 };
+}
+
 /** Decode a ValueSlot into a JS value (primitives) or a ref object. */
 export function decodeSlot(slot: ValueSlot): unknown {
   switch (slot.type) {
@@ -191,8 +232,14 @@ export function decodeSlot(slot: ValueSlot): unknown {
       return { offset: slot.a, length: slot.b };
     case TYPE_STRING_VALUE_REF:
       return { offset: slot.a, length: slot.b };
+    case TYPE_NULL:
+      return null;
     case TYPE_ARRAY_REF:
       return { offset: slot.a, count: slot.b, capacity: slot.c };
+    case TYPE_OBJECT_REF:
+      return { offset: slot.a };
+    case TYPE_KEY_REF:
+      return { index: slot.a };
     default:
       throw new Error(`Unknown slot type ${slot.type}`);
   }
@@ -675,13 +722,34 @@ export class SharedMemory {
     // unbounded ArrayTable growth. The block's objectId header is preserved.
     if (oldRef !== undefined && size <= ARRAY_HEADER + oldRef.length) {
       this.arrayTable.writeBytes(oldRef.offset + ARRAY_HEADER, bytes);
-      return { offset: oldRef.offset, length: bytes.byteLength };
+      return {
+        offset: oldRef.offset,
+        length: bytes.byteLength,
+        reserved: oldRef.reserved ?? size,
+      };
+    }
+    // The new string is longer than the old block. If the old block is the
+    // last allocated block (its reserved end is the current used length), grow
+    // it in place so repeated writes to the same property don't leak dead
+    // blocks. This also covers the shrink-then-grow case: a block that was
+    // reserved for a longer string but currently holds a shorter one can be
+    // grown back into its own reserved tail.
+    if (oldRef !== undefined && oldRef.reserved !== undefined) {
+      const reservedEnd = oldRef.offset + oldRef.reserved;
+      if (this.arrayTable.growInPlace(reservedEnd, size - oldRef.reserved)) {
+        this.arrayTable.writeBytes(oldRef.offset + ARRAY_HEADER, bytes);
+        return {
+          offset: oldRef.offset,
+          length: bytes.byteLength,
+          reserved: Math.max(oldRef.reserved, size),
+        };
+      }
     }
     const offset = this.arrayTable.reserve(size);
     const objectId = this.nextObjectId++;
     this.arrayTable.setInt32(offset, objectId);
     this.arrayTable.writeBytes(offset + ARRAY_HEADER, bytes);
-    return { offset, length: bytes.byteLength };
+    return { offset, length: bytes.byteLength, reserved: size };
   }
 
   /** Read a string value from the ArrayTable by reference. */
@@ -1117,6 +1185,14 @@ export class SharedMemory {
   getObjectLayout(key: string): ObjectLayout | null {
     const offset = this.lookup(key);
     if (offset === null) return null;
+    return this.getObjectLayoutAtOffset(offset);
+  }
+
+  /**
+   * Get the stable layout of an object block at a DataTable offset (top-level
+   * or nested). Returns null if the offset is not an object block.
+   */
+  getObjectLayoutAtOffset(offset: number): ObjectLayout | null {
     if (this.dataTable.getInt32(offset) !== TYPE_OBJECT) return null;
     const count = this.dataTable.getInt32(offset + 4);
     const properties = new Map<string, number>();
@@ -1189,6 +1265,20 @@ export class SharedMemory {
     return null;
   }
 
+  /**
+   * Read the key string for a known stable index. Used to resolve a live
+   * shared-key reference (TYPE_KEY_REF) back to its key so a wrapper can be
+   * reconstructed. Returns null if the index is out of range.
+   */
+  getKeyByIndex(index: number): string | null {
+    const count = this.indexTable.getInt32(0);
+    if (index >= count) return null;
+    const entryOffset = INDEX_HEADER + index * INDEX_ENTRY_SIZE;
+    const keyOffset = this.indexTable.getInt32(entryOffset);
+    const keyLength = this.indexTable.getInt32(entryOffset + 4);
+    return this.readString({ offset: keyOffset, length: keyLength });
+  }
+
   /**
    * Int32Array index of a key's version cell within the Index Table buffer.
    * Stable for the lifetime of the key (the Index Table is never reordered or
@@ -1339,12 +1429,21 @@ export class SharedMemory {
           stringValueBlocks.add(slot.a);
           arrayBlockSizes.set(
             slot.a,
-            Math.max(ARRAY_HEADER + slot.b, MIN_BLOCK_SIZE),
+            Math.max(slot.c || ARRAY_HEADER + slot.b, MIN_BLOCK_SIZE),
           );
           break;
         case TYPE_ARRAY_REF:
           markArray(slot.a, slot.b, slot.c);
           break;
+        case TYPE_OBJECT_REF:
+          // Nested object block lives in the DataTable; mark it recursively.
+          markObject(slot.a);
+          break;
+        case TYPE_KEY_REF:
+          // A live reference to another shared key. The referenced key is
+          // marked separately when the Index Table is walked (Phase 1), so
+          // nothing to do here.
+          break;
       }
     };
 
@@ -1460,14 +1559,14 @@ export class SharedMemory {
         const nameOffset = this.dataTable.getInt32(cursor);
         this.dataTable.setInt32(cursor, stringRemap.get(nameOffset)!);
         cursor += NAME_REF_SIZE;
-        remapSlot(this.dataTable, cursor, stringRemap, arrayRemap);
+        remapSlot(this.dataTable, cursor, stringRemap, arrayRemap, objectRemap);
         cursor += SLOT_SIZE;
       }
     }
     for (const oldOffset of sortedData) {
       if (this.dataTable.getInt32(oldOffset) === TYPE_OBJECT) continue;
       const newOff = objectRemap.get(oldOffset)!;
-      remapSlot(this.dataTable, newOff, stringRemap, arrayRemap);
+      remapSlot(this.dataTable, newOff, stringRemap, arrayRemap, objectRemap);
     }
     for (const oldOffset of sortedArrays) {
       if (stringValueBlocks.has(oldOffset)) continue;
@@ -1480,6 +1579,7 @@ export class SharedMemory {
           newOff + ARRAY_HEADER + i * SLOT_SIZE,
           stringRemap,
           arrayRemap,
+          objectRemap,
         );
       }
     }
@@ -1514,15 +1614,25 @@ function readSlot(buf: GrowableBuffer, offset: number): ValueSlot {
   };
 }
 
-/** Copy `len` bytes from `src` to `dst` in the same buffer (dst <= src). */
+/** Copy `len` bytes from `src` to `dst` in the same buffer, overlap-safe. */
 function copyBytes(
   buf: GrowableBuffer,
   dst: number,
   src: number,
   len: number,
 ): void {
-  for (let i = 0; i < len; i++) {
-    buf.setUint8(dst + i, buf.getUint8(src + i));
+  // `dst` may be greater than `src` when a small block compacts forward over
+  // the tail of a later block still holding its old data (e.g. string-value
+  // blocks interleaved with array blocks). Copy backwards in that case, like
+  // memmove, so overlapping source/destination ranges aren't corrupted.
+  if (dst > src) {
+    for (let i = len - 1; i >= 0; i--) {
+      buf.setUint8(dst + i, buf.getUint8(src + i));
+    }
+  } else {
+    for (let i = 0; i < len; i++) {
+      buf.setUint8(dst + i, buf.getUint8(src + i));
+    }
   }
 }
 
@@ -1536,11 +1646,16 @@ function remapSlot(
   offset: number,
   stringRemap: Map<number, number>,
   arrayRemap: Map<number, number>,
+  objectRemap?: Map<number, number>,
 ): void {
   const type = buf.getInt32(offset);
   if (type === TYPE_STRING_REF || type === TYPE_BIGINT_STR) {
     buf.setInt32(offset + 4, stringRemap.get(buf.getInt32(offset + 4))!);
   } else if (type === TYPE_ARRAY_REF || type === TYPE_STRING_VALUE_REF) {
     buf.setInt32(offset + 4, arrayRemap.get(buf.getInt32(offset + 4))!);
+  } else if (type === TYPE_OBJECT_REF && objectRemap !== undefined) {
+    buf.setInt32(offset + 4, objectRemap.get(buf.getInt32(offset + 4))!);
   }
+  // TYPE_KEY_REF (live shared-key reference) needs no remap: it stores the
+  // key's stable Index Table index, which never changes.
 }