@nxtedition/shared 3.0.0 → 3.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 nxtedition
+Copyright (c) nxtedition
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,50 +1,162 @@
-# shared
+# @nxtedition/shared
 
-Ring Buffer for NodeJS cross Worker communication.
+A high-performance, thread-safe ring buffer for inter-thread communication in Node.js using `SharedArrayBuffer`.
+
+## Why
+
+Passing data between worker threads in Node.js typically involves structured cloning or transferring `ArrayBuffer` ownership. Structured cloning copies every byte — fine for occasional messages, but a bottleneck when streaming megabytes per second between threads. Transferable objects avoid the copy, but each transfer still requires allocating a new `ArrayBuffer`, serializing the transfer list, and coordinating ownership between threads — overhead that adds up quickly in high-throughput scenarios.
+
+This ring buffer avoids these problems. A single `SharedArrayBuffer` is mapped into both threads. The writer appends messages by advancing a write pointer; the reader consumes them by advancing a read pointer. No copies, no ownership transfers, no cloning overhead. Because messages are stored inline in a contiguous buffer, data lives right where the protocol is rather than scattered across separately allocated `ArrayBuffer`s — keeping access patterns cache-friendly. The pointers are coordinated with `Atomics` operations, and cache-line-aligned to prevent false sharing between CPU cores.
+
+Reads are zero-copy: the reader callback receives a `DataView` directly into the shared buffer, so parsing can happen in-place without allocating intermediate buffers. Writes are batched — the write pointer is only published to the reader after a high-water mark is reached or the current event loop tick ends, drastically reducing the frequency of expensive atomic stores.
+
+## Platform Assumptions
+
+This library assumes that unaligned 32-bit reads and writes will not tear on the target platform. This holds true on x86/x64 and ARM64, which are the primary targets for Node.js.
 
 ## Install
 
-```
-npm i @nxtedition/shared
+```sh
+npm install @nxtedition/shared
 ```
 
-## Quick Start
+## Usage
 
 ```js
-// index.js
+import { alloc, reader, writer } from '@nxtedition/shared'
+
+// Allocate shared memory (pass these buffers to a worker thread)
+const { sharedState, sharedBuffer } = alloc(1024 * 1024) // 1 MB ring buffer
+
+// --- Writer side (e.g. main thread) ---
+const w = writer({ sharedState, sharedBuffer })
 
-import * as shared from '@nxtedition/shared'
-import tp from 'timers/promise'
+const payload = Buffer.from('hello world')
+w.writeSync(payload.length, (data) => {
+  payload.copy(data.buffer, data.offset)
+  return data.offset + payload.length
+})
 
-const writer = shared.alloc(16 * 1024 * 1024)
-const reader = shared.alloc(16 * 1024 * 1024)
+// --- Reader side (e.g. worker thread) ---
+const r = reader({ sharedState, sharedBuffer })
 
