bun-shared-memory 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dennis Dudek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,311 @@
-# Temporary Holding Version
+# bun-shared-memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript library for the **Bun** runtime that enables sharing data between workers/threads using `SharedArrayBuffer`.
+
+> **Requires Bun ≥ 1.4.0.** The worker integration (M4) relies on the
+> `process.on("worker")` handshake, which only works reliably from Bun 1.4.0
+> onward. Core shared-memory operations (including `SharedArrayBuffer.grow()`)
+> work on earlier versions, but the automatic worker buffer-sharing does not.
+
+## Install
+
+```sh
+bun add bun-shared-memory
+```
+
+See [SPEC.md](./SPEC.md) for the full specification.
+
+## Status
+
+✅ **M3 — Synchronization**: `Atomics`-based locking (`Mutex`) and notifications (`Notifier`) between workers, integrated into all shared-memory operations.
+
+✅ **Read cache**: reads are cached per worker and invalidated cross-worker via a per-key version counter.
+
+✅ **Reference counting & defragmentation**: workers acquire/release references to shared objects/arrays (released on GC), the main thread tracks which worker holds what, and a defragmentation pass reclaims dead space when free space is low.
+
+✅ **M4 — Worker integration**: a worker can simply call `Shared()` and automatically share the same buffers as the main thread. Both sides call `init()` — the main thread answers buffer requests, each worker requests the shared buffers — no manual buffer serialization needed.
+
+## Data Types
+
+- **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`.
+
+## Usage
+
+```ts
+import { Shared } from "bun-shared-memory";
+
+// Get a wrapper to a named value in shared memory.
+// If it doesn't exist, create it with the provided initial value.
+const user = Shared<User>("user-1", { name: "Alice", age: 30, tags: ["a"] });
+
+// Access object properties directly via getters/setters
+user.name; // "Alice"
+user.name = "Bob"; // writes to shared memory
+user.age = 31;
+
+// Arrays are proxied too: index access and mutating methods work
+user.tags.push("b");
+user.tags[0] = "x";
+user.tags.pop();
+
+// Top-level arrays work the same way
+const arr = Shared<number[]>("arr-1", [1, 2, 3]);
+arr.push(4);
+arr[0] = 99;
+
+// Primitives use read()/write()/update()
+const counter = Shared<number>("counter-1", 0);
+counter.write(42);
+counter.update((n) => n + 1);
+
+// Or create it with a loader function (sync or async)
+const user2 = await Shared<User>("user-2", async () => {
+  return await fetchUser();
+});
+```
+
+## Synchronization
+
+All shared-memory reads and writes are protected by an `Atomics`-based mutex, so concurrent access from multiple workers is safe.
+
+### Read cache
+
+Reads are cached per worker to avoid re-decoding the value on every access.
+Each key has a version cell (an `Int32`) in shared memory that is incremented
+on every write. A read does a single lock-free `Atomics.load` on the version
+cell; if it matches the cached version, the cached value is returned without
+taking the lock or decoding. Because the version cell is shared, a write in
+any worker invalidates the cache in every other worker automatically.
+
+`read()` returns a copy, so mutating the returned object cannot corrupt the
+cache. Property access through the proxy (e.g. `user.name`) reads from the
+cache directly.
+
+### Offset cache
+
+Because object properties may not be added or removed, an object's layout
+(total DataTable offset + each property's slot offset) is static for the
+lifetime of the object. The layout is built once (under the lock) and cached
+per worker, so a property read decodes only the requested slot instead of the
+whole object. The decoded property value is cached per property and
+invalidated by the same per-key version cell, so repeated reads of the same
+property are cheap. If a future GC/defragmentation moves an object block, the
+layout cache must be invalidated (e.g. via a layout version cell).
+
+### Mutex
+
+A re-entrant cross-worker mutex. Share the same buffer across workers.
+
+```ts
+import { Mutex } from "bun-shared-memory";
+
+const mutex = new Mutex();
+// pass mutex.buffer to other workers, then:
+mutex.lock();
+try {
+  // critical section
+} finally {
+  mutex.unlock();
+}
+// or
+mutex.withLock(() => {
+  // critical section
+});
+```
+
+### Notifier
+
+A cross-worker notification primitive built on `Atomics.wait`/`Atomics.notify`.
+
+```ts
+import { Notifier } from "bun-shared-memory";
+
+const notifier = new Notifier();
+// pass notifier.buffer to other workers, then:
+notifier.wait(); // block until notified
+notifier.notify(1); // wake one waiting worker
+```
+
+## Reference counting & memory reclamation
+
+The shared buffers are append-only, so dead space (overwritten strings,
+abandoned array blocks, replaced objects) is never reclaimed on its own. A
+reference-counting system tracks which workers hold references to which
+objects/arrays, and a **defragmentation** pass reclaims memory when free space
+runs low.
+
+When you use the worker integration (`init()`), this is wired up automatically:
+`init()` starts a `RefCountCoordinator` on the main thread (auto-maintenance +
+auto-registration of workers) and a `RefCountTracker` in each worker, so
+`read()` acquires references that are released on GC and dead space is
+defragmented — no manual setup needed.
+
+```ts
+import { Shared, init } from "bun-shared-memory";
+
+// Main thread: init() starts the coordinator automatically.
+init();
+const user = Shared("user-1", { name: "Alice" });
+const copy = user.read(); // acquires a ref; released when `copy` is GC'd
+```
+
+You can also wire it up manually (e.g. when not using `init()`):
+
+```ts
+import {
+  SharedMemory,
+  RefCountCoordinator,
+  RefCountTracker,
+  RefCountBuffer,
+} from "bun-shared-memory";
+
+// Main thread: coordinate refcounts and auto-register workers.
+const mem = new SharedMemory();
+const coord = new RefCountCoordinator(mem); // auto-maintenance starts automatically
+coord.autoRegister(); // track workers via process.on("worker")
+// The coordinator periodically drains acquire/release events and defragments
+// when free space runs low — no manual calls needed.
+
+// Worker: track references acquired by read().
+const tracker = new RefCountTracker(new RefCountBuffer(refBuf), workerId);
+const user = Shared(
+  "user-1",
+  { name: "Alice" },
+  { memory: mem, refCount: tracker },
+);
+const copy = user.read(); // acquires a ref; released when `copy` is GC'd
+```
+
+See [REFCOUNT.md](./REFCOUNT.md) for the full design.
+
+## Worker integration
+
+A worker can simply call `Shared()` and automatically share the same buffers
+as the main thread — no manual buffer serialization needed. Both sides call
+`init()` to set up the handshake: the main thread answers buffer requests from
+workers, and each worker requests the shared buffers from the main thread.
+
+```ts
+// main.ts
+import { Shared, init } from "bun-shared-memory";
+
+const user = Shared("user-1", { name: "Alice", age: 30 });
+init(); // answer buffer requests from every new worker
+```
+
+```ts
+// worker.ts
+import { Shared, init, onMessage } from "bun-shared-memory";
+
+await init(); // request the shared buffers from the main thread
+
+// Register your own message handler via onMessage(); messages are buffered
+// until the buffers have arrived.
+onMessage((e) => {
+  const user = Shared("user-1", { name: "x" }); // reads the main thread's value
+  self.postMessage(user.read());
+});
+```
+
+`init()` is safe to call on both sides: in the main thread it registers the
+buffer-request listener and starts the refcount coordinator (auto-maintenance
+
+- worker auto-registration), and in a worker it performs the request/response
+  handshake, reconstructs the shared buffers, and creates a refcount tracker —
+  so reference counting works automatically. `Shared()` never overwrites a value
+  that already exists in shared memory, so a worker reading a key created by the
+  main thread gets the existing value rather than its own initial value.
+
+> **Note:** a worker must call `await init()` before using `Shared()`. Calling
+> `Shared()` in a worker without `init()` throws an error rather than silently
+> creating a separate, unshared memory.
+
+A complete runnable example is in [`examples/worker/`](examples/worker/).
+
+## Memory budget
+
+Shared memory is split across several growable `SharedArrayBuffer`s (the
+index, data, string, and array tables; each key's version counter lives in its
+index entry). A single `SharedArrayBuffer` can be at most **4 GiB**. By default
+each buffer grows independently up to its own `maxByteLength`, so the _total_
+memory can be several times that.
+
+To cap the **total** memory across all buffers, pass `maxTotalBytes` when
+creating the memory (or to `init()`):
+
+```ts
+import { SharedMemory, init } from "bun-shared-memory";
+
+// Total budget of 4 GiB shared across all buffers. Each buffer's own
+// maxByteLength is min(4 GiB, maxTotalBytes), and the sum of all buffers'
+// physical sizes is additionally capped at maxTotalBytes.
+const mem = new SharedMemory({ maxTotalBytes: 4 * 1024 * 1024 * 1024 });
+
+// Or set it when initializing the shared-memory handshake:
+await init({ maxTotalBytes: 4 * 1024 * 1024 * 1024 });
+```
+
+The budget is shared dynamically — buffers grow as needed, but only while the
+sum of all buffers stays within `maxTotalBytes`. If a write would exceed the
+budget, a `RangeError` is thrown.
+
+## Array capacity
+
+By default an array is stored with exactly as many slots as it has elements,
+so the first `push` must relocate the array (with doubled capacity) to make
+room. To avoid that, reserve extra capacity up front with `arrayCapacity`:
+
+```ts
+import { Shared } from "bun-shared-memory";
+
+// Reserve 100 slots so the first ~90 pushes append in place without moving.
+const arr = Shared<number[]>("arr-cap", [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], {
+  arrayCapacity: 100,
+});
+```
+
+`arrayCapacity` is the initial capacity (in elements) reserved for arrays when
+they are first stored. `push` appends in place until the capacity is
+exhausted, then the array is relocated with doubled capacity. It defaults to
+the array's length.
+
+## Development
+
+```bash
+bun install        # install dependencies
+bun run typecheck  # type check (bun check)
+bun test           # run tests
+bun fmt            # format code
+bun run bench      # run benchmarks
+```
+
+## Benchmarks
+
+`bun run bench` compares shared-memory access against native JS access for
+every supported data type and its arrays:
+
+- **Primitives**: `number`, `string`, `boolean`, `bigint` (read + write)
+- **Arrays**: `number[]`, `string[]`, `boolean[]`, `bigint[]`, `mixed[]` (index read, index write)
+- **Objects**: property read/write and array-property access
+
+Each benchmark reports ops/sec for the native and shared paths, plus the
+relative slowdown. Results are in `bench/`.
+
+With the read cache and offset cache, **reads** are typically 5–12× slower than
+native (the remaining cost is the proxy dispatch). **Writes** are slower because
+they must serialize, write, and bump the version cell. Object property and array
+index writes are O(1) in-place updates (only the affected slot is written).
+Array `push`/`pop` are O(1) amortized in-place operations: arrays reserve
+capacity padding in the ArrayTable, `push` writes into the padding until it is
+exhausted (then the array is relocated with doubled capacity), and `pop` just
+decrements the length.
+
+**String interning**: repeated writes of the same string reuse a cached
+StringTable reference instead of re-encoding and re-copying the bytes. The
+per-worker LRU cache grows dynamically (configurable via `internCapacity` /
+`internMax` on `SharedMemory`) and evicts least-recently-used entries once it
+reaches capacity. Because the StringTable is append-only, cached references stay
+valid for the lifetime of the buffer.

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.ts";

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
+  "type": "module",
+  "module": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "default": "./index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src/"
+  ],
+  "scripts": {
+    "typecheck": "bun check",
+    "test": "bun test",
+    "bench": "bun bench/bench.ts"
+  },
+  "keywords": [
+    "bun",
+    "shared-memory",
+    "sharedarraybuffer",
+    "worker",
+    "threads",
+    "atomics",
+    "zero-copy"
+  ],
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^7"
+  }
+}

package/src/growable-buffer.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared memory budget shared across multiple GrowableBuffers.
+ *
+ * Tracks the sum of the physical sizes of all participating buffers so a
+ * caller can cap the *total* memory used by a set of buffers, rather than
+ * capping each buffer independently. Growth is only allowed if the new total
+ * stays within the budget.
+ */
+export class SharedBudget {
+  private total = 0;
+
+  constructor(private readonly max: number) {}
+
+  /** Record a buffer's initial physical size. */
+  add(size: number): void {
+    this.total += size;
+    if (this.total > this.max) {
+      throw new RangeError(
+        `Shared memory budget exceeded: initial buffers total ${this.total} bytes but the budget is ${this.max}`,
+      );
+    }
+  }
+
+  /**
+   * Attempt to grow a buffer from `oldSize` to `newSize`. Returns true and
+   * updates the total if the new total stays within the budget, false
+   * otherwise (the caller must not grow).
+   */
+  tryGrow(oldSize: number, newSize: number): boolean {
+    const newTotal = this.total - oldSize + newSize;
+    if (newTotal > this.max) return false;
+    this.total = newTotal;
+    return true;
+  }
+}
+
+/**
+ * Growable SharedArrayBuffer helper.
+ *
+ * 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.
+ */
+export class GrowableBuffer {
+  readonly buffer: SharedArrayBuffer;
+  private view: DataView;
+  private readonly maxByteLength: number;
+  private readonly budget?: SharedBudget;
+  private used = 0;
+
+  constructor(
+    initialSizeOrBuffer: number | SharedArrayBuffer,
+    maxByteLength: number,
+    budget?: SharedBudget,
+  ) {
+    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);
+  }
+
+  /** Number of bytes written so far (used length, not buffer capacity). */
+  get byteLength(): number {
+    return this.used;
+  }
+
+  /** 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`,
+      );
+    }
+    this.buffer.grow(newSize);
+    this.view = new DataView(this.buffer);
+  }
+
+  /** Mark `n` bytes as used, after writing them at the current offset. */
+  advance(n: number): void {
+    this.used += n;
+  }
+
+  /**
+   * 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.
+   */
+  reset(n: number): void {
+    this.used = n;
+  }
+
+  getView(): DataView {
+    return this.view;
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export { Shared } from "./shared.ts";
+export type { SharedRef, SharedOptions } from "./shared.ts";
+export { SharedMemory } from "./memory.ts";
+export type { SharedMemoryOptions } from "./memory.ts";
+export { Mutex } from "./mutex.ts";
+export { Notifier } from "./notifier.ts";
+export {
+  RefCountBuffer,
+  RefCountCoordinator,
+  RefCountTracker,
+} from "./refcount.ts";
+export type { ObjectId, RefEvent } from "./refcount.ts";
+export {
+  getDefaultMemory,
+  setDefaultMemory,
+  hasDefaultMemory,
+  getDefaultTracker,
+  init,
+  stopInit,
+  onMessage,
+} from "./worker.ts";