bun-shared-memory 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# 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.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.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,8 +1,9 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
   "type": "module",
+  "sideEffects": false,
   "module": "index.ts",
   "types": "index.ts",
   "exports": {
@@ -13,7 +14,8 @@
   },
   "files": [
     "index.ts",
-    "src/"
+    "src/",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "typecheck": "bun check",
@@ -45,11 +47,6 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "elysia": "^1.4.30",
-    "ioredis": "^6.0.0",
-    "mysql2": "^3.24.6"
-  },
-  "peerDependencies": {
-    "typescript": "^7"
+    "elysia": "^1.4.30"
   }
 }

package/src/shared.ts

@@ -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,6 +462,102 @@ 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.buffer;
+      },
+    });
+    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;
@@ -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(() => {