bun-shared-memory 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.2.1] - 2026-11-04
+
+### Performance
+
+- Inline the read-cache fast path in `readProp`/`readValue` instead of calling
+  `readCachedValue`, which returned a polymorphic `{hit,value}` union and
+  allocated an object on every cache hit. Keeping the read path monomorphic
+  lets the JIT optimize it: number reads dropped from ~12× to ~6× slower than
+  native, boolean reads from ~8.4× to ~5.5×, and all array index reads
+  improved (array-read summary ~9.7× → ~8.7×).
+- Add `updateBigIntSlot`/`updateArrayBigIntSlot` fast paths that write int64
+  bigints directly into the slot, avoiding the `ValueSlot` object allocation
+  of the generic encode path. `bigint[]` index writes dropped from ~24.8× to
+  ~18× slower than native.
+- Extract the array-proxy set handler body into a named `writeArrayProp`
+  function and inline the `writeLock`, so no closure is allocated per write.
+- 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
+  shared memory).
+
 ## [0.2.0] - 2026-11-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
   "type": "module",
   "sideEffects": false,
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "cofusion": "^0.0.1",
+    "cofusion": "^0.0.2",
     "elysia": "^1.4.30"
   }
 }

package/src/memory.ts

@@ -812,6 +812,20 @@ export class SharedMemory {
     buf.setInt32(off + 12, 0);
   }
 
