@nxtedition/shared 4.0.0 → 4.0.1

package/README.md

@@ -61,6 +61,15 @@ w.cork(() => {
 // All writes flushed atomically when cork returns
 ```
 
+Or manually:
+
+```js
+w.cork()
+w.writeSync(buf1.length, writeFn, buf1)
+w.writeSync(buf2.length, writeFn, buf2)
+w.uncork() // publishes all writes to the reader
+```
+
 ### Non-blocking writes with tryWrite
 
 ```js
@@ -92,11 +101,10 @@ const w = new Writer(state)
 
 ```js
 // reader-worker.js
-import { State, Reader } from '@nxtedition/shared'
+import { Reader } from '@nxtedition/shared'
 import { workerData } from 'node:worker_threads'
 
-const state = new State(workerData)
-const r = new Reader(state)
+const r = new Reader(workerData)
 
 function poll() {
   const count = r.readSome((data) => {
@@ -116,108 +124,110 @@ Allocates or wraps a shared memory buffer for the ring buffer. The first 128 byt
 - **size** — Data capacity in bytes (must be a positive integer, max ~2 GB)
 - **buffer** — An existing `SharedArrayBuffer` to wrap
 
-### `new Reader(state: State)`
+#### `state.buffer`
 
-Creates a reader for the ring buffer.
+The underlying `SharedArrayBuffer`. Pass this to a worker thread to share the ring buffer.
 
-#### `reader.readSome(next)`
+### `new Reader(state: State | SharedArrayBuffer)`
 
-Reads a batch of messages. Calls `next(data)` for each message, where `data` has:
+Creates a reader for the ring buffer. Accepts a `State` instance or a `SharedArrayBuffer` directly (shorthand for `new Reader(new State(buf))`).
+
+#### `reader.readSome(next, opaque?)`
+
+Reads a batch of messages. Calls `next(data, opaque)` for each message, where `data` has:
 
 - `buffer: Buffer` — The underlying shared buffer
 - `view: DataView` — A DataView over the shared buffer
 - `byteOffset: number` — Start offset of the message payload
 - `byteLength: number` — Length of the message payload in bytes
 
+- **opaque** — Optional user-provided context object passed through to the callback. Useful for avoiding closures on hot paths.
+
 Return `false` from the callback to stop reading early. Returns the number of messages processed.
 
 Messages are batched: up to 1024 items or 256 KiB per call.
 
-### `new Writer(state: State, options?)`
+### `new Writer(state: State | SharedArrayBuffer, options?)`
 
-Creates a writer for the ring buffer.
+Creates a writer for the ring buffer. Accepts a `State` instance or a `SharedArrayBuffer` directly (shorthand for `new Writer(new State(buf))`).
 
 **Options:**
 
 - `yield?: () => void` — Called when the writer must wait for the reader to catch up. Useful to prevent deadlocks when the writer thread also drives the reader.
 - `logger?: { warn(obj, msg): void }` — Logger for yield warnings (pino-compatible).
 
-#### `writer.writeSync(len, fn)`
+#### `writer.writeSync(len, fn, opaque?)`
 
 Synchronously writes a message. Blocks (via `Atomics.wait`) until buffer space is available.
 
 - **len** — Maximum payload size in bytes. Writing beyond `len` bytes in the callback is undefined behavior.
-- **fn(data) → number** — Write callback. Write payload into `data.buffer` starting at `data.byteOffset`. **Must return the end position** (`data.byteOffset + bytesWritten`), not the byte count.
+- **fn(data, opaque) → number** — Write callback. Write payload into `data.buffer` starting at `data.byteOffset`. **Must return the end position** (`data.byteOffset + bytesWritten`), not the byte count.
+- **opaque** — Optional user-provided context object passed through to the callback. Useful for avoiding closures on hot paths.
 
 Throws on timeout (default: 60000 ms).
 
-#### `writer.tryWrite(len, fn)`
+#### `writer.tryWrite(len, fn, opaque?)`
+
+Non-blocking write attempt. Returns `false` if the buffer is full. The `fn` and `opaque` parameters follow the same contract as `writeSync`.
 
-Non-blocking write attempt. Returns `false` if the buffer is full. The `fn` callback follows the same contract as `writeSync`.
+#### `writer.cork(callback?)`
 
-#### `writer.cork(callback)`
+Batches multiple writes. The write pointer is only published to the reader when the cork is released, reducing atomic operation overhead.
 
-Batches multiple writes within the callback. The write pointer is only published to the reader when `cork` returns, reducing atomic operation overhead.
+When called with a callback, uncork is called automatically when the callback returns. When called without a callback, you must call `uncork()` manually.
+
+#### `writer.uncork()`
+
+Decrements the cork counter. When it reaches zero, publishes the pending write position to the reader. Safe to call when not corked (no-op).
+
+#### `writer.flushSync()`
+
+Immediately publishes the pending write position to the reader. Unlike `uncork`, this does not interact with the cork counter — it forces a flush regardless.
 
 ## Benchmarks
 
-Measured on Apple M3 Pro (3.51 GHz), Node.js 25.6.1, 8 MiB ring buffer.
+Measured on AMD EPYC 9355P (4.28 GHz), Node.js 25.6.0, 8 MiB ring buffer, Docker (x64-linux).
 
 Each benchmark writes batches of fixed-size messages from the main thread and
 reads them in a worker thread. The shared ring buffer is compared against
-Node.js `postMessage` (structured clone). Hardware performance counters were
-collected with [`@mitata/counters`](https://github.com/evanwashere/mitata).
+Node.js `postMessage` (structured clone).
 
 ### Throughput
 
 |   Size | shared (buffer) | shared (string) | postMessage (buffer) | postMessage (string) |
 | -----: | --------------: | --------------: | -------------------: | -------------------: |
-|   64 B |  **1.64 GiB/s** |       753 MiB/s |             96 MiB/s |            120 MiB/s |
-|  256 B |  **3.13 GiB/s** |      2.46 GiB/s |            360 MiB/s |            464 MiB/s |
-|  1 KiB |      4.81 GiB/s |  **7.56 GiB/s** |           1.31 GiB/s |           1.68 GiB/s |
-|  4 KiB |      5.04 GiB/s | **16.44 GiB/s** |           3.91 GiB/s |           5.13 GiB/s |
-| 16 KiB |      5.10 GiB/s | **22.24 GiB/s** |           9.07 GiB/s |           7.60 GiB/s |
-| 64 KiB |      5.33 GiB/s | **12.42 GiB/s** |           8.85 GiB/s |          13.20 GiB/s |
+|   64 B |   **901 MiB/s** |       410 MiB/s |             25 MiB/s |             42 MiB/s |
+|  256 B |  **2.67 GiB/s** |       896 MiB/s |             88 MiB/s |            158 MiB/s |
+|  1 KiB |  **4.88 GiB/s** |      1.26 GiB/s |            328 MiB/s |            498 MiB/s |
+|  4 KiB |  **9.22 GiB/s** |      1.50 GiB/s |           1.14 GiB/s |           1.70 GiB/s |
+| 16 KiB | **10.90 GiB/s** |      1.56 GiB/s |           4.29 GiB/s |           6.27 GiB/s |
+| 64 KiB |     13.03 GiB/s |      1.55 GiB/s |          10.10 GiB/s |      **15.18 GiB/s** |
 
 ### Message rate
 
 |   Size | shared (buffer) | shared (string) | postMessage (buffer) | postMessage (string) |
 | -----: | --------------: | --------------: | -------------------: | -------------------: |
-|   64 B |   **27.53 M/s** |       12.33 M/s |             1.57 M/s |             1.97 M/s |
-|  256 B |   **13.14 M/s** |       10.31 M/s |             1.47 M/s |             1.90 M/s |
-|  1 KiB |        5.04 M/s |    **7.93 M/s** |             1.38 M/s |             1.77 M/s |
-|  4 KiB |        1.32 M/s |    **4.31 M/s** |             1.02 M/s |             1.35 M/s |
-| 16 KiB |         334 K/s |    **1.46 M/s** |              594 K/s |              498 K/s |
-| 64 KiB |          87 K/s |     **203 K/s** |              145 K/s |              216 K/s |
-
-### CPU efficiency (instructions per cycle)
-
-|   Size | shared (buffer) | shared (string) | postMessage (buffer) | postMessage (string) |
-| -----: | --------------: | --------------: | -------------------: | -------------------: |
-|   64 B |            5.45 |            5.62 |                 3.89 |                 3.35 |
-|  256 B |            4.52 |            5.76 |                 3.82 |                 3.18 |
-|  1 KiB |            4.18 |        **6.25** |                 3.65 |                 3.16 |
-|  4 KiB |            3.79 |        **6.65** |                 3.51 |                 2.92 |
-| 16 KiB |            3.73 |        **6.12** |                 2.91 |                 2.63 |
-| 64 KiB |            3.93 |        **4.30** |                 2.44 |                 2.92 |
+|   64 B |   **14.76 M/s** |        6.72 M/s |              405 K/s |              688 K/s |
+|  256 B |   **11.20 M/s** |        3.67 M/s |              360 K/s |              648 K/s |
+|  1 KiB |    **5.12 M/s** |        1.32 M/s |              336 K/s |              510 K/s |
+|  4 KiB |    **2.42 M/s** |         394 K/s |              298 K/s |              445 K/s |
+| 16 KiB |     **714 K/s** |         102 K/s |              281 K/s |              411 K/s |
+| 64 KiB |         213 K/s |          25 K/s |              165 K/s |          **249 K/s** |
 
 ### Key findings
 
-- **Small messages (64-256 B):** The shared ring buffer with `Buffer.copy` delivers
-  up to **18x higher message rate** and **14x higher throughput** than `postMessage`.
-  Per-message overhead dominates at these sizes, and avoiding structured cloning makes
-  the biggest difference. The `Int32Array` meta path is especially effective here —
-  27.5 M msg/s at 64 B with 5.45 IPC.
+- **Small messages (64–256 B):** The shared ring buffer with `Buffer.set` delivers
+  **14.8–11.2 M msg/s** — up to **36x faster** than `postMessage` (buffer) and
+  **21x faster** than `postMessage` (string). Per-message overhead dominates at
+  these sizes, and avoiding structured cloning makes the biggest difference.
 
-- **Large messages (1-64 KiB):** The shared ring buffer with string encoding
-  (`Buffer.write`) reaches up to **22 GiB/s** — roughly **2-4x faster** than
-  `postMessage`. V8's ASCII fast path for UTF-8 encoding is heavily vectorized
-  (6-7 IPC on Apple M3 Pro), which explains why string writes outperform raw
-  `Buffer.copy` at larger sizes.
+- **Medium to large messages (1–16 KiB):** `Buffer.set` via the ring buffer
+  maintains its lead, reaching **10.9 GiB/s** at 16 KiB — **1.7–5.4x faster**
+  than the best `postMessage` variant.
 
-- **CPU efficiency:** The shared ring buffer consistently achieves higher IPC
-  (4-7) compared to `postMessage` (2-4), indicating less time spent stalled on
-  memory or synchronization.
+- **Very large messages (64 KiB):** `postMessage` (string) overtakes the shared
+  buffer at **15.2 GiB/s** vs **13.0 GiB/s**. At this size, structured cloning
+  overhead is amortized and the kernel's optimized `memcpy` dominates.
 
 - **Caveat:** The string benchmark uses ASCII-only content. Multi-byte UTF-8
   strings will not hit V8's vectorized fast path and will be significantly slower.
@@ -225,8 +235,7 @@ collected with [`@mitata/counters`](https://github.com/evanwashere/mitata).
 ### Running the benchmark
 
 ```sh
-# Hardware counters require elevated privileges on macOS
-sudo node --allow-natives-syntax packages/shared/src/bench.mjs
+node --allow-natives-syntax packages/shared/src/bench.mjs
 ```
 
 ## License

package/lib/index.d.ts

@@ -25,7 +25,7 @@ export declare class State {
  */
 export declare class Reader {
     #private;
-    constructor(state: State);
+    constructor(state: State | SharedArrayBuffer);
     readSome<U>(next: (data: BufferRegion, opaque?: U) => void | boolean, opaque?: U): number;
 }
 /**
@@ -33,7 +33,7 @@ export declare class Reader {
  */
 export declare class Writer {
     #private;
-    constructor(state: State, { yield: onYield, logger }?: WriterOptions);
+    constructor(state: State | SharedArrayBuffer, { yield: onYield, logger }?: WriterOptions);
     /**
      * Synchronously writes a message. Blocks (via `Atomics.wait`) until buffer space is available.
      * Writing more than "len" bytes in the callback will cause undefined behavior.

package/lib/index.js

@@ -74,8 +74,8 @@ export class Reader {
   #data              
   #readPos        
 
-  constructor(state       ) {
-    const sharedBuffer = state.buffer
+  constructor(state                           ) {
+    const sharedBuffer = state instanceof SharedArrayBuffer ? state : state.buffer
     const size = sharedBuffer.byteLength - STATE_BYTES
 
     this.#state = new Int32Array(sharedBuffer, 0, STATE_BYTES >> 2)
@@ -183,8 +183,8 @@ export class Writer {
   #logger                                                      
   #uncorkBound            
 
-  constructor(state       , { yield: onYield, logger }                = {}) {
-    const sharedBuffer = state.buffer
+  constructor(state                           , { yield: onYield, logger }                = {}) {
+    const sharedBuffer = state instanceof SharedArrayBuffer ? state : state.buffer
 
     if (onYield != null && typeof onYield !== 'function') {
       throw new TypeError('onYield must be a function')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/shared",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -26,6 +26,5 @@
     "oxlint-tsgolint": "^0.13.0",
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
-  },
-  "gitHead": "18d5bdc8855ad9012882b03cab144a9625b8c4b8"
+  }
 }