bun-shared-memory 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -5,9 +5,99 @@ 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.7] - 2026-11-02
+
+### Added
+
+- Keep the Index Table in a single growable `SharedArrayBuffer` (capped at
+  4 GiB) instead of the chunked logic, so it stays contiguous and cheap to
+  address. `SharedMemoryOptions.indexTableMaxByteLength` configures its cap
+  (default 4 GiB).
+- `maxTotalBytes` now caps the combined physical size of DataTable,
+  StringTable, and ArrayTable only (the Index Table is excluded). The budget
+  is enforced by an atomic `SharedBudget` counter shared across workers that
+  reserves memory before each chunk growth, so the three tables cannot exceed
+  the limit even when multiple workers write concurrently.
+- Enforce size limits regardless of the configured values: `chunkSize` is at
+  least 4 MiB, `maxTotalBytes`/`maxByteLength` are at least 32 MiB, and
+  `chunkSize` is raised as needed so no table needs more than 1024 chunks.
+  `SharedMemory.maxByteLength` and `SharedMemory.maxTotalBytes` are now public
+  read-only fields.
+
+### Performance
+
+- Reclaim memory from inactive chunks after defragmentation. A
+  `SharedArrayBuffer` cannot be shrunk, so `GrowableBuffer` replaces each
+  inactive chunk with a fresh 4-byte `SharedArrayBuffer`, releasing the old
+  full-size buffer so its memory is freed. `defragment()` returns the new
+  chunk lists and the main thread broadcasts them to workers via a
+  `__chunkUpdate` message; workers apply them with `applyChunkUpdate()`. This
+  only runs during defragmentation (rare), so the hot path is unaffected.
+- Optimize the budget write hot path: `GrowableBuffer` tracks
+  `nextChunkToActivate` (the first not-yet-active chunk) so `ensureCapacity`
+  only activates new chunks instead of re-scanning every already-active chunk
+  on each write (was O(n) per write as the dataset grew). Writes ~9% faster.
+
+### Changed
+
+- Stabilize the real-world benchmark against CPU contention. The shared-memory
+  methodology finishes in tens of milliseconds, so it is sensitive to load
+  from other processes (IDE, language servers). Each worker now runs several
+  measured samples (default 5) and reports its fastest; each methodology is
+  run several times (default 3) and the fastest run is kept. Because
+  contention can only slow a run down, the minimum is the best estimate of
+  true throughput.
+
+### Fixed
+
+- Resolve chunk offsets with an unsigned right shift (`offset >>> chunkShift`)
+  instead of a signed one. A signed 32-bit shift turns offsets at or above
+  2 GiB negative, so reads/writes past 2 GiB (e.g. in a >4 GiB chunked buffer)
+  hit the wrong chunk or threw. The Index Table and the Data/String/Array
+  tables can now be addressed at any offset below the 4 GiB single-SAB cap.
+  Reported by [mizulu](https://github.com/mizulu).
+
+## [0.1.6] - 2026-11-02
+
+### Added
+
+- Support shared memory larger than 4 GiB. The single-`SharedArrayBuffer`
+  per-buffer architecture is replaced with a chunked `GrowableBuffer`: each
+  buffer is backed by multiple equal-size chunks (32 MiB default, power of
+  two), so a buffer can exceed the 4 GiB single-SAB limit. Offsets resolve
+  O(1) via bit shifts (`offset >> chunkShift`).
+- `SharedMemoryOptions.chunkSize` to configure the chunk size (the minimum
+  growth step).
+- Chunks are pre-allocated at construction (4 bytes each, with
+  `maxByteLength = chunkSize`) and activated on first access via
+  `SharedArrayBuffer.grow()`. Because `grow()` is visible across all workers
+  sharing a buffer, a worker can grow a chunk and every other worker sees it
+  immediately — no postMessage broadcast is needed for chunk activation.
+
+### Changed
+
+- `exportBuffers()`/`fromBuffers()` now pass chunk lists instead of a single
+  buffer; `fromBuffers` reuses the shared `SharedArrayBuffer`s directly (no
+  copy) so writes stay visible across workers. The chunk size is derived from
+  each buffer's `maxByteLength` (preserved across `postMessage`), not its
+  current 4-byte length.
+- Remove the 4 GiB cap on the per-buffer maximum in the `SharedMemory`
+  constructor (the chunked `GrowableBuffer` already bypasses the single-SAB
+  limit).
+
+### Performance
+
+- After defragmentation, unused chunks are marked inactive:
+  `GrowableBuffer.reset()` deactivates chunks beyond the compacted region so
+  the GC can reclaim their storage.
+- The chunked accessor adds an indirect `chunks[index].view` lookup on the
+  write hot path (the price of >4 GiB support): writes ~-15%, array writes
+  ~-20%. Reads are unchanged (lock-free cache path).
+
 ## [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
@@ -24,6 +114,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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
@@ -33,6 +124,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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).
@@ -41,6 +133,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
@@ -49,16 +142,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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()`.
@@ -67,6 +163,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.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`).
@@ -75,6 +172,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - O(1) in-place `push`/`pop` with capacity-based array growth.
 - Benchmarks for all data types vs native.
 