-const worker = new Worker(new URL('worker.js', import.meta.url), {
-  workerData: { reader, writer },
+r.readSome((data) => {
+  const msg = data.buffer.subarray(data.offset, data.offset + data.length).toString()
+  console.log(msg) // 'hello world'
 })
+```
+
+### Batching writes with cork
 
-const writeToWorker = shared.writer(reader)
+```js
+w.cork(() => {
+  for (const item of items) {
+    const buf = Buffer.from(JSON.stringify(item))
+    w.writeSync(buf.length, (data) => {
+      buf.copy(data.buffer, data.offset)
+      return data.offset + buf.length
+    })
+  }
+})
+// All writes flushed atomically when cork returns
+```
 
-writeToWorker(Buffer.from('ping'))
+### Non-blocking writes with tryWrite
 
-for await (const buffer of shared.reader(writer)) {
-  console.log(`From worker ${buffer}`)
-  await tp.setTimeout(1e3) // Backpressure
-  writeToWorker(Buffer.from('pong'))
+```js
+const buf = Buffer.from('data')
+const ok = w.tryWrite(buf.length, (data) => {
+  buf.copy(data.buffer, data.offset)
+  return data.offset + buf.length
+})
+if (!ok) {
+  // Buffer is full — the reader hasn't caught up yet
 }
 ```
 
+### Cross-thread usage
+
 ```js
-// worker.js
+// main.js
+import { alloc, writer } from '@nxtedition/shared'
+import { Worker } from 'node:worker_threads'
 
-import * as shared from '@nxtedition/shared'
-import tp from 'timers/promise'
+const { sharedState, sharedBuffer } = alloc(1024 * 1024)
+const worker = new Worker('./reader-worker.js', {
+  workerData: { sharedState, sharedBuffer },
+})
+
+const w = writer({ sharedState, sharedBuffer })
+// ... write messages
+```
 
-const writeToParent = shared.writer(workerData.writer)
+```js
+// reader-worker.js
+import { reader } from '@nxtedition/shared'
+import { workerData } from 'node:worker_threads'
+
+const r = reader(workerData)
 
-for await (const buffer of shared.reader(workerData.reader)) {
-  console.log(`From parent ${buffer}`)
-  await tp.setTimeout(1e3) // Backpressure
-  writeToWorker(Buffer.from('pong'))
+function poll() {
+  const count = r.readSome((data) => {
+    // process data.buffer at data.offset..data.offset+data.length
+  })
+  setImmediate(poll)
 }
+poll()
 ```
+
+## API
+
+### `alloc(size: number): SharedBuffers`
+
+Allocates the shared memory buffers for a ring buffer of the given byte size.
+
+- **size** — Buffer capacity in bytes (must be a positive integer, max ~2 GB)
+- Returns `{ sharedState: SharedArrayBuffer, sharedBuffer: SharedArrayBuffer }`
+
+### `reader(buffers: SharedBuffers): Reader`
+
+Creates a reader for the ring buffer.
+
+#### `reader.readSome(next): number`
+
+Reads a batch of messages. Calls `next(data)` for each message, where `data` has:
+
+- `buffer: Buffer` — The underlying shared buffer
+- `view: DataView` — A DataView over the shared buffer
+- `offset: number` — Start offset of the message payload
+- `length: number` — Length of the message payload in bytes
+
+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.
+
+### `writer(buffers: SharedBuffers, options?): Writer`
+
+Creates a writer for the ring buffer.
+
+**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, timeout?): void`
+
+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.offset`. **Must return the end position** (`data.offset + bytesWritten`), not the byte count.
+- **timeout** — Max wait time in ms (default: 60000). Throws on timeout.
+
+#### `writer.tryWrite(len, fn): boolean`
+
+Non-blocking write attempt. Returns `false` if the buffer is full. The `fn` callback follows the same contract as `writeSync`.
+
+#### `writer.cork(callback): T`
+
+Batches multiple writes within the callback. The write pointer is only published to the reader when `cork` returns, reducing atomic operation overhead.
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,44 @@
+export interface SharedBuffers {
+    sharedState: SharedArrayBuffer;
+    sharedBuffer: SharedArrayBuffer;
+}
+export interface BufferRegion {
+    buffer: Buffer;
+    view: DataView;
+    offset: number;
+    length: number;
+    byteOffset: number;
+    byteLength: number;
+}
+/**
+ * Allocates the shared memory buffers.
+ */
+export declare function alloc(size: number): SharedBuffers;
+export interface Reader {
+    readSome<U>(next: (data: BufferRegion, opaque: U) => void | boolean, opaque: U): number;
+    readSome(next: (data: BufferRegion) => void | boolean): number;
+}
+/**
+ * Creates a reader for the ring buffer.
+ */
+export declare function reader({ sharedState, sharedBuffer }: SharedBuffers): Reader;
+export interface WriterOptions {
+    yield?: () => void;
+    logger?: {
+        warn(obj: object, msg: string): void;
+    };
+}
+export interface Writer {
+    tryWrite(len: number, fn: (data: BufferRegion) => number): boolean;
+    tryWrite<U>(len: number, fn: (data: BufferRegion, opaque: U) => number, opaque: U): boolean;
+    writeSync(len: number, fn: (data: BufferRegion) => number): void;
+    writeSync<U>(len: number, fn: (data: BufferRegion, opaque: U) => number, opaque: U): void;
+    cork<T>(callback: () => T): T;
+    cork(): void;
+    uncork(): void;
+    flushSync(): void;
+}
+/**
+ * Creates a writer for the ring buffer.
+ */
+export declare function writer({ sharedState, sharedBuffer }: SharedBuffers, { yield: onYield, logger }?: WriterOptions): Writer;