+  /**
+   * Fast-path: write an int64 bigint into an array slot directly, avoiding
+   * the ValueSlot object allocation and the 4 separate Int32 writes.
+   */
+  updateArrayBigIntSlot(ref: ArrayRef, index: number, value: bigint): void {
+    slotView.setBigInt64(0, value, true);
+    const buf = this.arrayTable;
+    const off = ref.offset + ARRAY_HEADER + index * SLOT_SIZE;
+    buf.setInt32(off, TYPE_BIGINT);
+    buf.setInt32(off + 4, slotView.getInt32(0, true));
+    buf.setInt32(off + 8, slotView.getInt32(4, true));
+    buf.setInt32(off + 12, 0);
+  }
+
   /**
    * Fast-path: write a short string inline into an array slot (up to 11
    * UTF-8 bytes), avoiding a heap allocation and the string-table write.
@@ -970,6 +984,19 @@ export class SharedMemory {
     buf.setInt32(offset + 12, 0);
   }
 
+  /**
+   * Fast-path: write an int64 bigint slot directly into the DataTable,
+   * avoiding the ValueSlot object allocation of the generic path.
+   */
+  updateBigIntSlot(offset: number, value: bigint): void {
+    slotView.setBigInt64(0, value, true);
+    const buf = this.dataTable;
+    buf.setInt32(offset, TYPE_BIGINT);
+    buf.setInt32(offset + 4, slotView.getInt32(0, true));
+    buf.setInt32(offset + 8, slotView.getInt32(4, true));
+    buf.setInt32(offset + 12, 0);
+  }
+
   /**
    * Fast-path: write a short string inline into the slot itself (up to 11
    * UTF-8 bytes), avoiding a heap allocation and the string-table write.

package/src/shared.ts

@@ -443,8 +443,14 @@ function readProp(
   prop: string | symbol,
   arrayCapacity?: number,
 ): unknown {
-  const fast = readCachedValue(mem, key);
-  const value = fast.hit ? fast.value : readValue(mem, key);
+  // Inline the read-cache fast path (instead of calling readCachedValue, which
+  // returns a polymorphic {hit,value} union and allocates an object on every
+  // cache hit). Keeping this monomorphic lets the JIT optimize the hot read.
+  const cached = readCache.get(key);
+  const value =
+    cached !== undefined && cached.version === mem.getVersion(cached.index)
+      ? cached.value
+      : readValue(mem, key);
   if (Array.isArray(value)) {
     return getTopLevelArrayMember(mem, key, value, prop, arrayCapacity);
   }
@@ -493,6 +499,56 @@ function readObjectProp(
   return value;
 }
 
+/**
+ * Write a single object-property slot whose offset is already resolved
+ * (cached by the caller, e.g. the accessor setter). Avoids the
+ * `getObjectLayout` Map lookup + `properties.get` per write on the hot path.
+ */
+function writeObjectSlot(
+  mem: SharedMemory,
+  key: string,
+  slotOffset: number,
+  val: unknown,
+  arrayCapacity?: number,
+  target?: WriteTarget,
+): void {
+  if (typeof val === "number") {
+    // Fast path: numbers need no old-slot read (freeSlotRefs is a no-op)
+    // and no in-place string reuse; write the float64 directly.
+    mem.updateNumberSlot(slotOffset, val);
+    bumpTarget(mem, key, target);
+    return;
+  }
+  if (typeof val === "boolean") {
+    // Fast path: booleans need no old-slot read (freeSlotRefs is a no-op)
+    // and no in-place string reuse; write the 4 Int32s directly.
+    mem.updateBooleanSlot(slotOffset, val);
+    bumpTarget(mem, key, target);
+    return;
+  }
+  if (typeof val === "bigint" && val >= MIN_INT64 && val <= MAX_INT64) {
+    // Fast path: int64 bigints are written directly, avoiding the ValueSlot
+    // object allocation of the generic path.
+    mem.updateBigIntSlot(slotOffset, val);
+    bumpTarget(mem, key, target);
+    return;
+  }
+  if (typeof val === "string") {
+    // Fast path: short strings are written inline into the slot itself.
+    if (mem.updateInlineStringSlot(slotOffset, val)) {
+      bumpTarget(mem, key, target);
+      return;
+    }
+  }
+  const oldSlot = mem.readValueSlot(slotOffset);
+  freeSlotRefs(mem, oldSlot);
+  mem.updateValueSlot(
+    slotOffset,
+    encodeValue(mem, val, arrayCapacity, oldSlot),
+  );
+  bumpTarget(mem, key, target);
+}
+
 /**
  * Write a single property of a shared object value in place.
  *
@@ -544,27 +600,7 @@ function writePropInner(
           `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
         );
       }
-      if (typeof val === "number") {
-        // Fast path: numbers need no old-slot read (freeSlotRefs is a no-op)
-        // and no in-place string reuse; write the float64 directly.
-        mem.updateNumberSlot(slotOffset, val);
-        bumpTarget(mem, key, target);
-        return;
-      }
-      if (typeof val === "string") {
-        // Fast path: short strings are written inline into the slot itself.
-        if (mem.updateInlineStringSlot(slotOffset, val)) {
-          bumpTarget(mem, key, target);
-          return;
-        }
-      }
-      const oldSlot = mem.readValueSlot(slotOffset);
-      freeSlotRefs(mem, oldSlot);
-      mem.updateValueSlot(
-        slotOffset,
-        encodeValue(mem, val, arrayCapacity, oldSlot),
-      );
-      bumpTarget(mem, key, target);
+      writeObjectSlot(mem, key, slotOffset, val, arrayCapacity, target);
       return;
     }
   }
@@ -622,6 +658,13 @@ function writePropInner(
       bumpTarget(mem, key, target);
       return;
     }
+    if (typeof val === "bigint" && val >= MIN_INT64 && val <= MAX_INT64) {
+      // Fast path: int64 bigints are written directly, avoiding the
+      // ValueSlot object allocation of the generic path.
+      mem.updateArrayBigIntSlot(ref, index, val);
+      bumpTarget(mem, key, target);
+      return;
+    }
     if (typeof val === "string") {
       // Fast path: short strings are written inline into the array slot.
       if (mem.updateArrayInlineStringSlot(ref, index, val)) {
@@ -811,6 +854,12 @@ function createSharedRef<T>(
       // recreate the array proxy on every access. The proxy reads fresh data
       // on each access, so it stays correct without being recreated.
       let arrayProxy: unknown[] | undefined;
+      // Cached object slot offset for this property so writes skip the
+      // getObjectLayout Map lookup + properties.get on the hot path.
+      // Invalidated when the layout version changes (defragmentation moves
+      // the object block).
+      let slotOffset: number | undefined;
+      let slotLayoutVersion = -1;
       Object.defineProperty(ref, name, {
         enumerable: true,
         configurable: false,
@@ -845,7 +894,45 @@ function createSharedRef<T>(
         },
         set(v: unknown) {
           target.__cache = undefined;
-          writeProp(mem, key, name, v, arrayCapacity, target);
+          mem.beginWrite();
+          if (mem.isDefragmenting()) {
+            // A defrag pass may move the object block: drop the cached slot
+            // offset so it is re-resolved, and run the write under the mutex.
+            mem.endWrite();
+            slotOffset = undefined;
+            slotLayoutVersion = -1;
+            mem.withLock(() =>
+              writePropInner(mem, key, name, v, arrayCapacity, target),
+            );
+            return;
+          }
+          try {
+            // Write directly to the cached slot offset when still valid,
+            // skipping the getObjectLayout Map lookup + properties.get.
+            if (slotLayoutVersion !== mem.getLayoutVersion()) {
+              slotOffset = undefined;
+              slotLayoutVersion = mem.getLayoutVersion();
+            }
+            if (slotOffset === undefined) {
+              const layout = getObjectLayout(mem, key);
+              if (layout === null) {
+                // Not an object (shouldn't happen for an object accessor).
+                throw new TypeError(
+                  `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
+                );
+              }
+              const so = layout.properties.get(name);
+              if (so === undefined) {
+                throw new TypeError(
+                  `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
+                );
+              }
+              slotOffset = so;
+            }
+            writeObjectSlot(mem, key, slotOffset, v, arrayCapacity, target);
+          } finally {
+            mem.endWrite();
+          }
         },
       });
     }
@@ -890,22 +977,6 @@ function createSharedRef<T>(
   }) as unknown as SharedRef<T>;
 }
 
-/**
- * Lock-free fast path: if the cached version matches the current version cell,
- * the cached value is still valid. Returns the cached value, or a miss marker.
- * Kept small so the JIT can inline it into hot accessor getters.
- */
-function readCachedValue(
-  mem: SharedMemory,
-  key: string,
-): { hit: true; value: unknown } | { hit: false } {
-  const cached = readCache.get(key);
-  if (cached !== undefined && cached.version === mem.getVersion(cached.index)) {
-    return { hit: true, value: cached.value };
-  }
-  return { hit: false };
-}
-
 /**
  * Read the full value for a key from shared memory, using the read cache.
  *
@@ -920,10 +991,13 @@ function readValue(
     __cache?: { version: number; value: unknown; index: number };
   },
 ): unknown {
-  const fast = readCachedValue(mem, key);
-  if (fast.hit) return fast.value;
-
+  // Inline the read-cache fast path (see readProp) to avoid the polymorphic
+  // {hit,value} union returned by readCachedValue.
   const cached = readCache.get(key);
+  if (cached !== undefined && cached.version === mem.getVersion(cached.index)) {
+    return cached.value;
+  }
+
   const index = cached !== undefined ? cached.index : getIndex(mem, key);
   const version = mem.getVersion(index);
 
@@ -1037,6 +1111,10 @@ function writeValueInner(
       // no-op) and no in-place string reuse.
       if (typeof value === "boolean") {
         mem.updateBooleanSlot(existing, value);
+      } else if (value >= MIN_INT64 && value <= MAX_INT64) {
+        // Fast path: int64 bigints are written directly, avoiding the
+        // ValueSlot object allocation of the generic path.
+        mem.updateBigIntSlot(existing, value);
       } else {
         mem.updateValueSlot(existing, encodeValue(mem, value, arrayCapacity));
       }
@@ -1301,6 +1379,151 @@ function createArrayProxy(
   let cachedRef:
     { offset: number; count: number; capacity: number } | undefined;
   let cachedLayoutVersion = -1;
+  // Cached version-cell index for this key, so writes can bump the version
+  // cell without a Map lookup on every write. Stable for the key's lifetime.
+  let cachedIndex: number | undefined;
+
+  /** Bump the key's version cell using the cached index (resolved lazily). */
+  function bumpCached(): void {
+    if (cachedIndex === undefined) {
+      cachedIndex = getIndex(mem, key);
+    }
+    mem.bumpVersion(cachedIndex);
+  }
+
+  /**
+   * Write a single array-property slot in place. Defined once (not per call)
+   * so the set handler can inline the writeLock without allocating a closure
+   * on every write. Mutates the cached slot offset/ref/layout version.
+   */
+  function writeArrayProp(arrProp: string | symbol, val: unknown): boolean {
+    // Refresh the cached slot offset when the layout version changed
+    // (defragmentation may have moved the object block).
+    if (cachedLayoutVersion !== mem.getLayoutVersion()) {
+      cachedSlotOffset = undefined;
+      cachedRef = undefined;
+      cachedLayoutVersion = mem.getLayoutVersion();
+    }
+    if (cachedSlotOffset === undefined) {
+      const layout = getObjectLayout(mem, key);
+      if (layout === null) {
+        // Fallback: full read-modify-write.
+        return mutateValue<Record<string, unknown>, boolean>(
+          mem,
+          key,
+          (fresh) => {
+            const arr = fresh[prop] as unknown[];
+            (arr as unknown as Record<string | symbol, unknown>)[arrProp] = val;
+            return true;
+          },
+          arrayCapacity,
+        );
+      }
+      const so = layout.properties.get(prop);
+      if (so === undefined) {
+        throw new TypeError(
+          `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
+        );
+      }
+      cachedSlotOffset = so;
+    }
+    const propSlot = mem.readValueSlot(cachedSlotOffset);
+    if (
+      propSlot.type === TYPE_ARRAY_REF &&
+      typeof arrProp === "string" &&
+      /^\d+$/.test(arrProp)
+    ) {
+      const index = Number(arrProp);
+      // Use the cached ref when valid; re-read when the array may have
+      // grown past the cached count (push) or the layout changed.
+      let ref = cachedRef;
+      if (
+        ref === undefined ||
+        index >= ref.count ||
+        cachedLayoutVersion !== mem.getLayoutVersion()
+      ) {
+        ref = {
+          offset: propSlot.a,
+          count: propSlot.b,
+          capacity: propSlot.c,
+        };
+        cachedRef = ref;
+      }
+      if (index >= ref.count) {
+        throw new RangeError(
+          `Index ${index} out of bounds for array of length ${ref.count}`,
+        );
+      }
+      if (typeof val === "number") {
+        // Fast path: numbers need no old-slot read (freeSlotRefs is a no-op).
+        mem.updateArrayNumberSlot(ref, index, val);
+        bumpCached();
+        return true;
+      }
+      if (typeof val === "boolean") {
+        // Fast path: booleans need no old-slot read (freeSlotRefs is a no-op).
+        mem.updateArrayBooleanSlot(ref, index, val);
+        bumpCached();
+        return true;
+      }
+      if (typeof val === "bigint" && val >= MIN_INT64 && val <= MAX_INT64) {
+        // Fast path: int64 bigints are written directly, avoiding the
+        // ValueSlot object allocation of the generic path.
+        mem.updateArrayBigIntSlot(ref, index, val);
+        bumpCached();
+        return true;
+      }
+      if (typeof val === "string") {
+        // Fast path: short strings are written inline into the slot.
+        if (mem.updateArrayInlineStringSlot(ref, index, val)) {
+          bumpCached();
+          return true;
+        }
+      }
+      freeSlotRefs(mem, mem.readArraySlot(ref, index));
+      mem.updateArraySlot(ref, index, encodeValue(mem, val));
+      bumpCached();
+      return true;
+    }
+    // Array property length write: shrink/grow in place without re-encoding
+    // the whole object (which would leave a dead slot).
+    if (propSlot.type === TYPE_ARRAY_REF && arrProp === "length") {
+      const newLen = Number(val);
+      if (!Number.isInteger(newLen) || newLen < 0) {
+        throw new RangeError("Invalid array length");
+      }
+      const ref = {
+        offset: propSlot.a,
+        count: propSlot.b,
+        capacity: propSlot.c,
+      };
+      if (newLen <= ref.capacity) {
+        mem.updateValueSlot(
+          cachedSlotOffset,
+          arrayRefSlot({
+            offset: ref.offset,
+            count: newLen,
+            capacity: ref.capacity,
+          }),
+        );
+        bumpCached();
+        return true;
+      }
+      // Growing beyond capacity falls through to the full read-modify-write.
+    }
+    // Fallback: full read-modify-write.
+    return mutateValue<Record<string, unknown>, boolean>(
+      mem,
+      key,
+      (fresh) => {
+        const arr = fresh[prop] as unknown[];
+        (arr as unknown as Record<string | symbol, unknown>)[arrProp] = val;
+        return true;
+      },
+      arrayCapacity,
+    );
+  }
+
   return new Proxy([] as unknown[], {
     get(_target, arrProp) {
       // push/pop on an array property: operate directly on the array ref
@@ -1357,130 +1580,18 @@ function createArrayProxy(
     },
     set(_target, arrProp, val) {
       // In-place update: write only the affected array slot instead of
-      // decoding and re-encoding the whole object.
-      return writeLock(mem, () => {
-        // Refresh the cached slot offset when the layout version changed
-        // (defragmentation may have moved the object block).
-        if (cachedLayoutVersion !== mem.getLayoutVersion()) {
-          cachedSlotOffset = undefined;
-          cachedRef = undefined;
-          cachedLayoutVersion = mem.getLayoutVersion();
-        }
-        if (cachedSlotOffset === undefined) {
-          const layout = getObjectLayout(mem, key);
-          if (layout === null) {
-            // Fallback: full read-modify-write.
-            return mutateValue<Record<string, unknown>, boolean>(
-              mem,
-              key,
-              (fresh) => {
-                const arr = fresh[prop] as unknown[];
-                (arr as unknown as Record<string | symbol, unknown>)[arrProp] =
-                  val;
-                return true;
-              },
-              arrayCapacity,
-            );
-          }
-          const so = layout.properties.get(prop);
-          if (so === undefined) {
-            throw new TypeError(
-              `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
-            );
-          }
-          cachedSlotOffset = so;
-        }
-        const propSlot = mem.readValueSlot(cachedSlotOffset);
-        if (
-          propSlot.type === TYPE_ARRAY_REF &&
-          typeof arrProp === "string" &&
-          /^\d+$/.test(arrProp)
-        ) {
-          const index = Number(arrProp);
-          // Use the cached ref when valid; re-read when the array may have
-          // grown past the cached count (push) or the layout changed.
-          let ref = cachedRef;
-          if (
-            ref === undefined ||
-            index >= ref.count ||
-            cachedLayoutVersion !== mem.getLayoutVersion()
-          ) {
-            ref = {
-              offset: propSlot.a,
-              count: propSlot.b,
-              capacity: propSlot.c,
-            };
-            cachedRef = ref;
-          }
-          if (index >= ref.count) {
-            throw new RangeError(
-              `Index ${index} out of bounds for array of length ${ref.count}`,
-            );
-          }
-          if (typeof val === "number") {
-            // Fast path: numbers need no old-slot read (freeSlotRefs is a
-            // no-op) and no in-place string reuse.
-            mem.updateArrayNumberSlot(ref, index, val);
-            bump(mem, key);
-            return true;
-          }
-          if (typeof val === "boolean") {
-            // Fast path: booleans need no old-slot read (freeSlotRefs is a
-            // no-op).
-            mem.updateArrayBooleanSlot(ref, index, val);
-            bump(mem, key);
-            return true;
-          }
-          if (typeof val === "string") {
-            // Fast path: short strings are written inline into the slot.
-            if (mem.updateArrayInlineStringSlot(ref, index, val)) {
-              bump(mem, key);
-              return true;
-            }
-          }
-          freeSlotRefs(mem, mem.readArraySlot(ref, index));
-          mem.updateArraySlot(ref, index, encodeValue(mem, val));
-          bump(mem, key);
-          return true;
-        }
-        // Array property length write: shrink/grow in place without
-        // re-encoding the whole object (which would leave a dead slot).
-        if (propSlot.type === TYPE_ARRAY_REF && arrProp === "length") {
-          const newLen = Number(val);
-          if (!Number.isInteger(newLen) || newLen < 0) {
-            throw new RangeError("Invalid array length");
-          }
-          const ref = {
-            offset: propSlot.a,
-            count: propSlot.b,
-            capacity: propSlot.c,
-          };
-          if (newLen <= ref.capacity) {
-            mem.updateValueSlot(
-              cachedSlotOffset,
-              arrayRefSlot({
-                offset: ref.offset,
-                count: newLen,
-                capacity: ref.capacity,
-              }),
-            );
-            bump(mem, key);
-            return true;
-          }
-          // Growing beyond capacity falls through to the full read-modify-write.
-        }
-        // Fallback: full read-modify-write.
-        return mutateValue<Record<string, unknown>, boolean>(
-          mem,
-          key,
-          (fresh) => {
-            const arr = fresh[prop] as unknown[];
-            (arr as unknown as Record<string | symbol, unknown>)[arrProp] = val;
-            return true;
-          },
-          arrayCapacity,
-        );
-      });
+      // decoding and re-encoding the whole object. Inline writeLock to avoid
+      // a closure allocation on the hot path.
+      mem.beginWrite();
+      if (mem.isDefragmenting()) {
+        mem.endWrite();
+        return mem.withLock(() => writeArrayProp(arrProp, val));
+      }
+      try {
+        return writeArrayProp(arrProp, val);
+      } finally {
+        mem.endWrite();
+      }
     },
   });
 }