sabcom 0.1.140 → 0.1.141

package/README.md

@@ -6,14 +6,15 @@
 [![Coverage Status][codecov-image]][codecov-url]
 [![Snyk][snyk-image]][snyk-url]
 
-A TypeScript/Node.js library for high-performance inter-thread communication using `SharedArrayBuffer` with atomic operations. It provides both synchronous and asynchronous APIs to transfer byte data between threads (e.g., Main thread and Worker threads) without the overhead of structured cloning or memory copying.
+High-performance inter-thread communication using `SharedArrayBuffer` with atomic operations. Bidirectional channels with synchronous and asynchronous APIs. Faster than `postMessage` structured clone and transfer.
 
 ## What sabcom Does
 
-sabcom is a **protocol layer** for SharedArrayBuffer. It handles:
-- Synchronization between reader and writer via Atomics
-- Chunking large data that exceeds buffer size
-- Timeout detection to prevent deadlocks
+sabcom is a **ring-buffer protocol** over SharedArrayBuffer. It handles:
+- Bidirectional communication on a single SharedArrayBuffer
+- Synchronization between endpoints via Atomics
+- Segmented transfer for payloads larger than the ring capacity
+- Timeout detection and close semantics
 
 sabcom does **NOT**:
 - Create worker threads (you create them with `worker_threads` or `new Worker()`)
@@ -22,13 +23,13 @@ sabcom does **NOT**:
 
 ## Features
 
-- **Thread-safe communication** using `Atomics` for synchronization.
-- **Async and Sync APIs** to suit different architectural needs.
-- **Chunked Data Transfer** allows sending payloads larger than the buffer size.
-- **Byte-only API** for explicit serialization control.
-- **Configurable Timeouts** to prevent deadlocks.
-- **Generator-based Low-level API** for custom flow control implementations.
-- **Type-safe** with full TypeScript support.
+- **Bidirectional** - both endpoints can read and write on a single buffer
+- **Async and Sync APIs** - `write`/`read` (non-blocking) and `writeSync`/`readSync` (blocking)
+- **Zero-copy reads** - single-segment messages return a view into the SharedArrayBuffer
+- **Segmented transfer** - payloads larger than the ring are split automatically
+- **Close and reuse** - channels can be closed and buffers reused
+- **Configurable timeouts** - per-operation timeout support
+- **Type-safe** - full TypeScript support
 
 ## Installation
 
@@ -38,347 +39,190 @@ npm install sabcom
 
 ## Complete Example
 
-Here is a complete example demonstrating communication between a main thread and a worker thread using Node.js `worker_threads`.
-The `SharedArrayBuffer` is passed once via `workerData` so no `postMessage` is needed for data transfer.
-
 **worker.ts**
 ```typescript
 import { workerData } from 'worker_threads';
-import { readSync, writeSync } from 'sabcom';
+import { open } from 'sabcom';
 
-const buffer = workerData as SharedArrayBuffer;
+const ch = open(workerData as SharedArrayBuffer);
 
-try {
-  console.log('Worker: Waiting for data...');
-  const receivedData = readSync(buffer);
-  const message = new TextDecoder().decode(receivedData);
-  console.log('Worker: Received message:', message);
+const data = ch.readSync();
+const message = new TextDecoder().decode(data);
+console.log('Worker received:', message);
 
-  const reply = new TextEncoder().encode(message.toUpperCase());
-  writeSync(reply, buffer);
-} catch (err) {
-  console.error('Worker: Error', err);
-  process.exit(1);
-}
+ch.writeSync(new TextEncoder().encode(message.toUpperCase()));
+ch.close();
 ```
 
 **main.ts**
 ```typescript
 import { Worker } from 'worker_threads';
-import { write, read } from 'sabcom';
-import path from 'path';
-
-async function main() {
-  // 1. Create a SharedArrayBuffer (must be multiple of 4)
-  // 4KB buffer
-  const buffer = new SharedArrayBuffer(4096);
+import { createBuffer, open } from 'sabcom';
 
-  // 2. Start the worker and pass the buffer via workerData
-  const worker = new Worker(path.resolve(__dirname, 'worker.ts'), { workerData: buffer });
+const buffer = createBuffer(65536);
+const worker = new Worker('./worker.js', { workerData: buffer });
+const ch = open(buffer);
 
-  // 3. Prepare data
-  const text = "Hello from the main thread! ".repeat(500); // Larger than buffer
-  const data = new TextEncoder().encode(text);
+const text = 'Hello from the main thread!';
+await ch.write(new TextEncoder().encode(text));
 
-  console.log(`Main: Sending ${data.byteLength} bytes...`);
+const reply = await ch.read();
+console.log('Reply:', new TextDecoder().decode(reply));
 
-  // 4. Write data to the shared buffer
-  // The 'read' operation in the worker will pick this up.
-  await write(data, buffer);
-
-  const reply = await read(buffer);
-  console.log('Main: Reply:', new TextDecoder().decode(reply));
-}
-
-main().catch(console.error);
+ch.close();
+await worker.terminate();
 ```
 
