bun-shared-memory 0.1.1 → 0.1.3

package/README.md

@@ -1,4 +1,25 @@
-# bun-shared-memory
+<div align="center">
+
+# 🧠 bun-shared-memory
+
+**Share data between Bun workers/threads using `SharedArrayBuffer`** — zero-copy, 4-buffer architecture, Atomics-based synchronization.
+
+[![npm version](https://img.shields.io/npm/v/bun-shared-memory?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/bun-shared-memory)
+[![npm downloads](https://img.shields.io/npm/dm/bun-shared-memory?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/bun-shared-memory)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/bun-shared-memory?style=for-the-badge&color=blueviolet)](https://bundlephobia.com/package/bun-shared-memory)
+
+[![GitHub stars](https://img.shields.io/github/stars/Kapsonfire/bun-shared-memory?style=for-the-badge&logo=github&color=181717)](https://github.com/Kapsonfire/bun-shared-memory)
+[![GitHub forks](https://img.shields.io/github/forks/Kapsonfire/bun-shared-memory?style=for-the-badge&logo=github&color=181717)](https://github.com/Kapsonfire/bun-shared-memory)
+[![GitHub issues](https://img.shields.io/github/issues/Kapsonfire/bun-shared-memory?style=for-the-badge&logo=github&color=181717)](https://github.com/Kapsonfire/bun-shared-memory/issues)
+[![GitHub license](https://img.shields.io/github/license/Kapsonfire/bun-shared-memory?style=for-the-badge&color=green)](https://github.com/Kapsonfire/bun-shared-memory/blob/main/LICENSE)
+
+[![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.4.0-black?style=for-the-badge&logo=bun&color=14151a)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-7-blue?style=for-the-badge&logo=typescript&color=3178c6)](https://www.typescriptlang.org)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen?style=for-the-badge&logo=checkmarx)](https://github.com/Kapsonfire/bun-shared-memory/actions)
+
+</div>
+
+---
 
 A TypeScript library for the **Bun** runtime that enables sharing data between workers/threads using `SharedArrayBuffer`.
 
@@ -7,7 +28,42 @@ A TypeScript library for the **Bun** runtime that enables sharing data between w
 > onward. Core shared-memory operations (including `SharedArrayBuffer.grow()`)
 > work on earlier versions, but the automatic worker buffer-sharing does not.
 
-## Install
+## 📈 Real-world benchmark
+
+`bun run bench:real` compares four methodologies for serving a "get user"
+request through an [Elysia](https://elysiajs.com) mini API. Requests are built
+by hand and passed directly to `app.fetch()` (no HTTP server); each methodology
+is benchmarked sequentially with 4 workers. See
+[`bench/real-world/README.md`](bench/real-world/README.md) for setup.
+
+Measured on Linux (Bun 1.4.4, 100,000 requests per methodology, sorted by
+speed; MySQL/Redis benchmarked over both TCP and Unix socket):
+
+| Methodology | Transport | Requests | Elapsed (ms) | req/s      | vs. shared |
+|-------------|-----------|----------|--------------|------------|------------|
+| `shared`    | —         | 100,000  | 52           | 1,925,042  | —          |
+| `sqlite`    | —         | 100,000  | 187          | 535,469    | 3.6× slower |
+| `redis`     | socket    | 100,000  | 1,688        | 59,233     | 32.5× slower |
+| `mysql`     | socket    | 100,000  | 1,823        | 54,861     | 35.1× slower |
+| `redis`     | tcp       | 100,000  | 2,863        | 34,923     | 55.1× slower |
+| `mysql`     | tcp       | 100,000  | 3,281        | 30,476     | 63.2× slower |
+
+Shared memory is the fastest by a wide margin: ~3.6× faster than a live SQLite
+read and ~33–63× faster than live MySQL/Redis reads. Unix sockets are
+significantly faster than TCP for MySQL/Redis (~1.7×), but both remain far
+slower than shared memory.
+
+## ✨ Features
+
+- 🚀 **Zero-copy** shared memory between workers/threads via `SharedArrayBuffer`
+- 🧩 **4-buffer architecture** — Index Table, DataTable, append-only StringTable, ArrayTable
+- 🔒 **Atomics-based synchronization** — re-entrant `Mutex` + `Notifier`
+- ⚡ **Read & offset caches** — lock-free fast path, cross-worker invalidation via version cells
+- 🧹 **Reference counting & defragmentation** — automatic memory reclamation
+- 🪄 **Proxy-based API** — `Shared()` with direct getter/setter access
+- 🧵 **Automatic worker integration** — no manual buffer serialization
+
+## 📦 Install
 
 ```sh
 bun add bun-shared-memory
@@ -15,15 +71,18 @@ bun add bun-shared-memory
 
 See [SPEC.md](./SPEC.md) for the full specification.
 
-## Status
+## 📊 Stats
 
-✅ **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.
+| | |
+|---|---|
+| **Version** | [![npm version](https://img.shields.io/npm/v/bun-shared-memory?color=cb3837)](https://www.npmjs.com/package/bun-shared-memory) |
+| **Downloads / month** | [![npm downloads](https://img.shields.io/npm/dm/bun-shared-memory?color=cb3837)](https://www.npmjs.com/package/bun-shared-memory) |
+| **Stars** | [![GitHub stars](https://img.shields.io/github/stars/Kapsonfire/bun-shared-memory?color=181717)](https://github.com/Kapsonfire/bun-shared-memory) |
+| **Forks** | [![GitHub forks](https://img.shields.io/github/forks/Kapsonfire/bun-shared-memory?color=181717)](https://github.com/Kapsonfire/bun-shared-memory) |
+| **Open issues** | [![GitHub issues](https://img.shields.io/github/issues/Kapsonfire/bun-shared-memory?color=181717)](https://github.com/Kapsonfire/bun-shared-memory/issues) |
+| **Open PRs** | [![GitHub pull requests](https://img.shields.io/github/issues-pr/Kapsonfire/bun-shared-memory?color=181717)](https://github.com/Kapsonfire/bun-shared-memory/pulls) |
+| **License** | [![License](https://img.shields.io/github/license/Kapsonfire/bun-shared-memory?color=green)](https://github.com/Kapsonfire/bun-shared-memory/blob/main/LICENSE) |
+| **Language** | [![TypeScript](https://img.shields.io/badge/TypeScript-7-blue?color=3178c6)](https://www.typescriptlang.org) |
 
 ## Data Types
 
@@ -34,8 +93,15 @@ See [SPEC.md](./SPEC.md) for the full specification.
 
 ## Usage
 
+Always call `init()` first — on both the main thread and in every worker. It
+sets up the shared-memory handshake and (optionally) configures the buffers.
+
 ```ts
-import { Shared } from "bun-shared-memory";
+import { Shared, init } from "bun-shared-memory";
+
+// Main thread: call init() once at startup. It creates the shared memory
+// (with the given buffer sizes) and answers buffer requests from workers.
+await init({ initialSize: 64 * 1024, maxByteLength: 4 * 1024 * 1024 * 1024 });
 
 // Get a wrapper to a named value in shared memory.
 // If it doesn't exist, create it with the provided initial value.
@@ -67,6 +133,10 @@ const user2 = await Shared<User>("user-2", async () => {
 });
 ```
 
+In a worker, `await init()` requests the shared buffers from the main thread
+and reconstructs the same memory, so `Shared()` reads/writes the same data as
+the main thread. See [Worker integration](#worker-integration) below.
+
 ## Synchronization
 
 All shared-memory reads and writes are protected by an `Atomics`-based mutex, so concurrent access from multiple workers is safe.
@@ -147,7 +217,7 @@ defragmented — no manual setup needed.
 import { Shared, init } from "bun-shared-memory";
 
 // Main thread: init() starts the coordinator automatically.
-init();
+await init();
 const user = Shared("user-1", { name: "Alice" });
 const copy = user.read(); // acquires a ref; released when `copy` is GC'd
 ```
@@ -192,8 +262,11 @@ workers, and each worker requests the shared buffers from the main thread.
 // main.ts
 import { Shared, init } from "bun-shared-memory";
 
+// Always call init() first. It creates the shared memory (with the given
+// buffer sizes) and answers buffer requests from every new worker.
+await init({ initialSize: 64 * 1024, maxByteLength: 4 * 1024 * 1024 * 1024 });
+
 const user = Shared("user-1", { name: "Alice", age: 30 });
-init(); // answer buffer requests from every new worker
 ```
 
 ```ts
@@ -223,6 +296,11 @@ buffer-request listener and starts the refcount coordinator (auto-maintenance
 > `Shared()` in a worker without `init()` throws an error rather than silently
 > creating a separate, unshared memory.
 
+The coordinator's maintenance timer is unref'd, so it does not keep the
+process alive — the process exits naturally once no other work is pending
+(e.g. after the last worker closes). You don't need to call `stopInit()` or
+`process.exit()` to terminate.
+
 A complete runnable example is in [`examples/worker/`](examples/worker/).
 
 ## Memory budget
@@ -233,21 +311,28 @@ 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()`):
+Configure the buffers when calling `init()` — pass `initialSize` (each
+buffer's starting size, avoiding a grow on first use) and `maxByteLength`
+(each buffer's cap). To cap the **total** memory across all buffers, pass
+`maxTotalBytes`:
 
 ```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 });
+import { init } from "bun-shared-memory";
+
+// Each buffer starts at 64 KiB and grows up to 4 GiB; the sum of all buffers'
+// physical sizes is additionally capped at 4 GiB (maxTotalBytes).
+await init({
+  initialSize: 64 * 1024,
+  maxByteLength: 4 * 1024 * 1024 * 1024,
+  maxTotalBytes: 4 * 1024 * 1024 * 1024,
+});
 ```
 
+`maxTotalBytes` caps the **sum** of all buffers' physical sizes, so the total
+stays within the budget. If a write would exceed the budget, a `RangeError` is
+thrown. Without `maxTotalBytes`, each buffer simply grows up to its own
+`maxByteLength`.
+
 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.
@@ -309,3 +394,21 @@ 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.
+
+### Real-world benchmark
+
+See [📈 Real-world benchmark](#-real-world-benchmark) at the top of this
+README for the measured results.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please open an issue or pull request.
+
+- 🐛 [Report a bug](https://github.com/Kapsonfire/bun-shared-memory/issues/new?labels=bug)
+- 💡 [Request a feature](https://github.com/Kapsonfire/bun-shared-memory/issues/new?labels=enhancement)
+- 📖 [Browse open issues](https://github.com/Kapsonfire/bun-shared-memory/issues)
+- 🔀 [Open a pull request](https://github.com/Kapsonfire/bun-shared-memory/pulls)
+
+## 📄 License
+
+[MIT](./LICENSE) © [Kapsonfire](https://github.com/Kapsonfire)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
   "type": "module",
   "module": "index.ts",
@@ -18,7 +18,10 @@
   "scripts": {
     "typecheck": "bun check",
     "test": "bun test",
-    "bench": "bun bench/bench.ts"
+    "bench": "bun bench/bench.ts",
+    "bench:real": "bun bench/real-world/run.ts",
+    "bench:real:seed": "bun bench/real-world/seed.ts",
+    "bench:real:mysql": "docker compose -f bench/real-world/docker-compose.yml up -d"
   },
   "keywords": [
     "bun",
@@ -41,7 +44,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "elysia": "^1.4.30",
+    "ioredis": "^6.0.0",
+    "mysql2": "^3.24.6"
   },
   "peerDependencies": {
     "typescript": "^7"

package/src/refcount.ts

@@ -316,6 +316,10 @@ export class RefCountCoordinator {
         this.mem.withLock(() => this.mem.defragment());
       }
     }, intervalMs);
+    // Unref the timer so it does not keep the process alive. The coordinator
+    // keeps draining events and defragmenting while the process runs, but the
+    // process can still exit naturally when no other work is pending.
+    (this.maintenanceTimer as unknown as { unref?: () => void }).unref?.();
     return () => this.stopAutoMaintenance();
   }