sab-message-port 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Shlomi Loubaton
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,440 @@
+# sab-message-port
+
+High-performance IPC for Web Workers and Node.js worker threads over `SharedArrayBuffer`.
+
+Passes JSON messages between threads through shared memory using `Atomics` for synchronization — no serialization through `postMessage`, no copying overhead. Supports both **blocking** reads (via `Atomics.wait` in worker threads) and **non-blocking** async reads (via `Atomics.waitAsync`, safe on the main thread). Large messages are chunked transparently.
+
+## Motivation
+
+The native `postMessage` API is event-loop driven — a worker can only receive messages by yielding control back to the event loop. This makes it unsuitable for long-running synchronous worker code that needs to communicate mid-execution without returning from its current call stack.
+
+`sab-message-port` solves this by providing a **blocking read** (`Atomics.wait`) that lets a worker pause in place, wait for a message, and resume — with no dependence on the event loop. The worker stays in its own synchronous flow while the main thread sends messages asynchronously from the other side.
+
+## Install
+
+```bash
+npm install sab-message-port
+```
+
+```javascript
+import { SABMessagePort, SABPipe } from 'sab-message-port';
+```
+
+## Quick Start
+
+**Main thread:**
+
+```javascript
+import { SABMessagePort } from 'sab-message-port';
+
+const port = new SABMessagePort();
+port.postInit(worker);
+
+port.onmessage = (e) => console.log('from worker:', e.data);
+port.postMessage({ cmd: 'ping' });
+```
+
+**Worker:**
+
+```javascript
+import { SABMessagePort } from 'sab-message-port';
+
+self.onmessage = (e) => {
+  if (e.data.type === 'SABMessagePort') {
+    const port = SABMessagePort.from(e.data);
+
+    port.onmessage = (e) => {
+      if (e.data.cmd === 'ping') {
+        port.postMessage({ reply: 'pong' });
+      }
+    };
+  }
+};
+```
+
+## Example: Blocking Reads with Interrupt
+
+With native `postMessage`, a worker can only receive messages by returning to the event loop. If the worker is stuck in a long synchronous loop, incoming messages pile up undelivered. `sab-message-port` solves this — `port.read()` blocks in-place via `Atomics.wait`, and `port.tryRead()` checks for signals mid-computation, all without yielding to the event loop.
+
+**main.js**
+
+```javascript
+import { SABMessagePort } from 'sab-message-port';
+
+const worker = new Worker('./worker.js', { type: 'module' });
+const port = new SABMessagePort();
+port.postInit(worker);
+
+port.onmessage = ({ data }) => console.log(data);
+
+// Start a long task
+port.postMessage({ cmd: 'run', task: 'A', iterations: 5_000_000 });
+
+// After 200ms, abort and start a different task
+setTimeout(() => {
+  port.postMessage({ cmd: 'abort' });
+  port.postMessage({ cmd: 'run', task: 'B', iterations: 2_000_000 });
+}, 200);
+```
+
+**worker.js** — entirely synchronous, never yields to the event loop
+
+```javascript
+import { SABMessagePort } from 'sab-message-port';
+
+self.onmessage = (e) => {
+  if (e.data.type !== 'SABMessagePort') return;
+  const port = SABMessagePort.from(e.data);
+
+  while (true) {
+    const task = port.read();            // block until a task arrives
+    if (task.cmd !== 'run') continue;
+
+    for (let i = 0; i < task.iterations; i++) {
+      /* ... heavy work ... */
+
+      if (i % 500_000 === 0) {
+        port.postMessage({ task: task.task, progress: `${(i / task.iterations * 100) | 0}%` });
+
+        if (port.tryRead()?.cmd === 'abort') {   // non-blocking check
+          port.postMessage({ task: task.task, aborted: true });
+          break;                                  // → back to port.read()
+        }
+      }
+    }
+  }
+};
+```
+
+---
+
+## SABMessagePort
+
+Bidirectional channel over a single `SharedArrayBuffer`. Both sides can read and write simultaneously — full duplex. API mirrors the native `MessagePort`.
+
+All messages must be **JSON-serializable** (they go through `JSON.stringify`/`JSON.parse` internally). Message ordering is **FIFO** — messages are always delivered in the order they were sent.
+
+### `new SABMessagePort(side = 'a', sizeKB = 256)`
+
+Creates a new bidirectional port.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `side` | `'a'` | `'a'` (initiator) or `'b'` (responder). Typically only the initiator is created directly; the responder uses `SABMessagePort.from()`. |
+| `sizeKB` | `256` | Total buffer size in KB (split in half between the two directions), or an existing `SharedArrayBuffer`. Each direction gets `sizeKB / 2` KB of buffer space. |
+
+```javascript
+const port = new SABMessagePort();          // 256 KB total (128 KB per direction), side 'a'
+const port = new SABMessagePort('a', 512);  // 512 KB total (256 KB per direction)
+
+// Or pass an existing SharedArrayBuffer
+const sab = new SharedArrayBuffer(256 * 1024);
+const port = new SABMessagePort('a', sab);
+```
+
+Throws if `side` is not `'a'` or `'b'`.
+
+### `SABMessagePort.from(initMsg)`
+
+Creates the responder side (`'b'`) from a received init message. The init message must have `type: 'SABMessagePort'` and a `buffer` property containing the `SharedArrayBuffer`.
+
+Throws if `initMsg.type !== 'SABMessagePort'`.
+
+```javascript
+// Worker side
+self.onmessage = (e) => {
+  if (e.data.type === 'SABMessagePort') {
+    const port = SABMessagePort.from(e.data);
+    // ready to send and receive
+  }
+};
+```
+
+### `port.postInit(target = null, extraProps = {})`
+
+Sends the shared buffer to the other side via `postMessage`, or returns the arguments for manual sending.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `target` | `null` | A `Worker`, `MessagePort`, or any object with a `postMessage` method. If `null`, returns the arguments instead of sending. |
+| `extraProps` | `{}` | Additional properties merged into the init message (e.g. `{ channel: 'rpc' }`). |
+
+When `target` is provided, calls `target.postMessage(data, transferList)` directly. When `target` is `null`, returns `[data, transferList]` — a two-element array where `data` is the init message object and `transferList` is `[sharedArrayBuffer]`.
+
+```javascript
+// Auto-send to worker
+port.postInit(worker, { channel: 'rpc' });
+
+// Manual — returns [data, transferList]
+const [data, transfer] = port.postInit(null, { channel: 'rpc' });
+// data = { type: 'SABMessagePort', buffer: SharedArrayBuffer, channel: 'rpc' }
+// transfer = [SharedArrayBuffer]
+worker.postMessage(data, transfer);
+```
+
+### `port.postMessage(msg)` → `Promise`
+
+Queues a JSON-serializable message for sending. Returns a promise that resolves when the message has been written to the shared buffer.
+
+Multiple `postMessage()` calls made before the writer flushes are **batched** into a single payload and sent together. The returned promise resolves when the entire batch containing that message is fully written. This means you can fire off multiple `postMessage()` calls without awaiting — they will be coalesced efficiently.
+
+```javascript
+// Fire-and-forget (message is queued and sent asynchronously)
+port.postMessage({ action: 'save', data: [1, 2, 3] });
+
+// Or await to know when it's been written to the buffer
+await port.postMessage({ action: 'save', data: [1, 2, 3] });
+
+// Batching: these may all be sent as one payload
+port.postMessage({ a: 1 });
+port.postMessage({ b: 2 });
+port.postMessage({ c: 3 });
+```
+
+Throws if the port has been closed.
+
+### `port.onmessage`
+
+Event-driven reader. Mirrors the `MessagePort.onmessage` pattern. Setting a handler starts a continuous async read loop; setting `null` stops it.
+
+The handler receives an event object with a `data` property containing the message, matching the Web API convention: `handler({ data: message })`.
+
+```javascript
+port.onmessage = (e) => {
+  console.log(e.data); // the received message
+};
+
+// Stop listening
+port.onmessage = null;
+```
+
+**Mutual exclusion:** You cannot call `read()`, `asyncRead()`, or `tryRead()` while an `onmessage` handler is active — doing so throws an error. Set `onmessage = null` first.
+
+**Error resilience:** If the handler throws, the error is silently caught and the message loop continues. This ensures one bad message doesn't break the entire channel.
+
+**Re-assignment:** Assigning a new handler function replaces the current one immediately within the same loop — no gap in delivery and no duplicate loops.
+
+### `await port.asyncRead(timeout = Infinity, maxMessages = 1)` → message | null | Array
+
+Async read using `Atomics.waitAsync`. **Safe on the main thread.** Waits for a message or until timeout expires.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `timeout` | `Infinity` | Maximum time to wait in milliseconds. `Infinity` waits forever. |
+| `maxMessages` | `1` | Maximum number of messages to return. |
+
+**Return value depends on `maxMessages`:**
+
+- **`maxMessages = 1`** (default): Returns a single message, or `null` if timeout expired with no data.
+- **`maxMessages > 1`**: Returns an **array** of messages ordered **newest-first, oldest-last**, up to `maxMessages` items. Returns an **empty array** `[]` if timeout expired with no data. You can `pop()` from the returned array to process messages in send order (FIFO).
+
+If messages are already queued internally from a previous batch, they are returned immediately without waiting.
+
+```javascript
+const msg = await port.asyncRead();          // wait forever, returns single message
+const msg = await port.asyncRead(1000);      // wait up to 1s, returns message or null
+const msgs = await port.asyncRead(1000, 5);  // up to 5 messages, array (newest first, pop for FIFO)
+const msgs = await port.asyncRead(0, 10);    // non-blocking, returns whatever is available now
+```
+
+Throws if the port has been closed, or if `onmessage` is active.
+
+### `port.read(timeout = Infinity, blocking = true, maxMessages = 1)` → message | null | Array
+
+Synchronous read using `Atomics.wait`. **Worker threads only** — calling this on the main thread throws (`Atomics.wait` is not allowed on the main thread).
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `timeout` | `Infinity` | Maximum time to wait in milliseconds. Ignored when `blocking` is `false`. |
+| `blocking` | `true` | If `true`, blocks the thread until data arrives or timeout expires. If `false`, returns immediately. |
+| `maxMessages` | `1` | Maximum number of messages to return. |
+
+**Return value depends on `maxMessages`:**
+
+- **`maxMessages = 1`** (default): Returns a single message, or `null` if no data is available (timeout or non-blocking).
+- **`maxMessages > 1`**: Returns an **array** of messages ordered **newest-first, oldest-last**, up to `maxMessages` items. Returns an **empty array** `[]` if no data is available. You can `pop()` from the returned array to process messages in send order (FIFO).
+
+If messages are already queued internally from a previous batch, they are returned immediately without blocking.
+
+**Timeout and multipart messages:** The timeout only applies to the initial wait for a message. Once a large (multipart) message begins arriving, the read waits indefinitely for all remaining parts to ensure the message is fully received.
+
+```javascript
+const msg = port.read();                    // block forever until message
+const msg = port.read(500);                 // block up to 500ms, null on timeout
+const msg = port.read(0, false);            // non-blocking, returns null if empty
+const msgs = port.read(1000, true, 5);      // block up to 1s, up to 5 msgs (newest first, pop for FIFO)
+```
+
+Throws if the port has been closed, or if `onmessage` is active.
+
+### `port.tryRead(maxMessages = 1)` → message | null | Array
+
+Non-blocking read. Equivalent to `port.read(0, false, maxMessages)`. Returns immediately with available data.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `maxMessages` | `1` | Maximum number of messages to return. |
+
+**Return value depends on `maxMessages`:**
+
+- **`maxMessages = 1`** (default): Returns a single message, or `null`.
+- **`maxMessages > 1`**: Returns an **array** (newest-first, oldest-last), or an **empty array** `[]`. `pop()` to process in FIFO order.
+
+```javascript
+const msg = port.tryRead();       // single message or null
+const msgs = port.tryRead(10);    // up to 10 messages (array, newest first) or []
+```
+
+### `port.close()`
+
+Disposes both directions. Unblocks any waiting readers/writers by signaling disposal. After closing, all `postMessage()`, `read()`, `asyncRead()`, and `tryRead()` calls will throw. Calling `close()` multiple times is safe (subsequent calls are no-ops).
+
+### `port.buffer` → `SharedArrayBuffer`
+
+The underlying shared buffer.
+
+---
+
+## SABPipe
+
+Unidirectional channel — one end writes, the other reads. Used internally by `SABMessagePort`, but useful on its own when you only need one-way communication.
+
+All messages must be **JSON-serializable**. Message ordering is **FIFO**.
+
+### `new SABPipe(role, sabOrSize = 131072, byteOffset = 0, sectionSize = null)`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `role` | (required) | `'w'` (writer) or `'r'` (reader). Throws if invalid. |
+| `sabOrSize` | `131072` | Byte size for a new buffer (128 KB), or an existing `SharedArrayBuffer`. |
+| `byteOffset` | `0` | Starting byte offset in the SAB. |
+| `sectionSize` | `null` | Section size in bytes. Defaults to the remaining SAB from `byteOffset`. |
+
+The writer and reader must share the same `SharedArrayBuffer` (and same offset/section) to communicate. Role enforcement is strict: the writer can only call `postMessage()`, and the reader can only call `read()`/`asyncRead()`/`tryRead()`/`onmessage`. Calling the wrong method throws.
+
+```javascript
+// Writer creates the buffer
+const writer = new SABPipe('w');
+
+// Reader attaches to the same buffer
+const reader = new SABPipe('r', writer.buffer);
+```
+
+### Writer API
+
+#### `writer.postMessage(msg)` → `Promise`
+
+Queues a JSON-serializable message for sending. Returns a promise that resolves when the batch is written. Multiple calls are batched — see [`SABMessagePort.postMessage`](#portpostmessagemsg--promise) for details.
+
+```javascript
+writer.postMessage({ hello: 'world' });
+```
+
+### Reader API
+
+All read methods share the same return-value convention:
+
+- **`maxMessages = 1`** (default): returns a single message or `null`.
+- **`maxMessages > 1`**: returns an **array** of messages ordered **newest-first, oldest-last**, or an **empty array** `[]` if no data. `pop()` to process in FIFO order.
+
+#### `reader.read(timeout = Infinity, blocking = true, maxMessages = 1)`
+
+Synchronous read. **Worker threads only** (uses `Atomics.wait`).
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `timeout` | `Infinity` | Max wait time in ms. Ignored when non-blocking. |
+| `blocking` | `true` | If `false`, returns immediately without waiting. |
+| `maxMessages` | `1` | Max messages to return. |
+
+Timeout only applies to the initial wait. Multipart messages (large payloads that span multiple chunks) always wait for all parts once the first part arrives.
+
+#### `await reader.asyncRead(timeout = Infinity, maxMessages = 1)`
+
+Async read using `Atomics.waitAsync`. **Safe on the main thread.**
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `timeout` | `Infinity` | Max wait time in ms. |
+| `maxMessages` | `1` | Max messages to return. |
+
+#### `reader.tryRead(maxMessages = 1)`
+
+Non-blocking read. Equivalent to `reader.read(0, false, maxMessages)`. Returns immediately.
+
+#### `reader.onmessage`
+
+Event-driven handler. Setting a function starts a continuous async read loop; setting `null` stops it. Handler receives `{ data: message }`. See [`SABMessagePort.onmessage`](#portonmessage) for full behavior details (mutual exclusion, error resilience, re-assignment).
+
+### Shared
+
+#### `pipe.close()` / `pipe.destroy()`
+
+Disposes the channel and unblocks any waiting readers/writers. After disposal, all read/write operations throw `'SABPipe disposed'`. Safe to call multiple times.
+
+#### `pipe.isDisposed()` → `boolean`
+
+Returns `true` if the pipe has been disposed (by either side).
+
+---
+
+## Message Batching
+
+When the writer side calls `postMessage()` multiple times in quick succession (without awaiting), messages are **batched** into a single payload and sent together over the shared buffer. On the reader side, these batched messages are unpacked into an internal queue and delivered one at a time.
+
+This means a single `read()` or `asyncRead()` call may populate the internal queue with multiple messages. Subsequent reads return immediately from the queue without waiting on the shared buffer. Use `maxMessages > 1` to retrieve multiple queued messages in one call.
+
+```javascript
+// Writer side: 3 messages batched into one payload
+writer.postMessage({ id: 0 });
+writer.postMessage({ id: 1 });
+writer.postMessage({ id: 2 });
+
+// Reader side: first read waits for data, gets all 3 into the queue
+const msg0 = reader.read();   // { id: 0 } — waited for data
+const msg1 = reader.read();   // { id: 1 } — returned immediately from queue
+const msg2 = reader.read();   // { id: 2 } — returned immediately from queue
+
+// Or get all at once (newest first — pop() for FIFO)
+const msgs = reader.read(Infinity, true, 10); // [{ id: 2 }, { id: 1 }, { id: 0 }]
+msgs.pop(); // { id: 0 } — oldest
+msgs.pop(); // { id: 1 }
+msgs.pop(); // { id: 2 } — newest
+```
+
+## Large Messages & Chunking
+
+Messages larger than the buffer's data section are automatically split into chunks (multipart messages) and reassembled on the reader side. This is fully transparent — no API changes needed regardless of message size.
+
+During a multipart read, timeout is suspended: once the first chunk arrives, the reader waits indefinitely for remaining chunks to ensure the full message is received.
+
+The maximum single-chunk size is `bufferSize - 32 bytes` (32 bytes are reserved for control fields). For the default 128 KB pipe, that's ~131 KB per chunk.
+
+---
+
+## Performance
+
+Benchmarked on a single machine, Node.js worker threads, 1000 messages (~757 KB total):
+
+| Mode | Avg Latency | Throughput |
+|------|-------------|------------|
+| Blocking read (`Atomics.wait`) | ~19 us/msg | ~39 MB/s |
+| Async read (`Atomics.waitAsync`) | ~27 us/msg | ~27 MB/s |
+
+Sustained throughput (3 second run, ~500 byte messages):
+
+| Mode | Messages/sec | Throughput |
+|------|-------------|------------|
+| Blocking read | ~59,000 msg/s | ~30 MB/s |
+| Async read | ~50,000 msg/s | ~25 MB/s |
+
+Blocking reads are faster because `Atomics.wait` wakes with lower latency than the async event loop. Use blocking reads in worker threads for maximum performance; use async reads on the main thread or when you need to interleave with other async work.
+
+## Requirements
+
+- Node.js >= 16 or any browser with `SharedArrayBuffer` support
+- `SharedArrayBuffer` requires [cross-origin isolation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements) headers in browsers
+
+## License
+
+[BSD-3-Clause](LICENSE)

package/dist/SABMessagePort.min.js

@@ -0,0 +1 @@
+var p=new TextEncoder,g=new TextDecoder,R=!1,n=R?(...u)=>console.log("[SABPipe]",...u):()=>{},l=class u{static STATUS=0;static RW_SIGNAL=1;static W_DATA_LEN=2;static NUM_PARTS=3;static PART_INDEX=4;static RESERVED_1=5;static RESERVED_2=6;static RESERVED_3=7;static CONTROL_TOP=8;static DATA_OFFSET=32;static STATUS_ACTIVE=0;static STATUS_DISPOSED=-1;static RW_CAN_WRITE=0;static RW_CAN_READ=1;constructor(t,e=131072,s=0,i=null){this._sab=typeof e=="number"?new SharedArrayBuffer(e):e;let r=i??this._sab.byteLength-s;if(this.i32=new Int32Array(this._sab,s,r>>2),this.u8=new Uint8Array(this._sab,s,r),this.maxChunk=r-u.DATA_OFFSET,t==="w")this.isWriter=!0,this.isReader=!1,this._write_queue=this._create_write_queue(),this._read_queue=null,this._payload_in_progress=null,this._writing=!1;else if(t==="r")this.isWriter=!1,this.isReader=!0,this._read_queue=[],this._write_queue=null,this._reading=!1,this._onmessage=null,this._messageLoopActive=!1;else throw new Error("Invalid role parameter: must be 'r' or 'w'");this._max_chunk=r-u.DATA_OFFSET}c=this.constructor;isDisposed(){return this.i32===null||this.i32[this.c.STATUS]===this.c.STATUS_DISPOSED}_checkDisposed(){if(this.isDisposed())throw this.i32=null,this.u8=null,this._sab=null,new Error("SABPipe disposed")}destroy(){if(this.i32!==null){for(let t=0;t<this.c.CONTROL_TOP;t++)Atomics.store(this.i32,t,this.c.STATUS_DISPOSED);for(let t=0;t<this.c.CONTROL_TOP;t++)Atomics.notify(this.i32,t,1/0);this.i32=null,this.u8=null,this._sab=null}}close(){this.destroy()}_create_write_queue(){let t,e,s=new Promise((i,r)=>{t=i,e=r});return{queue:[],finishWritePromise:s,finishWriteResolveFunc:t,finishWriteRejectFunc:e}}_json_to_chunks(t){let e=p.encode(JSON.stringify(t)),s=[],i=Math.ceil(e.length/this._max_chunk)||1;for(let r=0;r<i;r++){let h=e.subarray(r*this._max_chunk,(r+1)*this._max_chunk);s.push(h)}return s}async _asyncWrite(){if(!this.isWriter)throw new Error("Only writer can write");if(this._checkDisposed(),this._writing){n("_write: already in progress, returning");return}this._writing=!0;try{if(n("_write: waiting for can write"),await this._waitForCanWrite(),n("_write: can write now"),Atomics.load(this.i32,this.c.RW_SIGNAL)===this.c.STATUS_DISPOSED&&this._checkDisposed(),this._write_queue.queue.length===0)return;this._payload_in_progress=this._write_queue,this._payload_in_progress.chunks=this._json_to_chunks(this._payload_in_progress.queue),this._payload_in_progress.currentPart=0,this._write_queue=this._create_write_queue(),this._payload_in_progress.finishWritePromise.then(()=>{this._write_queue.queue.length>0&&this._asyncWrite().catch(()=>{})});let t=this._payload_in_progress.chunks.length;for(let s=0;s<t;s++){s>0&&(await this._waitForCanWrite(),Atomics.load(this.i32,this.c.RW_SIGNAL)===this.c.STATUS_DISPOSED&&this._checkDisposed());let i=this._payload_in_progress.chunks[s];this.u8.set(i,this.c.DATA_OFFSET),this.i32[this.c.NUM_PARTS]=t,this.i32[this.c.PART_INDEX]=s,this.i32[this.c.W_DATA_LEN]=i.length,n(`_write: signaling RW_CAN_READ, part ${s}/${t}`),Atomics.store(this.i32,this.c.RW_SIGNAL,this.c.RW_CAN_READ),Atomics.notify(this.i32,this.c.RW_SIGNAL,1)}n("_write: all parts sent, resolving promise");let e=this._payload_in_progress;this._payload_in_progress=null,e.finishWriteResolveFunc()}finally{this._writing=!1}}async _waitForCanWrite(){for(;;){let t=Atomics.load(this.i32,this.c.RW_SIGNAL);if(t===this.c.RW_CAN_WRITE)return;t===this.c.STATUS_DISPOSED&&this._checkDisposed();let e=Atomics.waitAsync(this.i32,this.c.RW_SIGNAL,t);e.async&&await e.value}}_read(t=!0,e=1/0){if(!this.isReader)throw new Error("Only reader can read");this._checkDisposed(),n(`_read: starting, blocking=${t}, timeout=${e}`);let s=[],i=1,r=!0;for(;;){let a=Atomics.load(this.i32,this.c.RW_SIGNAL);if(n(`_read: signal=${a}, RW_CAN_READ=${this.c.RW_CAN_READ}`),a===this.c.STATUS_DISPOSED&&this._checkDisposed(),a!==this.c.RW_CAN_READ){if(!t)return n("_read: non-blocking, no data"),!1;let A=r?e:1/0;n(`_read: entering Atomics.wait, signal=${a}, timeout=${A}`);let w=Atomics.wait(this.i32,this.c.RW_SIGNAL,a,A);if(n(`_read: Atomics.wait returned ${w}`),w==="timed-out")return n("_read: timed out"),!1;let f=Atomics.load(this.i32,this.c.RW_SIGNAL);if(n(`_read: after wake, newSignal=${f}`),f===this.c.STATUS_DISPOSED&&this._checkDisposed(),f!==this.c.RW_CAN_READ){n("_read: spurious wakeup, retrying");continue}}let o=this.i32[this.c.W_DATA_LEN];i=this.i32[this.c.NUM_PARTS];let _=this.i32[this.c.PART_INDEX],d=this.u8.slice(this.c.DATA_OFFSET,this.c.DATA_OFFSET+o);if(s.push(d),n(`_read: got part ${_}/${i}, len=${o}, signaling RW_CAN_WRITE`),Atomics.store(this.i32,this.c.RW_SIGNAL,this.c.RW_CAN_WRITE),Atomics.notify(this.i32,this.c.RW_SIGNAL,1),r=!1,_>=i-1){n("_read: last part received");break}}let h;if(s.length===1)h=s[0];else{let a=s.reduce((_,d)=>_+d.length,0);h=new Uint8Array(a);let o=0;for(let _ of s)h.set(_,o),o+=_.length}let c=JSON.parse(g.decode(h));return c.reverse(),this._read_queue=c.concat(this._read_queue),!0}async _waitForCanRead(t=1/0){let e=t===1/0?1/0:Date.now()+t;for(;;){let s=Atomics.load(this.i32,this.c.RW_SIGNAL);if(s===this.c.RW_CAN_READ)return!0;s===this.c.STATUS_DISPOSED&&this._checkDisposed();let i=e===1/0?1/0:Math.max(0,e-Date.now());if(i===0)return!1;let r=Atomics.waitAsync(this.i32,this.c.RW_SIGNAL,s);if(r.async){if(i===1/0)await r.value;else if(await Promise.race([r.value,new Promise(c=>setTimeout(()=>c("timed-out"),i))])==="timed-out")return!1}}}async _asyncRead(t=1/0){if(!this.isReader)throw new Error("Only reader can read");if(this._checkDisposed(),this._reading)return n("_asyncRead: already in progress, returning"),!1;this._reading=!0;try{n(`_asyncRead: starting, timeout=${t}`);let e=[],s=!0;for(;;){let h=s?t:1/0;if(n(`_asyncRead: waiting for can read, timeout=${h}`),!await this._waitForCanRead(h))return n("_asyncRead: timed out or no data"),!1;Atomics.load(this.i32,this.c.RW_SIGNAL)===this.c.STATUS_DISPOSED&&this._checkDisposed();let a=this.i32[this.c.W_DATA_LEN],o=this.i32[this.c.NUM_PARTS],_=this.i32[this.c.PART_INDEX],d=this.u8.slice(this.c.DATA_OFFSET,this.c.DATA_OFFSET+a);if(e.push(d),n(`_asyncRead: got part ${_}/${o}, len=${a}, signaling RW_CAN_WRITE`),Atomics.store(this.i32,this.c.RW_SIGNAL,this.c.RW_CAN_WRITE),Atomics.notify(this.i32,this.c.RW_SIGNAL,1),s=!1,_>=o-1){n("_asyncRead: last part received");break}}let i;if(e.length===1)i=e[0];else{let h=e.reduce((a,o)=>a+o.length,0);i=new Uint8Array(h);let c=0;for(let a of e)i.set(a,c),c+=a.length}let r=JSON.parse(g.decode(i));return r.reverse(),this._read_queue=r.concat(this._read_queue),!0}finally{this._reading=!1}}postMessage(t){if(!this.isWriter)throw new Error("Only writer can write");this._checkDisposed(),this._write_queue.queue.push(t);let e=this._write_queue.finishWritePromise;return this._asyncWrite().catch(()=>{}),e}read(t=1/0,e=!0,s=1){if(!this.isReader)throw new Error("Only reader can read");if(this._onmessage!==null)throw new Error("Cannot call read while onmessage is active");return this._checkDisposed(),this._read_queue.length>0?this._popMessages(s):(this._read(e,t),this._popMessages(s))}tryRead(t=1){return this.read(0,!1,t)}async asyncRead(t=1/0,e=1){if(!this.isReader)throw new Error("Only reader can read");if(this._onmessage!==null)throw new Error("Cannot call asyncRead while onmessage is active");return this._checkDisposed(),this._read_queue.length>0?this._popMessages(e):(await this._asyncRead(t),this._popMessages(e))}set onmessage(t){if(!this.isReader)throw new Error("Only reader can set onmessage");this._onmessage=t??null,t!==null&&!this._messageLoopActive&&this._messageLoop()}get onmessage(){return this._onmessage}async _messageLoop(){if(!this._messageLoopActive){this._messageLoopActive=!0;try{for(;this._onmessage!==null;){for(;this._read_queue.length>0&&this._onmessage!==null;){let t=this._read_queue.pop();try{this._onmessage({data:t})}catch{}}if(this._onmessage===null)break;await this._asyncRead()}}catch{}finally{this._messageLoopActive=!1}}}_popMessages(t){if(t===1)return this._read_queue.length>0?this._read_queue.pop():null;{let e=Math.min(t,this._read_queue.length);return e===0?[]:this._read_queue.splice(-e)}}},y=class u{constructor(t="a",e=256){if(t!=="a"&&t!=="b")throw new Error("side must be 'a' or 'b'");this._sab=typeof e=="number"?new SharedArrayBuffer(e*1024):e;let s=this._sab.byteLength/2;t==="a"?(this._writer=new l("w",this._sab,0,s),this._reader=new l("r",this._sab,s,s)):(this._reader=new l("r",this._sab,0,s),this._writer=new l("w",this._sab,s,s))}static from(t){if(t?.type!=="SABMessagePort")throw new Error("Not a SABMessagePort init message");return new u("b",t.buffer)}postInit(t=null,e={}){let s=[{type:"SABMessagePort",buffer:this._sab,...e},[this._sab]];if(t===null)return s;t.postMessage(...s)}postMessage(t){return this._writer.postMessage(t)}set onmessage(t){this._reader.onmessage=t}get onmessage(){return this._reader.onmessage}asyncRead(t,e){return this._reader.asyncRead(t,e)}read(t,e,s){return this._reader.read(t,e,s)}tryRead(t){return this._reader.tryRead(t)}close(){this._writer.destroy(),this._reader.destroy()}get buffer(){return this._sab}};export{y as SABMessagePort,l as SABPipe};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "sab-message-port",
+  "version": "1.0.0",
+  "description": "Worker IPC over SharedArrayBuffer — blocking reads without the event loop",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/SABMessagePort.min.js",
+      "default": "./dist/SABMessagePort.min.js"
+    },
+    "./src": "./src/SABMessagePort.js"
+  },
+  "main": "./dist/SABMessagePort.min.js",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "esbuild src/SABMessagePort.js --bundle --format=esm --minify --outfile=dist/SABMessagePort.min.js",
+    "test": "node test/test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "sharedarraybuffer",
+    "atomics",
+    "worker",
+    "ipc",
+    "messageport",
+    "zero-copy",
+    "blocking",
+    "web-worker",
+    "worker-threads",
+    "shared-memory"
+  ],
+  "author": "Shlomi Loubaton",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shlomil/sab-message-port.git"
+  },
+  "homepage": "https://github.com/shlomil/sab-message-port#readme",
+  "bugs": {
+    "url": "https://github.com/shlomil/sab-message-port/issues"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.3"
+  }
+}