-## Usage
-
-### Async API
-Best for non-blocking operations in the main thread or event-loop driven workers.
-
-```typescript
-import { write, read } from 'sabcom';
+## API
 
-// Writer
-await write(data, buffer);
+### `createBuffer(byteLength: number): SharedArrayBuffer`
 
-// Reader
-const result = await read(buffer);
-```
+Creates and initializes a SharedArrayBuffer for use as a channel. `byteLength` must be a multiple of 4 and at least 4096.
 
-### Sync API
-Best for CPU-bound workers where blocking is acceptable or preferred.
+### `open(buffer: SharedArrayBuffer): Channel`
 
-```typescript
-import { writeSync, readSync } from 'sabcom';
+Opens a channel on the buffer. Two endpoints can open the same buffer (one per thread). Returns the same handle if called twice in the same thread.
 
-// Writer
-writeSync(data, buffer);
-
-// Reader
-const result = readSync(buffer);
-```
+### `reset(buffer: SharedArrayBuffer): void`
 
-### Options
+Resets a closed buffer so it can be reopened. Both endpoints must be closed first.
 
-All functions accept an optional options object:
+### Channel
 
 ```typescript
-await write(data, buffer, { 
-  timeout: 10000 // Timeout in milliseconds (default: 5000)
-});
+interface Channel {
+  write(data: Uint8Array, options?: Options): Promise<void>;
+  read(options?: Options): Promise<Uint8Array>;
+  writeSync(data: Uint8Array, options?: Options): void;
+  readSync(options?: Options): Uint8Array;
+  close(): void;
+}
 ```
 
-## Buffer Sizing & Requirements
-
-1.  **Multiple of 4**: The `byteLength` of the `SharedArrayBuffer` **must** be a multiple of 4 (e.g., 1024, 4096).
-2.  **Header Overhead**: The library uses a small portion of the buffer for a header. The buffer must be larger than `HEADER_SIZE` (exported).
-3.  **Performance Trade-off**:
-    *   **Larger Buffer**: Fewer chunks, less synchronization overhead, faster for large data.
-    *   **Smaller Buffer**: Less memory usage, more context switches/atomic operations.
-    *   **Recommendation**: Start with 4KB - 64KB (`4096` - `65536`) depending on your average payload size.
-
-## Multi-Worker Architecture
+- `write` / `writeSync` - send data to the peer endpoint
+- `read` / `readSync` - receive data from the peer endpoint
+- `close` - close this endpoint and notify the peer
 
-When multiple workers need to communicate with the main thread simultaneously, create a separate `SharedArrayBuffer` for each worker. Each buffer is an independent communication channel.
+### Options
 
-**main.ts**
 ```typescript
-import { Worker } from 'worker_threads';
-import { write, read } from 'sabcom';
-
-interface WorkerChannel {
-  worker: Worker;
-  buffer: SharedArrayBuffer;
-}
-
-async function createWorker(id: number): Promise<WorkerChannel> {
-  const buffer = new SharedArrayBuffer(4096);
-  const worker = new Worker('./worker.js', {
-    workerData: { id, buffer }
-  });
-  return { worker, buffer };
-}
-
-async function main() {
-  // Create multiple workers, each with its own buffer
-  const channels: WorkerChannel[] = await Promise.all([
-    createWorker(0),
-    createWorker(1),
-    createWorker(2),
-  ]);
-
-  // Send data to all workers in parallel
-  const tasks = ['task-a', 'task-b', 'task-c'];
-  await Promise.all(
-    channels.map((ch, i) =>
-      write(new TextEncoder().encode(tasks[i]), ch.buffer)
-    )
-  );
-
-  // Read responses from all workers in parallel
-  const responses = await Promise.all(
-    channels.map(ch => read(ch.buffer))
-  );
-
-  responses.forEach((data, i) => {
-    console.log(`Worker ${i}: ${new TextDecoder().decode(data)}`);
-  });
-
-  // Cleanup
-  await Promise.all(channels.map(ch => ch.worker.terminate()));
+interface Options {
+  timeout?: number; // milliseconds, default: 5000
 }
-
-main();
-```
-
-**worker.ts**
-```typescript
-import { workerData, parentPort } from 'worker_threads';
-import { readSync, writeSync } from 'sabcom';
-
-const { id, buffer } = workerData as { id: number; buffer: SharedArrayBuffer };
-
-// Receive task from main
-const task = new TextDecoder().decode(readSync(buffer));
-console.log(`Worker ${id} received: ${task}`);
-
-// Process and respond
-const result = `${task.toUpperCase()}-done`;
-writeSync(new TextEncoder().encode(result), buffer);
 ```
 
