sabcom 0.1.94 → 0.1.123

package/README.md

@@ -8,6 +8,18 @@
 
 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.
 
+## 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 does **NOT**:
+- Create worker threads (you create them with `worker_threads` or `new Worker()`)
+- Transfer the SharedArrayBuffer between threads (you pass it via `workerData` or `postMessage`)
+- Serialize data (you encode to `Uint8Array` before calling write, e.g., with `TextEncoder` or `JSON.stringify`)
+
 ## Features
 
 - **Thread-safe communication** using `Atomics` for synchronization.
@@ -128,6 +140,100 @@ await write(data, buffer, {
     *   **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
+
+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.
+
+**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()));
+}
+
+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.
+
+3. **Parallel operations** - Use `Promise.all()` with async API (`write`/`read`) to communicate with multiple workers concurrently.
+
+4. **Buffer pool pattern** - For dynamic worker counts, maintain a pool of buffers:
+
+```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);
+  }
+}
+```
+
 ## Advanced: Generators
 
 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.
@@ -175,6 +281,85 @@ The communication follows a strict handshake:
 
 *Note: The `SharedArrayBuffer` is reusable after a successful transfer.*
 
+## 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:
+
+```typescript
+// Writer
+const obj = { hello: 'world', count: 42 };
+const json = JSON.stringify(obj);
+await write(new TextEncoder().encode(json), buffer);
+
+// Reader
+const data = await read(buffer);
+const obj = 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:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+### How do I handle errors?
+
+```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:
+
+```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;
+}
+```
+
+### Can I reuse the buffer after a transfer?
+
+Yes. After a successful transfer (or error), the buffer resets to `READY` state and can be used again:
+
+```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);
+```
+
 ## Development
 
 ```bash

package/build/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const SEMAPHORE = 0;\n\nexport enum Semaphore {\n  READY,\n  HANDSHAKE,\n  PAYLOAD,\n}\n\nexport enum Handshake {\n  TOTAL_SIZE = 1,\n  TOTAL_CHUNKS,\n}\n\nexport enum Header {\n  CHUNK_INDEX = 1,\n  CHUNK_OFFSET,\n  CHUNK_SIZE,\n}\n\nexport const HEADER_VALUES = 4;\n\n/**\n * Size in bytes reserved for protocol header in the SharedArrayBuffer.\n * The usable payload size is `buffer.byteLength - HEADER_SIZE`.\n */\nexport const HEADER_SIZE = Uint32Array.BYTES_PER_ELEMENT * HEADER_VALUES;\n\nexport interface Options {\n  /** Max wait time in milliseconds before timeout error. Default: 5000 */\n  timeout?: number;\n}\n\nexport interface WaitRequest {\n  target: Int32Array;\n  index: number;\n  value: number;\n  timeout?: number;\n}\n\nexport type WaitResponse = ReturnType<typeof Atomics.wait>;\n\nexport function* writeGenerator(data: Uint8Array, buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, void, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const totalSize = data.length;\n  const totalChunks = Math.ceil(totalSize / chunkSize);\n  const header = new Int32Array(buffer);\n\n  header[Handshake.TOTAL_SIZE] = totalSize;\n  header[Handshake.TOTAL_CHUNKS] = totalChunks;\n  Atomics.store(header, SEMAPHORE, Semaphore.HANDSHAKE);\n  Atomics.notify(header, SEMAPHORE);\n\n  try {\n    const handshakeResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.HANDSHAKE,\n      timeout,\n    };\n    if (handshakeResult === 'timed-out') {\n      throw new Error('Reader handshake timeout');\n    }\n\n    const payload = new Uint8Array(buffer, HEADER_SIZE);\n    for (let i = 0; i < totalChunks; i++) {\n      const start = i * chunkSize;\n      const end = Math.min(start + chunkSize, totalSize);\n      const size = end - start;\n      payload.set(data.subarray(start, end), 0);\n      header[Header.CHUNK_INDEX] = i;\n      header[Header.CHUNK_OFFSET] = start;\n      header[Header.CHUNK_SIZE] = size;\n      Atomics.store(header, SEMAPHORE, Semaphore.PAYLOAD);\n      Atomics.notify(header, SEMAPHORE);\n\n      const chunkResult: WaitResponse = yield {\n        target: header,\n        index: SEMAPHORE,\n        value: Semaphore.PAYLOAD,\n        timeout,\n      };\n      if (chunkResult === 'timed-out') {\n        throw new Error(`Reader timeout on chunk ${i}/${totalChunks - 1}`);\n      }\n    }\n  } finally {\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n}\n\nexport function* readGenerator(buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, Uint8Array, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const header = new Int32Array(buffer);\n\n  const handshakeResult: WaitResponse = yield {\n    target: header,\n    index: SEMAPHORE,\n    value: Semaphore.READY,\n    timeout,\n  };\n  if (handshakeResult === 'timed-out') {\n    throw new Error('Handshake timeout');\n  }\n  if (header[SEMAPHORE] !== Semaphore.HANDSHAKE) {\n    throw new Error('Invalid handshake state');\n  }\n\n  const totalSize = header[Handshake.TOTAL_SIZE];\n  const totalChunks = header[Handshake.TOTAL_CHUNKS];\n  if (totalSize < 0 || totalChunks < 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize === 0 && totalChunks !== 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize > totalChunks * chunkSize) {\n    throw new Error('Invalid handshake values');\n  }\n  const data = new Uint8Array(totalSize);\n\n  Atomics.store(header, SEMAPHORE, Semaphore.READY);\n  Atomics.notify(header, SEMAPHORE);\n\n  const payload = new Uint8Array(buffer, HEADER_SIZE);\n  for (let i = 0; i < totalChunks; i++) {\n    const chunkResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.READY,\n      timeout,\n    };\n    if (chunkResult === 'timed-out') {\n      throw new Error(`Writer timeout waiting for chunk ${i}`);\n    }\n    // @ts-expect-error does not infer number\n    if (header[SEMAPHORE] !== Semaphore.PAYLOAD) {\n      throw new Error(`Expected payload header, received ${Semaphore[header[SEMAPHORE]]}`);\n    }\n    const chunkIndex = header[Header.CHUNK_INDEX];\n    if (i !== chunkIndex) {\n      throw new Error(`Reader integrity failure for chunk ${chunkIndex} expected ${i}`);\n    }\n    const offset = header[Header.CHUNK_OFFSET];\n    const size = header[Header.CHUNK_SIZE];\n    if (offset < 0 || size <= 0 || size > chunkSize || offset + size > totalSize) {\n      throw new Error(`Invalid chunk metadata for chunk ${chunkIndex}`);\n    }\n    data.set(payload.subarray(0, size), offset);\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n  return data;\n}\n\n/**\n * Synchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Blocks until the reader receives all data. Use in workers where blocking is acceptable.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { writeSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = new TextEncoder().encode('Hello from worker');\n * writeSync(data, buffer);\n * ```\n */\nexport const writeSync = (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): void => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Asynchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Non-blocking, suitable for main thread. Resolves when the reader receives all data.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { write } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * const data = new TextEncoder().encode('Hello from main');\n * await write(data, buffer);\n * ```\n */\nexport const write = async (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): Promise<void> => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Synchronously reads data from a SharedArrayBuffer written by another thread.\n * Blocks until all data is received. Use in workers where blocking is acceptable.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { readSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = readSync(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const readSync = (buffer: SharedArrayBuffer, options?: Options): Uint8Array => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n\n/**\n * Asynchronously reads data from a SharedArrayBuffer written by another thread.\n * Non-blocking, suitable for main thread. Resolves when all data is received.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { read } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * // Worker writes data...\n * const data = await read(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const read = async (buffer: SharedArrayBuffer, options?: Options): Promise<Uint8Array> => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n"],"names":["HEADER_SIZE","HEADER_VALUES","Handshake","Header","SEMAPHORE","Semaphore","read","readGenerator","readSync","write","writeGenerator","writeSync","Uint32Array","BYTES_PER_ELEMENT","data","buffer","timeout","byteLength","Int32Array","Error","chunkSize","totalSize","length","totalChunks","Math","ceil","header","Atomics","store","notify","handshakeResult","target","index","value","payload","Uint8Array","i","start","end","min","size","set","subarray","chunkResult","chunkIndex","offset","options","gen","result","next","done","waitResult","wait","request","waitAsync"],"mappings":"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"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const SEMAPHORE = 0;\n\nexport enum Semaphore {\n  READY,\n  HANDSHAKE,\n  PAYLOAD,\n}\n\nexport enum Handshake {\n  TOTAL_SIZE = 1,\n  TOTAL_CHUNKS,\n}\n\nexport enum Header {\n  CHUNK_INDEX = 1,\n  CHUNK_OFFSET,\n  CHUNK_SIZE,\n}\n\nexport const HEADER_VALUES = 4;\n\n/**\n * Size in bytes reserved for protocol header in the SharedArrayBuffer.\n * The usable payload size is `buffer.byteLength - HEADER_SIZE`.\n */\nexport const HEADER_SIZE = Uint32Array.BYTES_PER_ELEMENT * HEADER_VALUES;\n\nexport interface Options {\n  /** Max wait time in milliseconds before timeout error. Default: 5000 */\n  timeout?: number;\n}\n\n/**\n * Request yielded by generator functions for Atomics.wait/waitAsync.\n * Pass to Atomics.wait() for sync or Atomics.waitAsync() for async waiting.\n */\nexport interface WaitRequest {\n  /** Int32Array view of the SharedArrayBuffer header */\n  target: Int32Array;\n  /** Index in the array to wait on (always SEMAPHORE = 0) */\n  index: number;\n  /** Value to compare against before waiting */\n  value: number;\n  /** Timeout in milliseconds */\n  timeout?: number;\n}\n\nexport type WaitResponse = ReturnType<typeof Atomics.wait>;\n\n/**\n * Low-level generator for writing data with custom flow control.\n * Use for progress tracking, cancellation, or custom scheduling.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @yields {WaitRequest} Request to wait for reader acknowledgment\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { writeGenerator } from 'sabcom';\n *\n * const gen = writeGenerator(data, buffer);\n * let chunks = 0;\n * for (const request of gen) {\n *   const result = Atomics.wait(request.target, request.index, request.value, request.timeout);\n *   if (result === 'timed-out') throw new Error('Timeout');\n *   console.log(`Chunk ${++chunks} sent`);\n * }\n * ```\n */\nexport function* writeGenerator(data: Uint8Array, buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, void, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const totalSize = data.length;\n  const totalChunks = Math.ceil(totalSize / chunkSize);\n  const header = new Int32Array(buffer);\n\n  header[Handshake.TOTAL_SIZE] = totalSize;\n  header[Handshake.TOTAL_CHUNKS] = totalChunks;\n  Atomics.store(header, SEMAPHORE, Semaphore.HANDSHAKE);\n  Atomics.notify(header, SEMAPHORE);\n\n  try {\n    const handshakeResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.HANDSHAKE,\n      timeout,\n    };\n    if (handshakeResult === 'timed-out') {\n      throw new Error('Reader handshake timeout');\n    }\n\n    const payload = new Uint8Array(buffer, HEADER_SIZE);\n    for (let i = 0; i < totalChunks; i++) {\n      const start = i * chunkSize;\n      const end = Math.min(start + chunkSize, totalSize);\n      const size = end - start;\n      payload.set(data.subarray(start, end), 0);\n      header[Header.CHUNK_INDEX] = i;\n      header[Header.CHUNK_OFFSET] = start;\n      header[Header.CHUNK_SIZE] = size;\n      Atomics.store(header, SEMAPHORE, Semaphore.PAYLOAD);\n      Atomics.notify(header, SEMAPHORE);\n\n      const chunkResult: WaitResponse = yield {\n        target: header,\n        index: SEMAPHORE,\n        value: Semaphore.PAYLOAD,\n        timeout,\n      };\n      if (chunkResult === 'timed-out') {\n        throw new Error(`Reader timeout on chunk ${i}/${totalChunks - 1}`);\n      }\n    }\n  } finally {\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n}\n\n/**\n * Low-level generator for reading data with custom flow control.\n * Use for progress tracking, cancellation, or custom scheduling.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @yields {WaitRequest} Request to wait for writer data\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { readGenerator } from 'sabcom';\n *\n * const gen = readGenerator(buffer);\n * let result = gen.next();\n * while (!result.done) {\n *   const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n *   result = gen.next(waitResult);\n * }\n * const data = result.value; // Uint8Array\n * ```\n */\nexport function* readGenerator(buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, Uint8Array, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const header = new Int32Array(buffer);\n\n  const handshakeResult: WaitResponse = yield {\n    target: header,\n    index: SEMAPHORE,\n    value: Semaphore.READY,\n    timeout,\n  };\n  if (handshakeResult === 'timed-out') {\n    throw new Error('Handshake timeout');\n  }\n  if (header[SEMAPHORE] !== Semaphore.HANDSHAKE) {\n    throw new Error('Invalid handshake state');\n  }\n\n  const totalSize = header[Handshake.TOTAL_SIZE];\n  const totalChunks = header[Handshake.TOTAL_CHUNKS];\n  if (totalSize < 0 || totalChunks < 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize === 0 && totalChunks !== 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize > totalChunks * chunkSize) {\n    throw new Error('Invalid handshake values');\n  }\n  const data = new Uint8Array(totalSize);\n\n  Atomics.store(header, SEMAPHORE, Semaphore.READY);\n  Atomics.notify(header, SEMAPHORE);\n\n  const payload = new Uint8Array(buffer, HEADER_SIZE);\n  for (let i = 0; i < totalChunks; i++) {\n    const chunkResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.READY,\n      timeout,\n    };\n    if (chunkResult === 'timed-out') {\n      throw new Error(`Writer timeout waiting for chunk ${i}`);\n    }\n    // @ts-expect-error does not infer number\n    if (header[SEMAPHORE] !== Semaphore.PAYLOAD) {\n      throw new Error(`Expected payload header, received ${Semaphore[header[SEMAPHORE]]}`);\n    }\n    const chunkIndex = header[Header.CHUNK_INDEX];\n    if (i !== chunkIndex) {\n      throw new Error(`Reader integrity failure for chunk ${chunkIndex} expected ${i}`);\n    }\n    const offset = header[Header.CHUNK_OFFSET];\n    const size = header[Header.CHUNK_SIZE];\n    if (offset < 0 || size <= 0 || size > chunkSize || offset + size > totalSize) {\n      throw new Error(`Invalid chunk metadata for chunk ${chunkIndex}`);\n    }\n    data.set(payload.subarray(0, size), offset);\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n  return data;\n}\n\n/**\n * Synchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Blocks until the reader receives all data. Use in workers where blocking is acceptable.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { writeSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = new TextEncoder().encode('Hello from worker');\n * writeSync(data, buffer);\n * ```\n */\nexport const writeSync = (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): void => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Asynchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Non-blocking, suitable for main thread. Resolves when the reader receives all data.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { write } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * const data = new TextEncoder().encode('Hello from main');\n * await write(data, buffer);\n * ```\n */\nexport const write = async (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): Promise<void> => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Synchronously reads data from a SharedArrayBuffer written by another thread.\n * Blocks until all data is received. Use in workers where blocking is acceptable.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { readSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = readSync(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const readSync = (buffer: SharedArrayBuffer, options?: Options): Uint8Array => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n\n/**\n * Asynchronously reads data from a SharedArrayBuffer written by another thread.\n * Non-blocking, suitable for main thread. Resolves when all data is received.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { read } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * // Worker writes data...\n * const data = await read(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const read = async (buffer: SharedArrayBuffer, options?: Options): Promise<Uint8Array> => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n"],"names":["HEADER_SIZE","HEADER_VALUES","Handshake","Header","SEMAPHORE","Semaphore","read","readGenerator","readSync","write","writeGenerator","writeSync","Uint32Array","BYTES_PER_ELEMENT","data","buffer","timeout","byteLength","Int32Array","Error","chunkSize","totalSize","length","totalChunks","Math","ceil","header","Atomics","store","notify","handshakeResult","target","index","value","payload","Uint8Array","i","start","end","min","size","set","subarray","chunkResult","chunkIndex","offset","options","gen","result","next","done","waitResult","wait","request","waitAsync"],"mappings":";;;;;;;;;;;QAyBaA;eAAAA;;QANAC;eAAAA;;QAXDC;eAAAA;;QAKAC;eAAAA;;QAbCC;eAAAA;;QAEDC;eAAAA;;QAgVCC;eAAAA;;QAxLIC;eAAAA;;QAuJJC;eAAAA;;QA/BAC;eAAAA;;QAzMIC;eAAAA;;QA2KJC;eAAAA;;;AApPN,MAAMP,YAAY;AAElB,IAAA,AAAKC,mCAAAA;;;;WAAAA;;AAML,IAAA,AAAKH,mCAAAA;;;WAAAA;;AAKL,IAAA,AAAKC,gCAAAA;;;;WAAAA;;AAML,MAAMF,gBAAgB;AAMtB,MAAMD,cAAcY,YAAYC,iBAAiB,GAAGZ;AAgDpD,UAAUS,eAAeI,IAAgB,EAAEC,MAAyB,EAAE,EAAEC,UAAU,IAAI,EAAW,GAAG,CAAC,CAAC;IAC3G,IAAID,OAAOE,UAAU,GAAGC,WAAWL,iBAAiB,KAAK,GAAG;QAC1D,MAAM,IAAIM,MAAM;IAClB;IACA,MAAMC,YAAYL,OAAOE,UAAU,GAAGjB;IACtC,IAAIoB,aAAa,GAAG;QAClB,MAAM,IAAID,MAAM;IAClB;IACA,MAAME,YAAYP,KAAKQ,MAAM;IAC7B,MAAMC,cAAcC,KAAKC,IAAI,CAACJ,YAAYD;IAC1C,MAAMM,SAAS,IAAIR,WAAWH;IAE9BW,MAAM,GAAsB,GAAGL;IAC/BK,MAAM,GAAwB,GAAGH;IACjCI,QAAQC,KAAK,CAACF,QAAQtB;IACtBuB,QAAQE,MAAM,CAACH,QAAQtB;IAEvB,IAAI;QACF,MAAM0B,kBAAgC,MAAM;YAC1CC,QAAQL;YACRM,OAAO5B;YACP6B,KAAK;YACLjB;QACF;QACA,IAAIc,oBAAoB,aAAa;YACnC,MAAM,IAAIX,MAAM;QAClB;QAEA,MAAMe,UAAU,IAAIC,WAAWpB,QAAQf;QACvC,IAAK,IAAIoC,IAAI,GAAGA,IAAIb,aAAaa,IAAK;YACpC,MAAMC,QAAQD,IAAIhB;YAClB,MAAMkB,MAAMd,KAAKe,GAAG,CAACF,QAAQjB,WAAWC;YACxC,MAAMmB,OAAOF,MAAMD;YACnBH,QAAQO,GAAG,CAAC3B,KAAK4B,QAAQ,CAACL,OAAOC,MAAM;YACvCZ,MAAM,GAAoB,GAAGU;YAC7BV,MAAM,GAAqB,GAAGW;YAC9BX,MAAM,GAAmB,GAAGc;YAC5Bb,QAAQC,KAAK,CAACF,QAAQtB;YACtBuB,QAAQE,MAAM,CAACH,QAAQtB;YAEvB,MAAMuC,cAA4B,MAAM;gBACtCZ,QAAQL;gBACRM,OAAO5B;gBACP6B,KAAK;gBACLjB;YACF;YACA,IAAI2B,gBAAgB,aAAa;gBAC/B,MAAM,IAAIxB,MAAM,CAAC,wBAAwB,EAAEiB,EAAE,CAAC,EAAEb,cAAc,GAAG;YACnE;QACF;IACF,SAAU;QACRI,QAAQC,KAAK,CAACF,QAAQtB;QACtBuB,QAAQE,MAAM,CAACH,QAAQtB;IACzB;AACF;AA2BO,UAAUG,cAAcQ,MAAyB,EAAE,EAAEC,UAAU,IAAI,EAAW,GAAG,CAAC,CAAC;IACxF,IAAID,OAAOE,UAAU,GAAGC,WAAWL,iBAAiB,KAAK,GAAG;QAC1D,MAAM,IAAIM,MAAM;IAClB;IACA,MAAMC,YAAYL,OAAOE,UAAU,GAAGjB;IACtC,IAAIoB,aAAa,GAAG;QAClB,MAAM,IAAID,MAAM;IAClB;IACA,MAAMO,SAAS,IAAIR,WAAWH;IAE9B,MAAMe,kBAAgC,MAAM;QAC1CC,QAAQL;QACRM,OAAO5B;QACP6B,KAAK;QACLjB;IACF;IACA,IAAIc,oBAAoB,aAAa;QACnC,MAAM,IAAIX,MAAM;IAClB;IACA,IAAIO,MAAM,CAACtB,UAAU,QAA0B;QAC7C,MAAM,IAAIe,MAAM;IAClB;IAEA,MAAME,YAAYK,MAAM,GAAsB;IAC9C,MAAMH,cAAcG,MAAM,GAAwB;IAClD,IAAIL,YAAY,KAAKE,cAAc,GAAG;QACpC,MAAM,IAAIJ,MAAM;IAClB;IACA,IAAIE,cAAc,KAAKE,gBAAgB,GAAG;QACxC,MAAM,IAAIJ,MAAM;IAClB;IACA,IAAIE,YAAYE,cAAcH,WAAW;QACvC,MAAM,IAAID,MAAM;IAClB;IACA,MAAML,OAAO,IAAIqB,WAAWd;IAE5BM,QAAQC,KAAK,CAACF,QAAQtB;IACtBuB,QAAQE,MAAM,CAACH,QAAQtB;IAEvB,MAAM8B,UAAU,IAAIC,WAAWpB,QAAQf;IACvC,IAAK,IAAIoC,IAAI,GAAGA,IAAIb,aAAaa,IAAK;QACpC,MAAMO,cAA4B,MAAM;YACtCZ,QAAQL;YACRM,OAAO5B;YACP6B,KAAK;YACLjB;QACF;QACA,IAAI2B,gBAAgB,aAAa;YAC/B,MAAM,IAAIxB,MAAM,CAAC,iCAAiC,EAAEiB,GAAG;QACzD;QAEA,IAAIV,MAAM,CAACtB,UAAU,QAAwB;YAC3C,MAAM,IAAIe,MAAM,CAAC,kCAAkC,EAAEd,SAAS,CAACqB,MAAM,CAACtB,UAAU,CAAC,EAAE;QACrF;QACA,MAAMwC,aAAalB,MAAM,GAAoB;QAC7C,IAAIU,MAAMQ,YAAY;YACpB,MAAM,IAAIzB,MAAM,CAAC,mCAAmC,EAAEyB,WAAW,UAAU,EAAER,GAAG;QAClF;QACA,MAAMS,SAASnB,MAAM,GAAqB;QAC1C,MAAMc,OAAOd,MAAM,GAAmB;QACtC,IAAImB,SAAS,KAAKL,QAAQ,KAAKA,OAAOpB,aAAayB,SAASL,OAAOnB,WAAW;YAC5E,MAAM,IAAIF,MAAM,CAAC,iCAAiC,EAAEyB,YAAY;QAClE;QACA9B,KAAK2B,GAAG,CAACP,QAAQQ,QAAQ,CAAC,GAAGF,OAAOK;QACpClB,QAAQC,KAAK,CAACF,QAAQtB;QACtBuB,QAAQE,MAAM,CAACH,QAAQtB;IACzB;IACA,OAAOU;AACT;AAsBO,MAAMH,YAAY,CAACG,MAAkBC,QAA2B+B;IACrE,MAAMC,MAAMrC,eAAeI,MAAMC,QAAQ+B;IACzC,IAAIE,SAASD,IAAIE,IAAI;IACrB,MAAO,CAACD,OAAOE,IAAI,CAAE;QACnB,MAAMC,aAAaxB,QAAQyB,IAAI,CAACJ,OAAOf,KAAK,CAACF,MAAM,EAAEiB,OAAOf,KAAK,CAACD,KAAK,EAAEgB,OAAOf,KAAK,CAACA,KAAK,EAAEe,OAAOf,KAAK,CAACjB,OAAO;QACjHgC,SAASD,IAAIE,IAAI,CAACE;IACpB;AACF;AAuBO,MAAM1C,QAAQ,OAAOK,MAAkBC,QAA2B+B;IACvE,MAAMC,MAAMrC,eAAeI,MAAMC,QAAQ+B;IACzC,IAAIE,SAASD,IAAIE,IAAI;IACrB,MAAO,CAACD,OAAOE,IAAI,CAAE;QACnB,MAAMG,UAAUL,OAAOf,KAAK;QAC5B,MAAMkB,aAAa,MAAMxB,QAAQ2B,SAAS,CAACD,QAAQtB,MAAM,EAAEsB,QAAQrB,KAAK,EAAEqB,QAAQpB,KAAK,EAAEoB,QAAQrC,OAAO,EAAEiB,KAAK;QAC/Ge,SAASD,IAAIE,IAAI,CAACE;IACpB;AACF;AAuBO,MAAM3C,WAAW,CAACO,QAA2B+B;IAClD,MAAMC,MAAMxC,cAAcQ,QAAQ+B;IAClC,IAAIE,SAASD,IAAIE,IAAI;IACrB,MAAO,CAACD,OAAOE,IAAI,CAAE;QACnB,MAAMC,aAAaxB,QAAQyB,IAAI,CAACJ,OAAOf,KAAK,CAACF,MAAM,EAAEiB,OAAOf,KAAK,CAACD,KAAK,EAAEgB,OAAOf,KAAK,CAACA,KAAK,EAAEe,OAAOf,KAAK,CAACjB,OAAO;QACjHgC,SAASD,IAAIE,IAAI,CAACE;IACpB;IACA,OAAOH,OAAOf,KAAK;AACrB;AAyBO,MAAM3B,OAAO,OAAOS,QAA2B+B;IACpD,MAAMC,MAAMxC,cAAcQ,QAAQ+B;IAClC,IAAIE,SAASD,IAAIE,IAAI;IACrB,MAAO,CAACD,OAAOE,IAAI,CAAE;QACnB,MAAMG,UAAUL,OAAOf,KAAK;QAC5B,MAAMkB,aAAa,MAAMxB,QAAQ2B,SAAS,CAACD,QAAQtB,MAAM,EAAEsB,QAAQrB,KAAK,EAAEqB,QAAQpB,KAAK,EAAEoB,QAAQrC,OAAO,EAAEiB,KAAK;QAC/Ge,SAASD,IAAIE,IAAI,CAACE;IACpB;IACA,OAAOH,OAAOf,KAAK;AACrB"}

package/build/index.d.ts

@@ -23,14 +23,71 @@ export interface Options {
     /** Max wait time in milliseconds before timeout error. Default: 5000 */
     timeout?: number;
 }
+/**
+ * Request yielded by generator functions for Atomics.wait/waitAsync.
+ * Pass to Atomics.wait() for sync or Atomics.waitAsync() for async waiting.
+ */
 export interface WaitRequest {
+    /** Int32Array view of the SharedArrayBuffer header */
     target: Int32Array;
+    /** Index in the array to wait on (always SEMAPHORE = 0) */
     index: number;
+    /** Value to compare against before waiting */
     value: number;
+    /** Timeout in milliseconds */
     timeout?: number;
 }
 export type WaitResponse = ReturnType<typeof Atomics.wait>;
+/**
+ * Low-level generator for writing data with custom flow control.
+ * Use for progress tracking, cancellation, or custom scheduling.
+ * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)
+ * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)
+ * @param options - Optional configuration
+ * @yields {WaitRequest} Request to wait for reader acknowledgment
+ * @throws {Error} "SharedArrayBuffer byteLength must be a multiple of 4"
+ * @throws {Error} "SharedArrayBuffer too small for header"
+ * @throws {Error} "Reader handshake timeout" - reader didn't respond in time
+ * @throws {Error} "Reader timeout on chunk N/M" - reader stopped responding mid-transfer
+ * @example
+ * ```typescript
+ * import { writeGenerator } from 'sabcom';
+ *
+ * const gen = writeGenerator(data, buffer);
+ * let chunks = 0;
+ * for (const request of gen) {
+ *   const result = Atomics.wait(request.target, request.index, request.value, request.timeout);
+ *   if (result === 'timed-out') throw new Error('Timeout');
+ *   console.log(`Chunk ${++chunks} sent`);
+ * }
+ * ```
+ */
 export declare function writeGenerator(data: Uint8Array, buffer: SharedArrayBuffer, { timeout }?: Options): Generator<WaitRequest, void, WaitResponse>;
+/**
+ * Low-level generator for reading data with custom flow control.
+ * Use for progress tracking, cancellation, or custom scheduling.
+ * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)
+ * @param options - Optional configuration
+ * @yields {WaitRequest} Request to wait for writer data
+ * @returns Complete data as Uint8Array
+ * @throws {Error} "SharedArrayBuffer byteLength must be a multiple of 4"
+ * @throws {Error} "SharedArrayBuffer too small for header"
+ * @throws {Error} "Handshake timeout" - writer didn't send data in time
+ * @throws {Error} "Invalid handshake state" - protocol error
+ * @throws {Error} "Writer timeout waiting for chunk N" - writer stopped responding mid-transfer
+ * @example
+ * ```typescript
+ * import { readGenerator } from 'sabcom';
+ *
+ * const gen = readGenerator(buffer);
+ * let result = gen.next();
+ * while (!result.done) {
+ *   const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);
+ *   result = gen.next(waitResult);
+ * }
+ * const data = result.value; // Uint8Array
+ * ```
+ */
 export declare function readGenerator(buffer: SharedArrayBuffer, { timeout }?: Options): Generator<WaitRequest, Uint8Array, WaitResponse>;
 /**
  * Synchronously writes data to a SharedArrayBuffer for cross-thread transfer.

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const SEMAPHORE = 0;\n\nexport enum Semaphore {\n  READY,\n  HANDSHAKE,\n  PAYLOAD,\n}\n\nexport enum Handshake {\n  TOTAL_SIZE = 1,\n  TOTAL_CHUNKS,\n}\n\nexport enum Header {\n  CHUNK_INDEX = 1,\n  CHUNK_OFFSET,\n  CHUNK_SIZE,\n}\n\nexport const HEADER_VALUES = 4;\n\n/**\n * Size in bytes reserved for protocol header in the SharedArrayBuffer.\n * The usable payload size is `buffer.byteLength - HEADER_SIZE`.\n */\nexport const HEADER_SIZE = Uint32Array.BYTES_PER_ELEMENT * HEADER_VALUES;\n\nexport interface Options {\n  /** Max wait time in milliseconds before timeout error. Default: 5000 */\n  timeout?: number;\n}\n\nexport interface WaitRequest {\n  target: Int32Array;\n  index: number;\n  value: number;\n  timeout?: number;\n}\n\nexport type WaitResponse = ReturnType<typeof Atomics.wait>;\n\nexport function* writeGenerator(data: Uint8Array, buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, void, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const totalSize = data.length;\n  const totalChunks = Math.ceil(totalSize / chunkSize);\n  const header = new Int32Array(buffer);\n\n  header[Handshake.TOTAL_SIZE] = totalSize;\n  header[Handshake.TOTAL_CHUNKS] = totalChunks;\n  Atomics.store(header, SEMAPHORE, Semaphore.HANDSHAKE);\n  Atomics.notify(header, SEMAPHORE);\n\n  try {\n    const handshakeResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.HANDSHAKE,\n      timeout,\n    };\n    if (handshakeResult === 'timed-out') {\n      throw new Error('Reader handshake timeout');\n    }\n\n    const payload = new Uint8Array(buffer, HEADER_SIZE);\n    for (let i = 0; i < totalChunks; i++) {\n      const start = i * chunkSize;\n      const end = Math.min(start + chunkSize, totalSize);\n      const size = end - start;\n      payload.set(data.subarray(start, end), 0);\n      header[Header.CHUNK_INDEX] = i;\n      header[Header.CHUNK_OFFSET] = start;\n      header[Header.CHUNK_SIZE] = size;\n      Atomics.store(header, SEMAPHORE, Semaphore.PAYLOAD);\n      Atomics.notify(header, SEMAPHORE);\n\n      const chunkResult: WaitResponse = yield {\n        target: header,\n        index: SEMAPHORE,\n        value: Semaphore.PAYLOAD,\n        timeout,\n      };\n      if (chunkResult === 'timed-out') {\n        throw new Error(`Reader timeout on chunk ${i}/${totalChunks - 1}`);\n      }\n    }\n  } finally {\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n}\n\nexport function* readGenerator(buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, Uint8Array, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const header = new Int32Array(buffer);\n\n  const handshakeResult: WaitResponse = yield {\n    target: header,\n    index: SEMAPHORE,\n    value: Semaphore.READY,\n    timeout,\n  };\n  if (handshakeResult === 'timed-out') {\n    throw new Error('Handshake timeout');\n  }\n  if (header[SEMAPHORE] !== Semaphore.HANDSHAKE) {\n    throw new Error('Invalid handshake state');\n  }\n\n  const totalSize = header[Handshake.TOTAL_SIZE];\n  const totalChunks = header[Handshake.TOTAL_CHUNKS];\n  if (totalSize < 0 || totalChunks < 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize === 0 && totalChunks !== 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize > totalChunks * chunkSize) {\n    throw new Error('Invalid handshake values');\n  }\n  const data = new Uint8Array(totalSize);\n\n  Atomics.store(header, SEMAPHORE, Semaphore.READY);\n  Atomics.notify(header, SEMAPHORE);\n\n  const payload = new Uint8Array(buffer, HEADER_SIZE);\n  for (let i = 0; i < totalChunks; i++) {\n    const chunkResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.READY,\n      timeout,\n    };\n    if (chunkResult === 'timed-out') {\n      throw new Error(`Writer timeout waiting for chunk ${i}`);\n    }\n    // @ts-expect-error does not infer number\n    if (header[SEMAPHORE] !== Semaphore.PAYLOAD) {\n      throw new Error(`Expected payload header, received ${Semaphore[header[SEMAPHORE]]}`);\n    }\n    const chunkIndex = header[Header.CHUNK_INDEX];\n    if (i !== chunkIndex) {\n      throw new Error(`Reader integrity failure for chunk ${chunkIndex} expected ${i}`);\n    }\n    const offset = header[Header.CHUNK_OFFSET];\n    const size = header[Header.CHUNK_SIZE];\n    if (offset < 0 || size <= 0 || size > chunkSize || offset + size > totalSize) {\n      throw new Error(`Invalid chunk metadata for chunk ${chunkIndex}`);\n    }\n    data.set(payload.subarray(0, size), offset);\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n  return data;\n}\n\n/**\n * Synchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Blocks until the reader receives all data. Use in workers where blocking is acceptable.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { writeSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = new TextEncoder().encode('Hello from worker');\n * writeSync(data, buffer);\n * ```\n */\nexport const writeSync = (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): void => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Asynchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Non-blocking, suitable for main thread. Resolves when the reader receives all data.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { write } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * const data = new TextEncoder().encode('Hello from main');\n * await write(data, buffer);\n * ```\n */\nexport const write = async (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): Promise<void> => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Synchronously reads data from a SharedArrayBuffer written by another thread.\n * Blocks until all data is received. Use in workers where blocking is acceptable.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { readSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = readSync(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const readSync = (buffer: SharedArrayBuffer, options?: Options): Uint8Array => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n\n/**\n * Asynchronously reads data from a SharedArrayBuffer written by another thread.\n * Non-blocking, suitable for main thread. Resolves when all data is received.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { read } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * // Worker writes data...\n * const data = await read(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const read = async (buffer: SharedArrayBuffer, options?: Options): Promise<Uint8Array> => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n"],"names":["SEMAPHORE","Semaphore","Handshake","Header","HEADER_VALUES","HEADER_SIZE","Uint32Array","BYTES_PER_ELEMENT","writeGenerator","data","buffer","timeout","byteLength","Int32Array","Error","chunkSize","totalSize","length","totalChunks","Math","ceil","header","Atomics","store","notify","handshakeResult","target","index","value","payload","Uint8Array","i","start","end","min","size","set","subarray","chunkResult","readGenerator","chunkIndex","offset","writeSync","options","gen","result","next","done","waitResult","wait","write","request","waitAsync","readSync","read"],"mappings":"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"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export const SEMAPHORE = 0;\n\nexport enum Semaphore {\n  READY,\n  HANDSHAKE,\n  PAYLOAD,\n}\n\nexport enum Handshake {\n  TOTAL_SIZE = 1,\n  TOTAL_CHUNKS,\n}\n\nexport enum Header {\n  CHUNK_INDEX = 1,\n  CHUNK_OFFSET,\n  CHUNK_SIZE,\n}\n\nexport const HEADER_VALUES = 4;\n\n/**\n * Size in bytes reserved for protocol header in the SharedArrayBuffer.\n * The usable payload size is `buffer.byteLength - HEADER_SIZE`.\n */\nexport const HEADER_SIZE = Uint32Array.BYTES_PER_ELEMENT * HEADER_VALUES;\n\nexport interface Options {\n  /** Max wait time in milliseconds before timeout error. Default: 5000 */\n  timeout?: number;\n}\n\n/**\n * Request yielded by generator functions for Atomics.wait/waitAsync.\n * Pass to Atomics.wait() for sync or Atomics.waitAsync() for async waiting.\n */\nexport interface WaitRequest {\n  /** Int32Array view of the SharedArrayBuffer header */\n  target: Int32Array;\n  /** Index in the array to wait on (always SEMAPHORE = 0) */\n  index: number;\n  /** Value to compare against before waiting */\n  value: number;\n  /** Timeout in milliseconds */\n  timeout?: number;\n}\n\nexport type WaitResponse = ReturnType<typeof Atomics.wait>;\n\n/**\n * Low-level generator for writing data with custom flow control.\n * Use for progress tracking, cancellation, or custom scheduling.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @yields {WaitRequest} Request to wait for reader acknowledgment\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { writeGenerator } from 'sabcom';\n *\n * const gen = writeGenerator(data, buffer);\n * let chunks = 0;\n * for (const request of gen) {\n *   const result = Atomics.wait(request.target, request.index, request.value, request.timeout);\n *   if (result === 'timed-out') throw new Error('Timeout');\n *   console.log(`Chunk ${++chunks} sent`);\n * }\n * ```\n */\nexport function* writeGenerator(data: Uint8Array, buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, void, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const totalSize = data.length;\n  const totalChunks = Math.ceil(totalSize / chunkSize);\n  const header = new Int32Array(buffer);\n\n  header[Handshake.TOTAL_SIZE] = totalSize;\n  header[Handshake.TOTAL_CHUNKS] = totalChunks;\n  Atomics.store(header, SEMAPHORE, Semaphore.HANDSHAKE);\n  Atomics.notify(header, SEMAPHORE);\n\n  try {\n    const handshakeResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.HANDSHAKE,\n      timeout,\n    };\n    if (handshakeResult === 'timed-out') {\n      throw new Error('Reader handshake timeout');\n    }\n\n    const payload = new Uint8Array(buffer, HEADER_SIZE);\n    for (let i = 0; i < totalChunks; i++) {\n      const start = i * chunkSize;\n      const end = Math.min(start + chunkSize, totalSize);\n      const size = end - start;\n      payload.set(data.subarray(start, end), 0);\n      header[Header.CHUNK_INDEX] = i;\n      header[Header.CHUNK_OFFSET] = start;\n      header[Header.CHUNK_SIZE] = size;\n      Atomics.store(header, SEMAPHORE, Semaphore.PAYLOAD);\n      Atomics.notify(header, SEMAPHORE);\n\n      const chunkResult: WaitResponse = yield {\n        target: header,\n        index: SEMAPHORE,\n        value: Semaphore.PAYLOAD,\n        timeout,\n      };\n      if (chunkResult === 'timed-out') {\n        throw new Error(`Reader timeout on chunk ${i}/${totalChunks - 1}`);\n      }\n    }\n  } finally {\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n}\n\n/**\n * Low-level generator for reading data with custom flow control.\n * Use for progress tracking, cancellation, or custom scheduling.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @yields {WaitRequest} Request to wait for writer data\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { readGenerator } from 'sabcom';\n *\n * const gen = readGenerator(buffer);\n * let result = gen.next();\n * while (!result.done) {\n *   const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n *   result = gen.next(waitResult);\n * }\n * const data = result.value; // Uint8Array\n * ```\n */\nexport function* readGenerator(buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, Uint8Array, WaitResponse> {\n  if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {\n    throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');\n  }\n  const chunkSize = buffer.byteLength - HEADER_SIZE;\n  if (chunkSize <= 0) {\n    throw new Error('SharedArrayBuffer too small for header');\n  }\n  const header = new Int32Array(buffer);\n\n  const handshakeResult: WaitResponse = yield {\n    target: header,\n    index: SEMAPHORE,\n    value: Semaphore.READY,\n    timeout,\n  };\n  if (handshakeResult === 'timed-out') {\n    throw new Error('Handshake timeout');\n  }\n  if (header[SEMAPHORE] !== Semaphore.HANDSHAKE) {\n    throw new Error('Invalid handshake state');\n  }\n\n  const totalSize = header[Handshake.TOTAL_SIZE];\n  const totalChunks = header[Handshake.TOTAL_CHUNKS];\n  if (totalSize < 0 || totalChunks < 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize === 0 && totalChunks !== 0) {\n    throw new Error('Invalid handshake values');\n  }\n  if (totalSize > totalChunks * chunkSize) {\n    throw new Error('Invalid handshake values');\n  }\n  const data = new Uint8Array(totalSize);\n\n  Atomics.store(header, SEMAPHORE, Semaphore.READY);\n  Atomics.notify(header, SEMAPHORE);\n\n  const payload = new Uint8Array(buffer, HEADER_SIZE);\n  for (let i = 0; i < totalChunks; i++) {\n    const chunkResult: WaitResponse = yield {\n      target: header,\n      index: SEMAPHORE,\n      value: Semaphore.READY,\n      timeout,\n    };\n    if (chunkResult === 'timed-out') {\n      throw new Error(`Writer timeout waiting for chunk ${i}`);\n    }\n    // @ts-expect-error does not infer number\n    if (header[SEMAPHORE] !== Semaphore.PAYLOAD) {\n      throw new Error(`Expected payload header, received ${Semaphore[header[SEMAPHORE]]}`);\n    }\n    const chunkIndex = header[Header.CHUNK_INDEX];\n    if (i !== chunkIndex) {\n      throw new Error(`Reader integrity failure for chunk ${chunkIndex} expected ${i}`);\n    }\n    const offset = header[Header.CHUNK_OFFSET];\n    const size = header[Header.CHUNK_SIZE];\n    if (offset < 0 || size <= 0 || size > chunkSize || offset + size > totalSize) {\n      throw new Error(`Invalid chunk metadata for chunk ${chunkIndex}`);\n    }\n    data.set(payload.subarray(0, size), offset);\n    Atomics.store(header, SEMAPHORE, Semaphore.READY);\n    Atomics.notify(header, SEMAPHORE);\n  }\n  return data;\n}\n\n/**\n * Synchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Blocks until the reader receives all data. Use in workers where blocking is acceptable.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { writeSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = new TextEncoder().encode('Hello from worker');\n * writeSync(data, buffer);\n * ```\n */\nexport const writeSync = (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): void => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Asynchronously writes data to a SharedArrayBuffer for cross-thread transfer.\n * Non-blocking, suitable for main thread. Resolves when the reader receives all data.\n * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)\n * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Reader handshake timeout\" - reader didn't respond in time\n * @throws {Error} \"Reader timeout on chunk N/M\" - reader stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { write } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * const data = new TextEncoder().encode('Hello from main');\n * await write(data, buffer);\n * ```\n */\nexport const write = async (data: Uint8Array, buffer: SharedArrayBuffer, options?: Options): Promise<void> => {\n  const gen = writeGenerator(data, buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n};\n\n/**\n * Synchronously reads data from a SharedArrayBuffer written by another thread.\n * Blocks until all data is received. Use in workers where blocking is acceptable.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { workerData } from 'worker_threads';\n * import { readSync } from 'sabcom';\n *\n * const buffer = workerData as SharedArrayBuffer;\n * const data = readSync(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const readSync = (buffer: SharedArrayBuffer, options?: Options): Uint8Array => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n\n/**\n * Asynchronously reads data from a SharedArrayBuffer written by another thread.\n * Non-blocking, suitable for main thread. Resolves when all data is received.\n * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)\n * @param options - Optional configuration\n * @returns Complete data as Uint8Array\n * @throws {Error} \"SharedArrayBuffer byteLength must be a multiple of 4\"\n * @throws {Error} \"SharedArrayBuffer too small for header\"\n * @throws {Error} \"Handshake timeout\" - writer didn't send data in time\n * @throws {Error} \"Invalid handshake state\" - protocol error\n * @throws {Error} \"Writer timeout waiting for chunk N\" - writer stopped responding mid-transfer\n * @example\n * ```typescript\n * import { Worker } from 'worker_threads';\n * import { read } from 'sabcom';\n *\n * const buffer = new SharedArrayBuffer(4096);\n * const worker = new Worker('./worker.js', { workerData: buffer });\n * // Worker writes data...\n * const data = await read(buffer);\n * const message = new TextDecoder().decode(data);\n * ```\n */\nexport const read = async (buffer: SharedArrayBuffer, options?: Options): Promise<Uint8Array> => {\n  const gen = readGenerator(buffer, options);\n  let result = gen.next();\n  while (!result.done) {\n    const request = result.value;\n    const waitResult = await Atomics.waitAsync(request.target, request.index, request.value, request.timeout).value;\n    result = gen.next(waitResult);\n  }\n  return result.value;\n};\n"],"names":["SEMAPHORE","Semaphore","Handshake","Header","HEADER_VALUES","HEADER_SIZE","Uint32Array","BYTES_PER_ELEMENT","writeGenerator","data","buffer","timeout","byteLength","Int32Array","Error","chunkSize","totalSize","length","totalChunks","Math","ceil","header","Atomics","store","notify","handshakeResult","target","index","value","payload","Uint8Array","i","start","end","min","size","set","subarray","chunkResult","readGenerator","chunkIndex","offset","writeSync","options","gen","result","next","done","waitResult","wait","write","request","waitAsync","readSync","read"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sabcom",
-  "version": "0.1.94",
+  "version": "0.1.123",
   "description": "A TypeScript/Node.js library for inter-thread communication using SharedArrayBuffer with atomic operations for raw buffer data transfer",
   "type": "module",
   "types": "build/index.d.ts",
@@ -41,20 +41,20 @@
     "url": "https://linkedin.com/in/3axap4eHko"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^25.0.10",
-    "@typescript-eslint/eslint-plugin": "^8.53.1",
-    "@typescript-eslint/parser": "^8.53.1",
-    "@vitest/coverage-v8": "^4.0.17",
-    "eslint": "^9.39.2",
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
     "husky": "^9.1.7",
-    "inop": "^0.8.10",
+    "inop": "^0.9.0",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.53.1",
-    "vitest": "^4.0.17"
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.2"
   },
   "scripts": {
     "build": "rm -rf build && inop src build -i __tests__ -i *.tmp.ts && tsc --declaration --emitDeclarationOnly",

package/src/index.ts

@@ -30,15 +30,47 @@ export interface Options {
   timeout?: number;
 }
 
+/**
+ * Request yielded by generator functions for Atomics.wait/waitAsync.
+ * Pass to Atomics.wait() for sync or Atomics.waitAsync() for async waiting.
+ */
 export interface WaitRequest {
+  /** Int32Array view of the SharedArrayBuffer header */
   target: Int32Array;
+  /** Index in the array to wait on (always SEMAPHORE = 0) */
   index: number;
+  /** Value to compare against before waiting */
   value: number;
+  /** Timeout in milliseconds */
   timeout?: number;
 }
 
 export type WaitResponse = ReturnType<typeof Atomics.wait>;
 
+/**
+ * Low-level generator for writing data with custom flow control.
+ * Use for progress tracking, cancellation, or custom scheduling.
+ * @param data - Bytes to send (can be larger than buffer, will be chunked automatically)
+ * @param buffer - SharedArrayBuffer shared with the reader thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)
+ * @param options - Optional configuration
+ * @yields {WaitRequest} Request to wait for reader acknowledgment
+ * @throws {Error} "SharedArrayBuffer byteLength must be a multiple of 4"
+ * @throws {Error} "SharedArrayBuffer too small for header"
+ * @throws {Error} "Reader handshake timeout" - reader didn't respond in time
+ * @throws {Error} "Reader timeout on chunk N/M" - reader stopped responding mid-transfer
+ * @example
+ * ```typescript
+ * import { writeGenerator } from 'sabcom';
+ *
+ * const gen = writeGenerator(data, buffer);
+ * let chunks = 0;
+ * for (const request of gen) {
+ *   const result = Atomics.wait(request.target, request.index, request.value, request.timeout);
+ *   if (result === 'timed-out') throw new Error('Timeout');
+ *   console.log(`Chunk ${++chunks} sent`);
+ * }
+ * ```
+ */
 export function* writeGenerator(data: Uint8Array, buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, void, WaitResponse> {
   if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {
     throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');
@@ -95,6 +127,31 @@ export function* writeGenerator(data: Uint8Array, buffer: SharedArrayBuffer, { t
   }
 }
 
+/**
+ * Low-level generator for reading data with custom flow control.
+ * Use for progress tracking, cancellation, or custom scheduling.
+ * @param buffer - SharedArrayBuffer shared with the writer thread (byteLength must be multiple of 4 and larger than HEADER_SIZE)
+ * @param options - Optional configuration
+ * @yields {WaitRequest} Request to wait for writer data
+ * @returns Complete data as Uint8Array
+ * @throws {Error} "SharedArrayBuffer byteLength must be a multiple of 4"
+ * @throws {Error} "SharedArrayBuffer too small for header"
+ * @throws {Error} "Handshake timeout" - writer didn't send data in time
+ * @throws {Error} "Invalid handshake state" - protocol error
+ * @throws {Error} "Writer timeout waiting for chunk N" - writer stopped responding mid-transfer
+ * @example
+ * ```typescript
+ * import { readGenerator } from 'sabcom';
+ *
+ * const gen = readGenerator(buffer);
+ * let result = gen.next();
+ * while (!result.done) {
+ *   const waitResult = Atomics.wait(result.value.target, result.value.index, result.value.value, result.value.timeout);
+ *   result = gen.next(waitResult);
+ * }
+ * const data = result.value; // Uint8Array
+ * ```
+ */
 export function* readGenerator(buffer: SharedArrayBuffer, { timeout = 5000 }: Options = {}): Generator<WaitRequest, Uint8Array, WaitResponse> {
   if (buffer.byteLength % Int32Array.BYTES_PER_ELEMENT !== 0) {
     throw new Error('SharedArrayBuffer byteLength must be a multiple of 4');