+[0.1.7]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/Kapsonfire/bun-shared-memory/compare/v0.1.4...v0.1.5
 [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

package/README.md

@@ -37,20 +37,21 @@ 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):
+speed; MySQL/Redis benchmarked over both TCP and Unix socket; each methodology
+is the minimum over 3 runs × 5 samples to filter CPU-contention noise):
 
 | 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
+| `shared`    | —         | 100,000  | 21           | 4,876,492  | —          |
+| `sqlite`    | —         | 100,000  | 188          | 531,116    | 9.2× slower |
+| `redis`     | socket    | 100,000  | 1,262        | 79,229     | 61.5× slower |
+| `mysql`     | socket    | 100,000  | 1,605        | 62,322     | 78.2× slower |
+| `redis`     | tcp       | 100,000  | 2,817        | 35,497     | 137.4× slower |
+| `mysql`     | tcp       | 100,000  | 2,976        | 33,602     | 145.1× slower |
+
+Shared memory is the fastest by a wide margin: ~9.2× faster than a live SQLite
+read and ~61–145× faster than live MySQL/Redis reads. Unix sockets are
+significantly faster than TCP for MySQL/Redis (~1.8×), but both remain far
 slower than shared memory.
 
 ## ✨ Features
@@ -305,22 +306,24 @@ 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.
+The Index Table (including each key's version counter) uses one growable
+`SharedArrayBuffer`, capped at **4 GiB** by default (configurable via
+`indexTableMaxByteLength`). The DataTable, StringTable, and ArrayTable use
+chunks and can individually exceed 4 GiB. By default each table grows up to
+its own `maxByteLength`, so the _total_ memory can be several times that.
 
 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`:
+table's starting size, avoiding a grow on first use) and `maxByteLength`
+(each table's cap). To cap the combined physical memory of DataTable,
+StringTable, and ArrayTable, pass `maxTotalBytes`. The Index Table is excluded
+from this budget. Its growth and chunk growth in workers reserve memory from
+the same atomic budget before allocating, so the three tables cannot exceed it.
 
 ```ts
 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).
+// The Index Table grows up to 4 GiB independently. DataTable, StringTable, and
+// ArrayTable together are capped at 4 GiB.
 await init({
   initialSize: 64 * 1024,
   maxByteLength: 4 * 1024 * 1024 * 1024,
@@ -328,14 +331,24 @@ await init({
 });
 ```
 
-`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`.
+`maxTotalBytes` caps the **sum** of the physical sizes of DataTable,
+StringTable, and ArrayTable, including across workers. If a write would exceed
+the budget, a `RangeError` is thrown before the chunk grows. Without
+`maxTotalBytes`, each table 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.
+### Size limits
+
+The following limits are enforced regardless of the configured values:
+
+- **`chunkSize` is at least 4 MiB.** A smaller value is raised to 4 MiB.
+- **`maxTotalBytes` / `maxByteLength` are at least 32 MiB.** A smaller value
+  is raised to 32 MiB.
+- **No table uses more than 1024 chunks.** `chunkSize` is raised as needed so
+  that `ceil(maxByteLength / chunkSize) ≤ 1024` (e.g. an 8 GiB table with a
+  4 MiB chunk would need 2048 chunks, so the chunk size is raised to 8 MiB).
+
+These keep the chunk count bounded (so the pre-allocated chunk list stays
+small) and avoid pathological tiny chunks.
 
 ## Array capacity
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-shared-memory",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
   "type": "module",
   "sideEffects": false,