-### Key Points for Multi-Worker Setup
-
-1. **One buffer per worker** - Each worker needs its own `SharedArrayBuffer`. A single buffer can only handle one reader-writer pair at a time.
-
-2. **Buffer ownership** - Each buffer represents a bidirectional channel between main thread and one worker. Don't share a buffer between multiple workers.
+## Zero-Copy Reads
 
-3. **Parallel operations** - Use `Promise.all()` with async API (`write`/`read`) to communicate with multiple workers concurrently.
+When a message fits in a single ring segment and does not wrap the ring boundary, `readSync` and `read` return a `Uint8Array` view directly into the SharedArrayBuffer - no allocation or copy. The view is valid until the next method call on the same channel (`read`, `readSync`, `write`, `writeSync`, or `close`). After that, the underlying memory may be overwritten by the peer.
 
-4. **Buffer pool pattern** - For dynamic worker counts, maintain a pool of buffers:
+If you need to keep the data beyond the next call, copy it:
 
 ```typescript
-class BufferPool {
-  private available: SharedArrayBuffer[] = [];
-
-  acquire(size = 4096): SharedArrayBuffer {
-    return this.available.pop() ?? new SharedArrayBuffer(size);
-  }
-
-  release(buffer: SharedArrayBuffer): void {
-    this.available.push(buffer);
-  }
-}
+const view = ch.readSync();
+const copy = view.slice(); // safe to hold indefinitely
 ```
 
-## Advanced: Generators
+Messages that wrap the ring boundary or span multiple segments return an owned copy automatically.
 
-If you need fine-grained control over the transfer process (e.g., to implement a progress bar, cancellation, or custom scheduling), you can use the generator functions directly.
+## Buffer Sizing
 
-```typescript
-import { writeGenerator } from 'sabcom';
-
-const gen = writeGenerator(data, buffer);
-let result = gen.next();
-
-while (!result.done) {
-    // Perform custom logic here (e.g. check for cancellation)
-    
-    // Wait for the reader signal
-    const request = result.value;
-    const waitResult = Atomics.wait(request.target, request.index, request.value, request.timeout);
-    
-    // Resume generator
-    result = gen.next(waitResult);
-}
-```
+- **Minimum**: 4096 bytes
+- **Multiple of 4** required
+- **Larger buffers** reduce segmentation overhead for large payloads
+- **Recommendation**: 4KB-64KB depending on average payload size
 
-## API Reference
+The buffer is split into two ring directions (one per endpoint). Each direction contains control metadata, message descriptors, and a data ring. Larger buffers allocate more data ring space.
 
-### `write(data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): Promise<void>`
-Writes bytes to the buffer. Resolves when the reader has received all data.
+## Multi-Worker Architecture
 
-### `read(buffer: SharedArrayBuffer, options?: Options): Promise<Uint8Array>`
-Waits for and reads bytes from the buffer. Resolves with the complete data.
+Each worker needs its own SharedArrayBuffer. A single buffer supports exactly two endpoints.
 