package/src/SABMessagePort.js

@@ -0,0 +1,802 @@
+/**
+ * SABPipe — High-level SharedArrayBuffer communication channel.
+ *
+ * Unified layout for all Lobo SABs (rpc_sab, evt_sab, dbg_sab):
+ *
+ *   Byte offset   Int32 index   Field
+ *   ───────────────────────────────────────────────────────────────
+ *   0             0             status             (STATUS_ACTIVE=0, STATUS_DISPOSED=0xFFFFFFFF)
+ *   4             1             rw_signal          (0=RW_CAN_WRITE (IDLE state, empty buffer), 1=RW_CAN_READ, STATUS_DISPOSED=0xFFFFFFFF)
+ *   8             2             w_data_len         (0=no new data, else length of data)
+ *   12            3             num_parts          (for multipart messages, total number of parts; 1 for single-part)
+ *   16            4             part_index
+ *   20            5             reserved1
+ *   24            6             reserved2
+ *   28            7             reserved3
+ *   32..131071    —             data (JSON payload)
+ *
+ *  RW protocol:
+ *
+ *  Terms:
+ *    - use the terms "read"/"write" for external API.
+ *    - fresh-write = new message (not in the middle of multipart session) - previous write was single or last part of multipart session
+ *    - fresh-read = not in the middle of multipart read session - previous read was single or last part of multipart session
+ *
+ *  Writer low level _asyncWrite():
+ *  - check role isWriter, check sab is not disposed, throw if so
+ *  - The payload to write is the entire write_queue:
+ *  - writer has access to write_queue { queue, finishWritePromise , finishWriteResolveFunc, finishWriteRejectFunc }
+ *  - No timeouts, all code is async
+ *  - _payload_in_progress = null is initialized in the class constructor for the use of this function.
+ *  - Writer writes data (non-blocking, all actions with async):
+ *              1. if _payload_in_progress != null then return immediately (without awaiting)
+ *              2. waitAsync for rw_signal=0 (RW_CAN_WRITE) if needed
+ *              3. if rw_signal=STATUS_DISPOSED, throw error
+ *              4. if write_queue is empty, return immediately (nothing to write)
+ *              5. if fresh-write then
+ *                 - move write_queue to _payload_in_progress, break it to parts and create new empty write_queue
+ *                 - chain the writing of payloads
+ *                   _payload_in_progress.finishWritePromise.then(() => {if _write_queue.queue.length > 0) _asyncWrite()})
+ *                   so that next payload is written immediately after current one finishes
+ *              6. else: select next part of _payload_in_progress to be written
+ *              7. write data  (JSON stringified payload or parts of it)
+ *              8. num_parts=1 (1 for single or >1 for multipart)
+ *              9. part_index  (0..num_parts-1 for multipart, always 0 for single part)
+ *              10. w_data_len  (length of data, written to data field)
+ *              11. rw_signal=1 (W_CAN_READ)
+ *              12. notify rw_signal
+ *  -           13. if multipart: - writer can now wait (waitAsync only) for rw_signal=0 (RW_CAN_WRITE) before writing next part.
+ *                               - go to step 2 for next part until all parts written
+ *              14. tmp = _payload_in_progress
+ *              15. _payload_in_progress = null
+ *              16. resolve tmp.finishWritePromise resolve only after payload is cleared so new _write invocation
+ *                  don't chain the current payload anymore
+ *
+ *  Reader: (low level _read or _tryRead):
+ *  - Reader reads data (try Read or blocking Read):
+ *              1. wait for rw_signal=1 (RW_CAN_READ) or just check value and continue for non-blocking
+ *              2. if rw_signal=STATUS_DISPOSED, throw error
+ *              3. read w_data_len to get length of data
+ *              4. read data (JSON string) and parse
+ *              5. read num_parts and part_index for multipart handling - message reconstruction if needed
+ *              6. set rw_signal=0 (RW_CAN_WRITE) to indicate buffer is consumed and ready for next message
+ *              7. notify rw_signal
+ *              8. if multipart and part_index<num_parts-1, goto [step 1] and repeat for next part until all parts read
+ *              9. if multipart, after last part is read reconstruct full payload
+ *              10. parse the payload , reverse it, append the current read_queue to it and set it as the new read_queue.
+ * - Timeout Support: in blocking-read, reader can specify timeout for waiting on rw_signal in [step 1] iff not in the
+ *                    middle of multipart session (e.g. previous read was a single part or last part in a multipart
+ *                    session). During multipart session, reader waits indefinitely for each part to ensure full message
+ *                    is received.
+ *
+ *
+ *
+ * Reader/Writer Disposal: The dispose() method will set rw_signal to STATUS_DISPOSED and notify all waiters, ensuring that they are
+ *             unblocked and can check the disposed state.
+ *             After being woken up from waitAsync or wait, reader or writer should check if rw_signal
+ *             is STATUS_DISPOSED and throw error if so. This ensures that any thread waiting for a message or
+ *             waiting for buffer availability will be properly notified of disposal and can handle it gracefully.
+ *
+ * Higher level buffered/Queues read/write methods:
+ *
+ *
+ * async postMessage(jsonMessage) :
+ *    // write a single message
+ *  - queue (push) the jsonMessage into write_queue
+ *  - call low level _asyncWrite() to write the entire queue without await (so main thread can call postMessage multiple times without awaiting)
+ *  - return write_queue.finishWritePromise that resolves when the message is fully sent
+ *
+ *
+ * read(timeout, blocking = true, max_num_messages=1) -> jsonMessage:
+ *    // reads (pop) a single message from read queue, or multiple messages if available and requested, up to max_num_messages
+ *    // if blocking is false, timeout is ignored and method returns immediately with available messages up to max_num_messages or null if no messages available
+ *    // if max_num_messages!=1 returns an array of messages, or empty array if no messages available,
+ *    //   otherwise returns a single message or null if no messages available
+ *    // the read_queue is ordered newest first, poping from the end of the array returns the oldest message.
+ *    // if array is returned, it should take a slice off the end of the read_queue up to max_num_messages and return it, removing those messages from the read_queue
+ *  - if there are messages in read_queue, return the next max_num_messages immediately (non-blocking)
+ *  - else in not blocking and rw_signal=RW_CAN_READ call _read() to read the message and return the first max_num_messages messages in the read_queue
+ *  - else if blocking call _read(timeout) to read the messages and return the first max_num_messages message in the read_queue
+ *
+ * Implementation notes:
+ *  - private methods and values are prefixed with _ to indicate they are not part of the public API.
+ *  - if possible, avoid exposing word indices and bit flags in the public API, use higher level abstractions instead.
+ * 
+ */
+
+
+const _encoder = new TextEncoder();
+const _decoder = new TextDecoder();
+
+// Debug logging - set to true to enable
+const MYLOG_ON = false;
+const mylog = MYLOG_ON ? (...args) => console.log('[SABPipe]', ...args) : () => {};
+
+
+
+
+// ════════════════════════════════════════════════════════════════
+// SABPipe — Core channel implementation
+// ════════════════════════════════════════════════════════════════
+
+export class SABPipe {
+
+
+  static STATUS = 0;
+  static RW_SIGNAL = 1;
+  static W_DATA_LEN = 2;
+  static NUM_PARTS = 3;
+  static PART_INDEX = 4;
+  static RESERVED_1 = 5;
+  static RESERVED_2 = 6;
+  static RESERVED_3 = 7;
+  static CONTROL_TOP = 8; // number of Int32 control fields (status, flags, metadata)
+  static DATA_OFFSET = 8 * 4; // byte offset where data starts (after control fields)
+
+  static STATUS_ACTIVE = 0;
+  static STATUS_DISPOSED = -1;  // 0xFFFFFFFF as signed int32
+
+  static RW_CAN_WRITE = 0;
+  static RW_CAN_READ = 1;
+
+
+  constructor(role, sabOrSize = 131072, byteOffset = 0, sectionSize = null) {  // 128 KB default
+    this._sab = typeof sabOrSize === 'number'
+        ? new SharedArrayBuffer(sabOrSize)
+        : sabOrSize;
+    const size = sectionSize ?? (this._sab.byteLength - byteOffset);
+    this.i32 = new Int32Array(this._sab, byteOffset, size >> 2);
+    this.u8 = new Uint8Array(this._sab, byteOffset, size);
+    this.maxChunk = size - SABPipe.DATA_OFFSET;
+    if (role === 'w') {
+      this.isWriter = true;
+      this.isReader = false;
+      this._write_queue = this._create_write_queue();
+      this._read_queue = null;
+      this._payload_in_progress = null;
+      this._writing = false;
+    } else if (role === 'r') {
+      this.isWriter = false;
+      this.isReader = true;
+      this._read_queue = [];
+      this._write_queue = null;
+      this._reading = false;
+      this._onmessage = null;
+      this._messageLoopActive = false;
+    } else throw new Error("Invalid role parameter: must be 'r' or 'w'");
+    this._max_chunk = size - SABPipe.DATA_OFFSET;
+  }
+
+  c = this.constructor; // for easier access to static fields
+
+  isDisposed() {
+    return this.i32 === null || this.i32[this.c.STATUS] === this.c.STATUS_DISPOSED;
+  }
+
+  _checkDisposed() {
+    if (this.isDisposed()) {
+      this.i32 = null;
+      this.u8 = null;
+      this._sab = null;
+      throw new Error('SABPipe disposed');
+    }
+  }
+
+  destroy() {
+    if (this.i32 === null) return; // already destroyed
+
+    //wake every possible waiting thread (reader or writer) to unblock them on dispose
+    for (let i = 0; i < this.c.CONTROL_TOP; i++) {
+      Atomics.store(this.i32, i, this.c.STATUS_DISPOSED);
+    }
+
+    for (let i = 0; i < this.c.CONTROL_TOP; i++) {
+      Atomics.notify(this.i32, i, Infinity);
+    }
+    this.i32 = null;
+    this.u8 = null;
+    this._sab = null;
+  }
+
+  close() {
+    this.destroy();
+  }
+
+  _create_write_queue() {
+    let resolveFunc, rejectFunc;
+    const finishWritePromise = new Promise((resolve, reject) => {
+      resolveFunc = resolve;
+      rejectFunc = reject;
+    });
+    return { queue: [], finishWritePromise, finishWriteResolveFunc: resolveFunc, finishWriteRejectFunc: rejectFunc };
+  }
+
+  _json_to_chunks(payload) {
+    const bytes = _encoder.encode(JSON.stringify(payload));
+    let chunks = [];
+    const numParts = Math.ceil(bytes.length / this._max_chunk) || 1;
+    for (let i = 0; i < numParts; i++) {
+      const chunk = bytes.subarray(i * this._max_chunk, (i + 1) * this._max_chunk);
+      chunks.push(chunk);
+    }
+    return chunks;
+  }
+
+
+  /**
+   * Low-level write implementation. Sends entire write_queue as a single payload.
+   * Non-blocking (uses waitAsync only).
+   */
+  async _asyncWrite() {
+    if (!this.isWriter) throw new Error('Only writer can write');
+    this._checkDisposed();
+
+    // Step 1: If already writing, return immediately (chaining handles continuation)
+    if (this._writing) {
+      mylog('_write: already in progress, returning');
+      return;
+    }
+    this._writing = true;
+
+    try {
+      // Step 2: Wait for buffer to be available
+      mylog('_write: waiting for can write');
+      await this._waitForCanWrite();
+      mylog('_write: can write now');
+
+      // Step 3: Check disposed after waking
+      if (Atomics.load(this.i32, this.c.RW_SIGNAL) === this.c.STATUS_DISPOSED) {
+        this._checkDisposed();
+      }
+
+      // Step 4: If queue is empty, nothing to write
+      if (this._write_queue.queue.length === 0) {
+        return;
+      }
+
+      // Step 5: Fresh write - move queue to _payload_in_progress
+      this._payload_in_progress = this._write_queue;
+      this._payload_in_progress.chunks = this._json_to_chunks(this._payload_in_progress.queue);
+      this._payload_in_progress.currentPart = 0;
+
+      // Create new write_queue for incoming messages during send
+      this._write_queue = this._create_write_queue();
+
+      // Chain: when this payload finishes, send next batch if any
+      this._payload_in_progress.finishWritePromise.then(() => {
+        if (this._write_queue.queue.length > 0) {
+          this._asyncWrite().catch(() => {}); // catch to prevent unhandled rejection on disposal
+        }
+      });
+
+      // Send all parts
+      const numParts = this._payload_in_progress.chunks.length;
+
+      for (let partIndex = 0; partIndex < numParts; partIndex++) {
+        // For parts after the first, wait for reader to consume previous part
+        if (partIndex > 0) {
+          await this._waitForCanWrite();
+
+          // Check disposed after waking
+          if (Atomics.load(this.i32, this.c.RW_SIGNAL) === this.c.STATUS_DISPOSED) {
+            this._checkDisposed();
+          }
+        }
+
+        // Step 7: Write data chunk
+        const chunk = this._payload_in_progress.chunks[partIndex];
+        this.u8.set(chunk, this.c.DATA_OFFSET);
+
+        // Steps 8-10: Write metadata (regular writes - faster than Atomics)
+        this.i32[this.c.NUM_PARTS] = numParts;
+        this.i32[this.c.PART_INDEX] = partIndex;
+        this.i32[this.c.W_DATA_LEN] = chunk.length;
+
+        // Steps 11-12: Signal reader and notify
+        // Atomics.store provides release semantics - ensures all above writes are visible
+        mylog(`_write: signaling RW_CAN_READ, part ${partIndex}/${numParts}`);
+        Atomics.store(this.i32, this.c.RW_SIGNAL, this.c.RW_CAN_READ);
+        Atomics.notify(this.i32, this.c.RW_SIGNAL, 1);
+      }
+
+      // Steps 14-16: Clear payload and resolve promise
+      mylog('_write: all parts sent, resolving promise');
+      const tmp = this._payload_in_progress;
+      this._payload_in_progress = null;
+      tmp.finishWriteResolveFunc();
+    } finally {
+      this._writing = false;
+    }
+  }
+
+  /**
+   * Wait for rw_signal to become RW_CAN_WRITE (0).
+   * Uses Atomics.waitAsync for non-blocking async wait.
+   */
+  async _waitForCanWrite() {
+    while (true) {
+      const signal = Atomics.load(this.i32, this.c.RW_SIGNAL);
+
+      if (signal === this.c.RW_CAN_WRITE) {
+        return; // Buffer is available
+      }
+
+      if (signal === this.c.STATUS_DISPOSED) {
+        this._checkDisposed();
+      }
+
+      // Wait for signal to change
+      const result = Atomics.waitAsync(this.i32, this.c.RW_SIGNAL, signal);
+      if (result.async) {
+        await result.value;
+      }
+    }
+  }
+
+  /**
+   * Low-level read implementation. Reads from SAB and populates read_queue.
+   * @param {boolean} blocking - If true, uses Atomics.wait (worker thread only)
+   * @param {number} timeout - Timeout in ms (only for fresh-read, not mid-multipart)
+   * @returns {boolean} - true if data was read, false if timeout/no data (non-blocking)
+   */
+  _read(blocking = true, timeout = Infinity) {
+    if (!this.isReader) throw new Error('Only reader can read');
+    this._checkDisposed();
+
+    mylog(`_read: starting, blocking=${blocking}, timeout=${timeout}`);
+
+    const chunks = [];
+    let numParts = 1;
+    let isFirstPart = true;
+
+    // Read all parts (single loop iteration for single-part messages)
+    while (true) {
+      // Step 1: Wait for data to be available
+      const signal = Atomics.load(this.i32, this.c.RW_SIGNAL);
+      mylog(`_read: signal=${signal}, RW_CAN_READ=${this.c.RW_CAN_READ}`);
+
+      if (signal === this.c.STATUS_DISPOSED) {
+        this._checkDisposed();
+      }
+
+      if (signal !== this.c.RW_CAN_READ) {
+        if (!blocking) {
+          mylog('_read: non-blocking, no data');
+          return false;
+        }
+
+        // Blocking: wait for signal
+        // Only use timeout on first part (fresh-read)
+        const waitTimeout = isFirstPart ? timeout : Infinity;
+        mylog(`_read: entering Atomics.wait, signal=${signal}, timeout=${waitTimeout}`);
+        const result = Atomics.wait(this.i32, this.c.RW_SIGNAL, signal, waitTimeout);
+        mylog(`_read: Atomics.wait returned ${result}`);
+
+        if (result === 'timed-out') {
+          mylog('_read: timed out');
+          return false;
+        }
+
+        // Re-check after waking
+        const newSignal = Atomics.load(this.i32, this.c.RW_SIGNAL);
+        mylog(`_read: after wake, newSignal=${newSignal}`);
+        if (newSignal === this.c.STATUS_DISPOSED) {
+          this._checkDisposed();
+        }
+
+        if (newSignal !== this.c.RW_CAN_READ) {
+          mylog('_read: spurious wakeup, retrying');
+          continue; // Spurious wakeup, retry
+        }
+      }
+
+      // Steps 3-5: Read metadata (regular reads - safe after Atomics.wait acquire)
+      const dataLen = this.i32[this.c.W_DATA_LEN];
+      numParts = this.i32[this.c.NUM_PARTS];
+      const partIndex = this.i32[this.c.PART_INDEX];
+
+      // Step 4: Read data chunk (copy to avoid issues when buffer is reused)
+      const chunk = this.u8.slice(this.c.DATA_OFFSET, this.c.DATA_OFFSET + dataLen);
+      chunks.push(chunk);
+
+      // Steps 6-7: Signal writer and notify
+      // Atomics.store provides release semantics
+      mylog(`_read: got part ${partIndex}/${numParts}, len=${dataLen}, signaling RW_CAN_WRITE`);
+      Atomics.store(this.i32, this.c.RW_SIGNAL, this.c.RW_CAN_WRITE);
+      Atomics.notify(this.i32, this.c.RW_SIGNAL, 1);
+
+      isFirstPart = false;
+
+      // Step 8: Check if more parts to read
+      if (partIndex >= numParts - 1) {
+        mylog('_read: last part received');
+        break; // Last part received
+      }
+
+      // Continue loop for next part (no timeout - must complete multipart)
+    }
+
+    // Step 9: Reconstruct payload if multipart
+    let payloadBytes;
+    if (chunks.length === 1) {
+      payloadBytes = chunks[0];
+    } else {
+      // Combine all chunks
+      const totalLen = chunks.reduce((sum, c) => sum + c.length, 0);
+      payloadBytes = new Uint8Array(totalLen);
+      let offset = 0;
+      for (const chunk of chunks) {
+        payloadBytes.set(chunk, offset);
+        offset += chunk.length;
+      }
+    }
+
+    // Step 10: Parse payload, reverse, prepend to read_queue
+    const messages = JSON.parse(_decoder.decode(payloadBytes));
+
+    // messages is the queue array sent by writer
+    // Reverse so oldest is at the end (for FIFO pop)
+    messages.reverse();
+
+    // Prepend to read_queue (new messages at front, oldest at end)
+    this._read_queue = messages.concat(this._read_queue);
+
+    return true;
+  }
+
+  /**
+   * Wait for rw_signal to become RW_CAN_READ (1).
+   * Uses Atomics.waitAsync for non-blocking async wait.
+   * @param {number} timeout - Timeout in ms (Infinity = wait forever)
+   * @returns {Promise<boolean>} - true if data available, false if timed out
+   */
+  async _waitForCanRead(timeout = Infinity) {
+    const deadline = timeout === Infinity ? Infinity : Date.now() + timeout;
+    while (true) {
+      const signal = Atomics.load(this.i32, this.c.RW_SIGNAL);
+
+      if (signal === this.c.RW_CAN_READ) {
+        return true; // Data is available
+      }
+
+      if (signal === this.c.STATUS_DISPOSED) {
+        this._checkDisposed();
+      }
+
+      // Calculate remaining time for this wait iteration
+      const remaining = deadline === Infinity ? Infinity : Math.max(0, deadline - Date.now());
+      if (remaining === 0) return false; // timed out
+
+      // Wait for signal to change
+      // Note: Atomics.waitAsync's timeout doesn't keep the Node.js event loop alive,
+      // so we use Promise.race with setTimeout for finite timeouts.
+      const result = Atomics.waitAsync(this.i32, this.c.RW_SIGNAL, signal);
+      if (result.async) {
+        if (remaining === Infinity) {
+          await result.value;
+        } else {
+          const outcome = await Promise.race([
+            result.value,
+            new Promise(r => setTimeout(() => r('timed-out'), remaining))
+          ]);
+          if (outcome === 'timed-out') return false;
+        }
+      }
+      // loop: re-check signal (handles spurious wakeups and value changes)
+    }
+  }
+
+  /**
+   * Low-level async read implementation. Reads from SAB and populates read_queue.
+   * Uses waitAsync — safe for main thread. Mirrors _read() logic.
+   * @param {number} timeout - Timeout in ms (only for fresh-read, not mid-multipart)
+   * @returns {Promise<boolean>} - true if data was read, false if timeout/no data
+   */
+  async _asyncRead(timeout = Infinity) {
+    if (!this.isReader) throw new Error('Only reader can read');
+    this._checkDisposed();
+
+    // Guard: prevent concurrent async reads from interleaving
+    if (this._reading) {
+      mylog('_asyncRead: already in progress, returning');
+      return false;
+    }
+    this._reading = true;
+
+    try {
+      mylog(`_asyncRead: starting, timeout=${timeout}`);
+
+      const chunks = [];
+      let isFirstPart = true;
+
+      // Read all parts (single loop iteration for single-part messages)
+      while (true) {
+        // Step 1: Wait for data to be available
+        // Only use timeout on first part (fresh-read)
+        const waitTimeout = isFirstPart ? timeout : Infinity;
+        mylog(`_asyncRead: waiting for can read, timeout=${waitTimeout}`);
+        const ready = await this._waitForCanRead(waitTimeout);
+
+        if (!ready) {
+          mylog('_asyncRead: timed out or no data');
+          return false;
+        }
+
+        // Step 2: Check disposed after waking
+        if (Atomics.load(this.i32, this.c.RW_SIGNAL) === this.c.STATUS_DISPOSED) {
+          this._checkDisposed();
+        }
+
+        // Steps 3-5: Read metadata
+        const dataLen = this.i32[this.c.W_DATA_LEN];
+        const numParts = this.i32[this.c.NUM_PARTS];
+        const partIndex = this.i32[this.c.PART_INDEX];
+
+        // Step 6: Read data chunk (copy to avoid issues when buffer is reused)
+        const chunk = this.u8.slice(this.c.DATA_OFFSET, this.c.DATA_OFFSET + dataLen);
+        chunks.push(chunk);
+
+        // Steps 7-8: Signal writer and notify
+        mylog(`_asyncRead: got part ${partIndex}/${numParts}, len=${dataLen}, signaling RW_CAN_WRITE`);
+        Atomics.store(this.i32, this.c.RW_SIGNAL, this.c.RW_CAN_WRITE);
+        Atomics.notify(this.i32, this.c.RW_SIGNAL, 1);
+
+        isFirstPart = false;
+
+        // Step 9: Check if more parts to read
+        if (partIndex >= numParts - 1) {
+          mylog('_asyncRead: last part received');
+          break; // Last part received
+        }
+
+        // Continue loop for next part (no timeout - must complete multipart)
+      }
+
+      // Step 10: Reconstruct payload if multipart
+      let payloadBytes;
+      if (chunks.length === 1) {
+        payloadBytes = chunks[0];
+      } else {
+        const totalLen = chunks.reduce((sum, c) => sum + c.length, 0);
+        payloadBytes = new Uint8Array(totalLen);
+        let offset = 0;
+        for (const chunk of chunks) {
+          payloadBytes.set(chunk, offset);
+          offset += chunk.length;
+        }
+      }
+
+      // Step 11: Parse payload, reverse, prepend to read_queue
+      const messages = JSON.parse(_decoder.decode(payloadBytes));
+      messages.reverse();
+      this._read_queue = messages.concat(this._read_queue);
+
+      return true;
+    } finally {
+      this._reading = false;
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════════
+  // High-level API
+  // ════════════════════════════════════════════════════════════════
+
+  /**
+   * Write a message to the channel.
+   * Non-blocking - queues message and returns promise that resolves when sent.
+   * @param {*} jsonMessage - JSON-serializable message
+   * @returns {Promise} - Resolves when the message batch is fully written
+   */
+  postMessage(jsonMessage) {
+    if (!this.isWriter) throw new Error('Only writer can write');
+    this._checkDisposed();
+
+    // Push message to queue
+    this._write_queue.queue.push(jsonMessage);
+
+    // Save promise BEFORE _asyncWrite() might replace _write_queue
+    const promise = this._write_queue.finishWritePromise;
+
+    // Trigger send (no await - fire and forget; catch to prevent unhandled rejection on disposal)
+    this._asyncWrite().catch(() => {});
+
+    // Return promise that resolves when this batch is sent
+    return promise;
+  }
+
+  /**
+   * Read message(s) from the channel.
+   * @param {number} timeout - Timeout in ms (ignored if non-blocking)
+   * @param {boolean} blocking - If true, blocks until data available (worker thread only)
+   * @param {number} max_num_messages - Maximum messages to return
+   * @returns {*|null|Array} - Single message/null (max=1) or array of messages (max>1)
+   */
+  read(timeout = Infinity, blocking = true, max_num_messages = 1) {
+    if (!this.isReader) throw new Error('Only reader can read');
+    if (this._onmessage !== null) throw new Error('Cannot call read while onmessage is active');
+    this._checkDisposed();
+
+    // If queue has messages, return immediately
+    if (this._read_queue.length > 0) {
+      return this._popMessages(max_num_messages);
+    }
+
+    // Try to read from SAB
+    this._read(blocking, timeout);
+
+    // Return from queue (may be empty if timeout or no data)
+    return this._popMessages(max_num_messages);
+  }
+
+  /**
+   * Non-blocking read - returns immediately with available messages.
+   * @param {number} max_num_messages - Maximum messages to return
+   * @returns {*|null|Array} - Single message/null (max=1) or array of messages (max>1)
+   */
+  tryRead(max_num_messages = 1) {
+    return this.read(0, false, max_num_messages);
+  }
+
+  /**
+   * Async read message(s) from the channel. Main-thread safe.
+   * @param {number} timeout - Timeout in ms
+   * @param {number} max_num_messages - Maximum messages to return
+   * @returns {Promise<*|null|Array>} - Single message/null (max=1) or array of messages (max>1)
+   */
+  async asyncRead(timeout = Infinity, max_num_messages = 1) {
+    if (!this.isReader) throw new Error('Only reader can read');
+    if (this._onmessage !== null) throw new Error('Cannot call asyncRead while onmessage is active');
+    this._checkDisposed();
+
+    // If queue has messages, return immediately
+    if (this._read_queue.length > 0) {
+      return this._popMessages(max_num_messages);
+    }
+
+    // Async read from SAB
+    await this._asyncRead(timeout);
+
+    // Return from queue (may be empty if timeout or no data)
+    return this._popMessages(max_num_messages);
+  }
+
+  /**
+   * Event-driven message handler. Mirrors the Web API MessagePort.onmessage pattern.
+   * Setting a handler starts a continuous async read loop; setting null stops it.
+   * @param {Function|null} handler - handler(message) called for each received message
+   */
+  set onmessage(handler) {
+    if (!this.isReader) throw new Error('Only reader can set onmessage');
+    this._onmessage = handler ?? null;
+
+    // Start loop if handler set and loop not already running
+    if (handler !== null && !this._messageLoopActive) {
+      this._messageLoop(); // fire-and-forget (no await)
+    }
+  }
+
+  get onmessage() {
+    return this._onmessage;
+  }
+
+  /**
+   * Internal message loop. Continuously reads messages and dispatches to onmessage handler.
+   * Runs until onmessage is set to null or channel is disposed.
+   */
+  async _messageLoop() {
+    if (this._messageLoopActive) return;
+    this._messageLoopActive = true;
+
+    try {
+      while (this._onmessage !== null) {
+        // 1. Drain all queued messages first
+        while (this._read_queue.length > 0 && this._onmessage !== null) {
+          const msg = this._read_queue.pop();
+          try {
+            this._onmessage({ data: msg });
+          } catch (e) {
+            // Handler error does not break the loop
+          }
+        }
+
+        if (this._onmessage === null) break;
+
+        // 2. Wait for new data (no timeout — waits until data or disposal)
+        await this._asyncRead();
+        // _asyncRead populates _read_queue; loop drains it on next iteration
+      }
+    } catch (err) {
+      // Channel disposed — loop stops silently
+    } finally {
+      this._messageLoopActive = false;
+    }
+  }
+
+  /**
+   * Pop messages from read_queue.
+   * @param {number} max - Maximum messages to pop
+   * @returns {*|null|Array} - Single message/null (max=1) or array (max>1)
+   */
+  _popMessages(max) {
+    if (max === 1) {
+      // Return single message or null
+      return this._read_queue.length > 0 ? this._read_queue.pop() : null;
+    } else {
+      // Return array of messages (FIFO - oldest first)
+      const count = Math.min(max, this._read_queue.length);
+      if (count === 0) return [];
+      // Pop from end (oldest messages)
+      return this._read_queue.splice(-count);
+    }
+  }
+}
+
+
+// ════════════════════════════════════════════════════════════════
+// SABMessagePort — Bidirectional wrapper over two SABPipe instances
+// ════════════════════════════════════════════════════════════════
+
+export class SABMessagePort {
+
+  constructor(side = 'a', sabOrSizeKB = 256) {
+    if (side !== 'a' && side !== 'b') throw new Error("side must be 'a' or 'b'");
+
+    this._sab = (typeof sabOrSizeKB === 'number')
+      ? new SharedArrayBuffer(sabOrSizeKB * 1024)
+      : sabOrSizeKB;
+
+    const sectionSize = this._sab.byteLength / 2;
+
+    if (side === 'a') {
+      this._writer = new SABPipe('w', this._sab, 0, sectionSize);
+      this._reader = new SABPipe('r', this._sab, sectionSize, sectionSize);
+    } else {
+      this._reader = new SABPipe('r', this._sab, 0, sectionSize);
+      this._writer = new SABPipe('w', this._sab, sectionSize, sectionSize);
+    }
+  }
+
+  static from(initMsg) {
+    if (initMsg?.type !== 'SABMessagePort') {
+      throw new Error('Not a SABMessagePort init message');
+    }
+    return new SABMessagePort('b', initMsg.buffer);
+  }
+
+  postInit(target = null, extraProps = {}) {
+    const msg = [
+      { type: 'SABMessagePort', buffer: this._sab, ...extraProps },
+      [this._sab]
+    ];
+    if (target === null) return msg;
+    target.postMessage(...msg);
+  }
+
+  postMessage(jsonMessage) {
+    return this._writer.postMessage(jsonMessage);
+  }
+
+  set onmessage(handler) { this._reader.onmessage = handler; }
+  get onmessage() { return this._reader.onmessage; }
+
+  asyncRead(timeout, max_num_messages) {
+    return this._reader.asyncRead(timeout, max_num_messages);
+  }
+
+  read(timeout, blocking, max_num_messages) {
+    return this._reader.read(timeout, blocking, max_num_messages);
+  }
+
+  tryRead(max_num_messages) {
+    return this._reader.tryRead(max_num_messages);
+  }
+
+  close() {
+    this._writer.destroy();
+    this._reader.destroy();
+  }
+
+  get buffer() {
+    return this._sab;
+  }
+}