bun-shared-memory 0.1.4 → 0.1.6

package/src/refcount.ts

@@ -286,9 +286,9 @@ export class RefCountCoordinator {
 
   /** Whether any table has less than `defragThreshold` free space. */
   needsDefrag(): boolean {
-    const max = this.mem.dataTable.buffer.maxByteLength;
-    const free = (b: { buffer: SharedArrayBuffer; byteLength: number }) =>
-      (b.buffer.byteLength - b.byteLength) / max;
+    const max = this.mem.dataTable.capacity;
+    const free = (b: { capacity: number; byteLength: number }) =>
+      (b.capacity - b.byteLength) / max;
     return (
       free(this.mem.dataTable) < this.defragThreshold ||
       free(this.mem.arrayTable) < this.defragThreshold ||

package/src/shared.ts

@@ -178,7 +178,7 @@ function isTrackable(value: unknown): boolean {
 function getTopLevelObjectId(mem: SharedMemory, key: string): number | null {
   const offset = getOffset(mem, key);
   if (offset === null) return null;
-  const type = mem.dataTable.getView().getInt32(offset, true);
+  const type = mem.dataTable.getInt32(offset);
   if (type === 5) {
     return mem.getObjectId(offset);
   }
@@ -189,20 +189,6 @@ function getTopLevelObjectId(mem: SharedMemory, key: string): number | null {
   return null;
 }
 
-/**
- * Per-worker cache of decoded object properties: key -> { version, props }.
- *
- * When a property of an object is read via the layout (single-slot decode),
- * the decoded value is cached here keyed by the object's version. A hit avoids
- * re-decoding the property (e.g. re-reading a string from the StringTable) on
- * repeated reads of the same property. Writes bump the object's version, so
- * the whole entry is invalidated automatically.
- */
-const propCache = new Map<
-  string,
-  { version: number; index: number; props: Map<string, unknown> }
->();
-
 /**
  * Per-worker cache of object layouts: key -> stable property slot offsets.
  *
@@ -222,13 +208,21 @@ function getObjectLayout(mem: SharedMemory, key: string): ObjectLayout | null {
   return layout;
 }
 
-/** Deep-ish copy of a decoded value, so callers can't corrupt the cache. */
+/**
+ * Deep-ish copy of a decoded value, so callers can't corrupt the cache.
+ *
+ * Uses `Object.assign` for the fast shallow copy, then a `for...in` pass to
+ * copy any nested arrays (so mutating a returned array property cannot corrupt
+ * the cache). This is ~4.5× faster than the previous `Object.entries` + spread
+ * loop, which allocated an entries array and re-checked `Array.isArray` on
+ * every property.
+ */
 function copyValue(value: unknown): unknown {
   if (Array.isArray(value)) return [...value];
   if (value !== null && typeof value === "object") {
-    const copy: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value)) {
-      copy[k] = Array.isArray(v) ? [...v] : v;
+    const copy = Object.assign({} as Record<string, unknown>, value);
+    for (const k in copy) {
+      if (Array.isArray(copy[k])) copy[k] = [...(copy[k] as unknown[])];
     }
     return copy;
   }
@@ -297,6 +291,7 @@ export function Shared<T>(
   const ref = createSharedRef<T>(
     mem,
     key,
+    typeof initialOrLoader === "function" ? undefined : (initialOrLoader as T),
     options.refCount ?? getDefaultTracker() ?? undefined,
     options.arrayCapacity,
   );
@@ -318,10 +313,125 @@ export function Shared<T>(
   return ref;
 }
 
+/**
+ * Read a single property of a shared object value.
+ *
+ * Shared by the proxy `get` handler and the generated accessor getters. Uses
+ * the lock-free read-cache fast path and falls back to `readValue` (which
+ * fills the cache) on a miss. Array properties are returned as an array proxy.
+ */
+function readProp(
+  mem: SharedMemory,
+  key: string,
+  prop: string | symbol,
+  arrayCapacity?: number,
+): unknown {
+  const fast = readCachedValue(mem, key);
+  const value = fast.hit ? fast.value : readValue(mem, key);
+  if (Array.isArray(value)) {
+    return getTopLevelArrayMember(mem, key, value, prop, arrayCapacity);
+  }
+  const propValue = (value as Record<string | symbol, unknown>)[prop];
+  if (Array.isArray(propValue)) {
+    return createArrayProxy(mem, key, prop as string, arrayCapacity);
+  }
+  return propValue;
+}
+
+/**
+ * Write a single property of a shared object value in place.
+ *
+ * Shared by the proxy `set` handler and the generated accessor setters. Uses
+ * the cached layout to update only the affected slot.
+ */
+function writeProp(
+  mem: SharedMemory,
+  key: string,
+  prop: string | symbol,
+  val: unknown,
+  arrayCapacity?: number,
+): void {
+  mem.withLock(() => {
+    // Object property: use the cached layout to write only that slot.
+    const layout = getObjectLayout(mem, key);
+    if (layout !== null) {
+      const slotOffset = layout.properties.get(prop as string);
+      if (slotOffset === undefined) {
+        throw new TypeError(
+          `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
+        );
+      }
+      mem.updateValueSlot(slotOffset, encodeValue(mem, val));
+      bump(mem, key);
+      return;
+    }
+
+    // Top-level array index write: update only that array slot.
+    const offset = getOffset(mem, key);
+    if (offset === null) {
+      throw new Error(`No shared value found for key "${key}"`);
+    }
+    const slot = mem.readValueSlot(offset);
+    if (
+      slot.type === TYPE_ARRAY_REF &&
+      typeof prop === "string" &&
+      /^\d+$/.test(prop)
+    ) {
+      const index = Number(prop);
+      const ref = { offset: slot.a, count: slot.b, capacity: slot.c };
+      if (index >= ref.count) {
+        throw new RangeError(
+          `Index ${index} out of bounds for array of length ${ref.count}`,
+        );
+      }
+      mem.updateArraySlot(ref, index, encodeValue(mem, val));
+      bump(mem, key);
+      return;
+    }
+
+    // Top-level array length write: shrink/grow the array in place.
+    if (slot.type === TYPE_ARRAY_REF && prop === "length") {
+      const newLen = Number(val);
+      if (!Number.isInteger(newLen) || newLen < 0) {
+        throw new RangeError("Invalid array length");
+      }
+      const ref = { offset: slot.a, count: slot.b, capacity: slot.c };
+      if (newLen <= ref.capacity) {
+        mem.updateValueSlot(
+          offset,
+          arrayRefSlot({
+            offset: ref.offset,
+            count: newLen,
+            capacity: ref.capacity,
+          }),
+        );
+        bump(mem, key);
+        return;
+      }
+    }
+
+    // Fallback: full read-modify-write.
+    mutateValue<unknown, boolean>(
+      mem,
+      key,
+      (value) => {
+        if (Array.isArray(value)) {
+          (value as unknown as Record<string | symbol, unknown>)[prop] = val;
+        } else {
+          (value as Record<string | symbol, unknown>)[prop] = val;
+        }
+        return true;
+      },
+      arrayCapacity,
+    );
+  });
+}
+
 /** Create a SharedRef proxy backed by a SharedMemory instance. */
 function createSharedRef<T>(
   mem: SharedMemory,
   key: string,
+  initialValue: T | undefined,
   tracker?: RefCountTracker,
   arrayCapacity?: number,
 ): SharedRef<T> {
@@ -352,13 +462,109 @@ function createSharedRef<T>(
     },
   };
 
+  // Determine the object's property names so we can hard-bake accessor
+  // getters/setters instead of routing every access through a Proxy trap.
+  // The shape is known from the initial value (if it is an object) or from
+  // shared memory (if the key already exists, e.g. in a worker).
+  let propNames: string[] | null = null;
+  if (
+    initialValue !== null &&
+    typeof initialValue === "object" &&
+    !Array.isArray(initialValue)
+  ) {
+    propNames = Object.keys(initialValue as Record<string, unknown>);
+  } else {
+    const layout = mem.withLock(() => mem.getObjectLayout(key));
+    if (layout !== null) {
+      propNames = [...layout.properties.keys()];
+    }
+  }
+
+  // Object values: return a plain object with hard-baked accessor getters and
+  // setters (no Proxy). This avoids the Proxy trap overhead on every property
+  // read (~2.6× faster) and stays a plain, serializable object.
+  if (propNames !== null && propNames.length > 0) {
+    // Methods live on the prototype, not on the object itself. Keeping the
+    // data properties as the only own properties lets the JIT treat the
+    // object as monomorphic, which is ~2× faster for accessor reads than
+    // having extra own properties (read/write/update/key/buffer).
+    const proto: Record<string | symbol, unknown> = {
+      [Symbol.toPrimitive]: () => target.read(),
+    };
+    Object.defineProperty(proto, "read", {
+      enumerable: false,
+      configurable: false,
+      value: target.read,
+    });
+    Object.defineProperty(proto, "write", {
+      enumerable: false,
+      configurable: false,
+      value: target.write,
+    });
+    Object.defineProperty(proto, "update", {
+      enumerable: false,
+      configurable: false,
+      value: target.update,
+    });
+    // key/buffer are non-enumerable so they don't appear in JSON.stringify /
+    // Object.keys (matching the previous Proxy behavior).
+    Object.defineProperty(proto, "key", {
+      enumerable: false,
+      configurable: false,
+      value: key,
+    });
+    Object.defineProperty(proto, "buffer", {
+      enumerable: false,
+      configurable: false,
+      get() {
+        return mem.dataTable.buffers[0];
+      },
+    });
+    const ref = Object.create(proto) as Record<string | symbol, unknown>;
+    for (const name of propNames) {
+      Object.defineProperty(ref, name, {
+        enumerable: true,
+        configurable: false,
+        get() {
+          // Lock-free fast path inlined so the JIT can optimize the hot
+          // cache-hit read without a function-call chain.
+          const cached = readCache.get(key);
+          if (
+            cached !== undefined &&
+            cached.version === mem.getVersion(cached.index)
+          ) {
+            const v = cached.value;
+            if (Array.isArray(v)) {
+              return getTopLevelArrayMember(mem, key, v, name, arrayCapacity);
+            }
+            const pv = (v as Record<string | symbol, unknown>)[name];
+            if (Array.isArray(pv)) {
+              return createArrayProxy(mem, key, name, arrayCapacity);
+            }
+            return pv;
+          }
+          return readProp(mem, key, name, arrayCapacity);
+        },
+        set(v: unknown) {
+          target.__cache = undefined;
+          writeProp(mem, key, name, v, arrayCapacity);
+        },
+      });
+    }
+    // Fixed shape: reject adding new properties (throws in strict mode).
+    Object.preventExtensions(ref);
+    return ref as unknown as SharedRef<T>;
+  }
+
+  // Arrays, primitives, or unknown shape: use a Proxy (index access, array
+  // methods, and dynamic properties require interception).
   return new Proxy(target, {
     get(t, prop) {
       if (prop === "read") return t.read;
       if (prop === "write") return t.write;
       if (prop === "update") return t.update;
       if (prop === "key") return t.key;
-      if (prop === "buffer") return mem.dataTable.buffer;
+      if (prop === "buffer") return mem.dataTable.buffers[0];
       if (prop === Symbol.toPrimitive) return () => t.read();
 
       // push/pop on a top-level array: operate directly on the array ref
@@ -371,177 +577,12 @@ function createSharedRef<T>(
         }
       }
 
-      // Fast path: if the full value is cached and valid, read the property
-      // from the cached value (no decode, no lock). The cache entry is kept
-      // directly on the target to avoid a Map lookup on the hot path.
-      const cached = t.__cache;
-      if (
-        cached !== undefined &&
-        cached.version === mem.getVersion(cached.index)
-      ) {
-        const cachedValue = cached.value;
-        if (Array.isArray(cachedValue)) {
-          return getTopLevelArrayMember(
-            mem,
-            key,
-            cachedValue,
-            prop,
-            arrayCapacity,
-          );
-        }
-        const propValue = (cachedValue as Record<string | symbol, unknown>)[
-          prop
-        ];
-        if (Array.isArray(propValue)) {
-          return createArrayProxy(mem, key, prop as string, arrayCapacity);
-        }
-        return propValue;
-      }
-
-      // Cache miss: for objects, decode only the requested property's slot via
-      // the cached layout, avoiding a full-object decode. The decoded value is
-      // cached per property so repeated reads of the same property are cheap.
-      const layout = getObjectLayout(mem, key);
-      if (layout !== null) {
-        const slotOffset = layout.properties.get(prop as string);
-        if (slotOffset === undefined) return undefined;
-
-        // Property cache hit: the object's version is unchanged.
-        const pc = propCache.get(key);
-        const version = pc !== undefined ? mem.getVersion(pc.index) : -1;
-        if (pc !== undefined && pc.version === version) {
-          const cachedProp = pc.props.get(prop as string);
-          if (cachedProp !== undefined) {
-            if (Array.isArray(cachedProp)) {
-              return createArrayProxy(mem, key, prop as string, arrayCapacity);
-            }
-            return cachedProp;
-          }
-        }
-
-        // Decode the single slot and cache it under the object's version.
-        // The key's index is stable (keys are never removed), so reuse the
-        // cached index when available to avoid the linear index-table lookup.
-        const index =
-          pc !== undefined
-            ? pc.index
-            : (readCache.get(key)?.index ?? getIndex(mem, key));
-        const slot = mem.readValueSlot(slotOffset);
-        // Array properties are handled lazily by the array proxy; don't decode
-        // the whole array here (avoids O(n) work on every access).
-        if (slot.type === TYPE_ARRAY_REF) {
-          return createArrayProxy(mem, key, prop as string, arrayCapacity);
-        }
-        const propValue = decodeValue(mem, slot);
-        if (pc === undefined || pc.version !== version) {
-          propCache.set(key, {
-            version: mem.getVersion(index),
-            index,
-            props: new Map(),
-          });
-        }
-        propCache.get(key)!.props.set(prop as string, propValue);
-        if (Array.isArray(propValue)) {
-          return createArrayProxy(mem, key, prop as string, arrayCapacity);
-        }
-        return propValue;
-      }
-
-      // Primitive/array key: use the cached value directly (no copy).
-      const value = readValue(mem, key, t);
-      if (Array.isArray(value)) {
-        return getTopLevelArrayMember(mem, key, value, prop, arrayCapacity);
-      }
-      // Object value: property access.
-      const propValue = (value as Record<string | symbol, unknown>)[prop];
-      if (Array.isArray(propValue)) {
-        return createArrayProxy(mem, key, prop as string, arrayCapacity);
-      }
-      return propValue;
+      return readProp(mem, key, prop, arrayCapacity);
     },
     set(t, prop, val) {
-      // In-place update: write only the affected slot instead of decoding and
-      // re-encoding the whole value.
       t.__cache = undefined;
-      return mem.withLock(() => {
-        // Object property: use the cached layout to write only that slot.
-        const layout = getObjectLayout(mem, key);
-        if (layout !== null) {
-          const slotOffset = layout.properties.get(prop as string);
-          if (slotOffset === undefined) {
-            throw new TypeError(
-              `Value for key "${key}" has a fixed shape: properties may not be added or removed`,
-            );
-          }
-          mem.updateValueSlot(slotOffset, encodeValue(mem, val));
-          bump(mem, key);
-          return true;
-        }
-
-        // Top-level array index write: update only that array slot.
-        const offset = getOffset(mem, key);
-        if (offset === null) {
-          throw new Error(`No shared value found for key "${key}"`);
-        }
-        const slot = mem.readValueSlot(offset);
-        if (
-          slot.type === TYPE_ARRAY_REF &&
-          typeof prop === "string" &&
-          /^\d+$/.test(prop)
-        ) {
-          const index = Number(prop);
-          const ref = { offset: slot.a, count: slot.b, capacity: slot.c };
-          if (index >= ref.count) {
-            throw new RangeError(
-              `Index ${index} out of bounds for array of length ${ref.count}`,
-            );
-          }
-          mem.updateArraySlot(ref, index, encodeValue(mem, val));
-          bump(mem, key);
-          return true;
-        }
-
-        // Top-level array length write: shrink/grow the array in place without
-        // re-encoding the whole array (which would leave a dead slot behind).
-        if (slot.type === TYPE_ARRAY_REF && prop === "length") {
-          const newLen = Number(val);
-          if (!Number.isInteger(newLen) || newLen < 0) {
-            throw new RangeError("Invalid array length");
-          }
-          const ref = { offset: slot.a, count: slot.b, capacity: slot.c };
-          if (newLen <= ref.capacity) {
-            // Shrinking (or growing within capacity): just update the count.
-            mem.updateValueSlot(
-              offset,
-              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 (e.g. setting a primitive key's
-        // property, or a non-index property on an array).
-        return mutateValue<T, boolean>(
-          mem,
-          key,
-          (value) => {
-            if (Array.isArray(value)) {
-              (value as unknown as Record<string | symbol, unknown>)[prop] =
-                val;
-            } else {
-              (value as Record<string | symbol, unknown>)[prop] = val;
-            }
-            return true;
-          },
-          arrayCapacity,
-        );
-      });
+      writeProp(mem, key, prop, val, arrayCapacity);
+      return true;
     },
     deleteProperty() {
       throw new TypeError(
@@ -551,6 +592,22 @@ 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.
  *
@@ -565,15 +622,12 @@ function readValue(
     __cache?: { version: number; value: unknown; index: number };
   },
 ): unknown {
+  const fast = readCachedValue(mem, key);
+  if (fast.hit) return fast.value;
+
   const cached = readCache.get(key);
   const index = cached !== undefined ? cached.index : getIndex(mem, key);
-
-  // Lock-free fast path: if the cached version matches the current version
-  // cell, the cached value is still valid.
   const version = mem.getVersion(index);
-  if (cached !== undefined && cached.version === version) {
-    return cached.value;
-  }
 
   // Cache miss: decode under the lock and cache with the observed version.
   const value = mem.withLock(() => {
@@ -581,7 +635,7 @@ function readValue(
     if (offset === null) {
       throw new Error(`No shared value found for key "${key}"`);
     }
-    const type = mem.dataTable.getView().getInt32(offset, true);
+    const type = mem.dataTable.getInt32(offset);
     if (type === 5) {
       // Object block.
       const properties = mem.readObject(offset);
@@ -611,7 +665,7 @@ function writeValue(
   mem.withLock(() => {
     const existing = getOffset(mem, key);
     if (existing !== null) {
-      const type = mem.dataTable.getView().getInt32(existing, true);
+      const type = mem.dataTable.getInt32(existing);
       if (type === 5) {
         // Update existing object's property slots in place.
         const properties = mem.readObject(existing);

package/src/worker.ts

@@ -144,6 +144,7 @@ function stopCoordinator(): void {
   }
 }
 
+// ---------------------------------------------------------------------------
 /** The main-thread worker listener, so it can be removed by `stopInit()`. */
 let mainListener:
   | ((worker: {
@@ -166,12 +167,17 @@ function initMain(): void {
   }) => {
     worker.addEventListener("message", (e) => {
       const msg = e.data as { __sharedMemoryRequest?: boolean } | undefined;
-      if (msg && msg.__sharedMemoryRequest) {
+      if (
+        msg !== null &&
+        typeof msg === "object" &&
+        "__sharedMemoryRequest" in msg
+      ) {
         const mem = getDefaultMemory();
         worker.postMessage({
           __sharedMemoryInit: true,
           buffers: mem.exportBuffers(),
         });
+        return;
       }
     });
   };
@@ -234,7 +240,12 @@ function installMessageWrapper(): void {
           buffers?: Parameters<typeof SharedMemory.fromBuffers>[0];
         }
       | undefined;
-    if (msg && msg.__sharedMemoryInit && msg.buffers) {
+    if (
+      msg !== null &&
+      typeof msg === "object" &&
+      "__sharedMemoryInit" in msg &&
+      msg.buffers
+    ) {
       const mem = SharedMemory.fromBuffers(msg.buffers);
       setDefaultMemory(mem);
       // Create the worker-side refcount tracker from the shared refcount