-### `writeSync(data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): void`
-Synchronous version of `write`. Blocks until completion.
+```typescript
+import { Worker } from 'worker_threads';
+import { createBuffer, open } from 'sabcom';
 
-### `readSync(buffer: SharedArrayBuffer, options?: Options): Uint8Array`
-Synchronous version of `read`. Blocks until data is received.
+async function spawnWorker(task: string) {
+  const buffer = createBuffer(65536);
+  const worker = new Worker('./worker.js', { workerData: buffer });
+  const ch = open(buffer);
 
-## Protocol Details
+  ch.writeSync(new TextEncoder().encode(task));
+  const result = await ch.read();
 
-The communication follows a strict handshake:
-1.  **Writer** acquires lock, writes metadata (total size, chunk count) -> `HANDSHAKE`.
-2.  **Reader** acknowledges -> `READY`.
-3.  **Writer** writes chunk -> `PAYLOAD`.
-4.  **Reader** reads chunk, acknowledges -> `READY`.
-5.  Repeat 3-4 until done.
+  ch.close();
+  await worker.terminate();
+  return new TextDecoder().decode(result);
+}
 
-*Note: The `SharedArrayBuffer` is reusable after a successful transfer.*
+const results = await Promise.all([
+  spawnWorker('task-a'),
+  spawnWorker('task-b'),
+  spawnWorker('task-c'),
+]);
+```
 
 ## FAQ
 
-### What is the minimum buffer size?
-
-`HEADER_SIZE` is 16 bytes. Your buffer must be larger to have usable payload space:
-
-```typescript
-import { HEADER_SIZE } from 'sabcom';
-
-// Minimum: HEADER_SIZE + at least 1 byte for payload
-// Practical minimum: 1024 bytes (1KB)
-const buffer = new SharedArrayBuffer(1024);
-```
-
 ### How do I send JSON or objects?
 
-sabcom transfers raw bytes only. Serialize before sending:
+sabcom transfers raw bytes. Serialize before sending:
 
 ```typescript
-// Writer
 const obj = { hello: 'world', count: 42 };
-const json = JSON.stringify(obj);
-await write(new TextEncoder().encode(json), buffer);
+ch.writeSync(new TextEncoder().encode(JSON.stringify(obj)));
 
-// Reader
-const data = await read(buffer);
-const obj = JSON.parse(new TextDecoder().decode(data));
+const data = ch.readSync();
+const parsed = JSON.parse(new TextDecoder().decode(data));
 ```
 
 ### Does sabcom work in browsers?
 
-Yes, with Web Workers. However, `SharedArrayBuffer` requires cross-origin isolation headers on your server:
+Yes, with Web Workers. `SharedArrayBuffer` requires cross-origin isolation headers:
 
 ```
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-### How do I handle errors?
+### Can I reuse the buffer after closing?
 
-```typescript
-try {
-  await write(data, buffer, { timeout: 5000 });
-} catch (err) {
-  if (err.message.includes('timeout')) {
-    console.error('Reader did not respond in time');
-  }
-}
-```
-
-### Can I cancel a transfer mid-way?
-
-Use generators with `for...of` - breaking out automatically triggers cleanup:
+Yes. After both endpoints close, call `reset(buffer)` and reopen:
 
 ```typescript
-const gen = writeGenerator(data, buffer);
-for (const request of gen) {
-  if (shouldCancel) break; // finally block resets buffer to READY
-  const result = Atomics.wait(request.target, request.index, request.value, request.timeout);
-  if (result === 'timed-out') break;
-}
+ch.close();
+// ... peer also closes ...
+reset(buffer);
+const ch2 = open(buffer);
 ```
 
-### Can I reuse the buffer after a transfer?
+Or pass the buffer to new workers - `open` auto-resets buffers where both endpoints have closed.
 
-Yes. After a successful transfer (or error), the buffer resets to `READY` state and can be used again:
+### How do I handle errors?
 
 ```typescript
-const buffer = new SharedArrayBuffer(4096);
-
-// First transfer
-await write(data1, buffer);
-const result1 = await read(buffer);
-
-// Second transfer - same buffer
-await write(data2, buffer);
-const result2 = await read(buffer);
+try {
+  ch.writeSync(data, { timeout: 5000 });
+} catch (err) {
+  if (err.message.includes('timeout')) {
+    console.error('Peer did not respond in time');
+  } else if (err.message.includes('closed')) {
+    console.error('Peer closed the channel');
+  }
+}
 ```
 
 ## Development
 
 ```bash
-# Install dependencies
 pnpm install
-
-# Build
 pnpm build
-
-# Run tests
 pnpm test
-
-# Lint
-pnpm lint
+pnpm bench
 ```
 
 ## License
 
-Apache-2.0 © [Ivan Zakharchanka](https://linkedin.com/in/3axap4eHko)
+Apache-2.0 (c) [Ivan Zakharchanka](https://linkedin.com/in/3axap4eHko)
 
 [npm-url]: https://www.npmjs.com/package/sabcom
 [downloads-image]: https://img.shields.io/npm/dw/sabcom.svg?maxAge=43200