sab-message-port 1.0.0 → 1.0.2

package/README.md

@@ -17,7 +17,7 @@ npm install sab-message-port
 ```
 
 ```javascript
-import { SABMessagePort, SABPipe } from 'sab-message-port';
+import { SABMessagePort, SABPipe, MWChannel } from 'sab-message-port';
 ```
 
 ## Quick Start
@@ -285,6 +285,10 @@ const msg = port.tryRead();       // single message or null
 const msgs = port.tryRead(10);    // up to 10 messages (array, newest first) or []
 ```
 
+### `port.tryPeek()` → message | null
+
+Non-blocking peek. Returns the next message without removing it from the queue. If the queue is empty, attempts a non-blocking read from the shared buffer first. Returns `null` if no data is available.
+
 ### `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).
@@ -362,6 +366,15 @@ Async read using `Atomics.waitAsync`. **Safe on the main thread.**
 
 Non-blocking read. Equivalent to `reader.read(0, false, maxMessages)`. Returns immediately.
 
+#### `reader.tryPeek()` → message | null
+
+Non-blocking peek. Returns the next message that would be returned by `read()` or `tryRead()`, **without removing it from the queue**. If the internal queue is empty, attempts a non-blocking read from the shared buffer first. Returns `null` if no data is available.
+
+```javascript
+const msg = reader.tryPeek();   // peek at next message, or null
+const same = reader.tryRead();  // consumes the same message
+```
+
 #### `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).
@@ -378,6 +391,163 @@ Returns `true` if the pipe has been disposed (by either side).
 
 ---
 
+## MWChannel
+
+A hybrid channel that uses the best transport for each direction: **native `MessagePort`** for worker→main (faster, no SharedArrayBuffer overhead) and **SABPipe** for main→worker (enables blocking reads). The worker can also switch to receiving via `MessagePort` when blocking reads aren't needed.
+
+`SABMessagePort` uses SABPipe in both directions — which means worker→main messages pay the SABPipe serialization cost even though the worker never needs to block on outgoing messages. `MWChannel` avoids this by using native `postMessage` for the worker→main direction, where it's typically faster, while keeping SABPipe for the main→worker direction where blocking reads are the whole point.
+
+The worker can also switch between blocking (SABPipe) and non-blocking (MessagePort) receive modes at runtime for the main→worker direction.
+
+**Key design:**
+- **Worker→main:** Always uses native `MessagePort` (faster, no SABPipe overhead).
+- **Main→worker:** Uses SABPipe by default (enables `read()`/`tryRead()` on the worker). Can be switched to native `MessagePort` when blocking reads aren't needed.
+- The main thread **always receives via native `MessagePort`** and never blocks.
+
+### `new MWChannel(side, sabSizeKB = 128)`
+
+Creates a new channel.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `side` | (required) | `'m'` (main thread) or `'w'` (worker). Throws if invalid. |
+| `sabSizeKB` | `128` | SABPipe buffer size in KB. Main side only. |
+
+```javascript
+const port = new MWChannel('m');         // 128 KB SABPipe buffer
+const port = new MWChannel('m', 256);   // 256 KB SABPipe buffer
+```
+
+### `MWChannel.from(initMsg)`
+
+Creates the worker side from a received init message. The init message must have `type: 'MWChannel'`.
+
+The worker starts in **blocking mode** by default.
+
+```javascript
+self.onmessage = (e) => {
+  if (e.data.type === 'MWChannel') {
+    const port = MWChannel.from(e.data);
+    // ready — defaults to blocking mode
+  }
+};
+```
+
+### `port.postInit(target = null, extraProps = {})`
+
+Sends the SAB and a `MessagePort` to the other side. The init message contains `{ type: 'MWChannel', buffer, port, ...extraProps }`. The `MessagePort` is included in the transfer list.
+
+If `target` is `null`, returns `[msg, transferList]` for manual sending.
+
+```javascript
+// Auto-send to worker
+port.postInit(worker, { channel: 'events' });
+
+// Manual
+const [msg, transfer] = port.postInit(null);
+worker.postMessage(msg, transfer);
+```
+
+### `port.postMessage(msg)`
+
+**Main side:** Sends via SABPipe (blocking mode) or native `MessagePort` (nonblocking mode), depending on the current mode. Returns a `Promise` in blocking mode, `undefined` in nonblocking mode.
+
+**Worker side:** Always sends via native `MessagePort`. Returns `undefined`.
+
+### `port.onmessage`
+
+**Main side:** Event handler on the native `MessagePort`. Always active — the main thread never blocks. Handler receives `{ data: message }`.
+
+**Worker side:** Only available in **nonblocking mode**. Delegates to `MessagePort.onmessage`. Setting `onmessage` in blocking mode throws — use `read()`/`tryRead()` instead.
+
+### `port.read(timeout = Infinity, blocking = true, maxMessages = 1)`
+
+**Worker side, blocking mode only.** Synchronous read from the SABPipe. Same return-value convention as [`SABPipe.read()`](#readerreadtimeout--infinity-blocking--true-maxmessages--1). Throws if called on main side or in nonblocking mode.
+
+### `port.tryRead(maxMessages = 1)`
+
+**Worker side, blocking mode only.** Non-blocking read from the SABPipe. Throws if called on main side or in nonblocking mode.
+
+### `port.tryPeek()`
+
+**Worker side, blocking mode only.** Non-blocking peek from the SABPipe. Returns the next message without removing it, or `null`. Throws if called on main side or in nonblocking mode.
+
+### `port.asyncRead(timeout = Infinity, maxMessages = 1)`
+
+**Worker side, blocking mode only.** Async read from the SABPipe. Throws if called on main side or in nonblocking mode.
+
+### `port.setMode(mode)`
+
+Switches the transport mode. `mode` must be `'blocking'` or `'nonblocking'`. No-op if already in the requested mode.
+
+**Main side:** Switches the **send** transport. `'blocking'` sends via SABPipe, `'nonblocking'` sends via native `MessagePort`.
+
+**Worker side:** Switches the **receive** transport.
+
+Switching to `'blocking'`:
+1. Detaches the `onmessage` handler from the native `MessagePort`.
+2. Sets mode to `'blocking'` — `read()`/`tryRead()`/`asyncRead()` become available.
+
+Switching to `'nonblocking'`:
+1. Drains any pending messages from the SABPipe via `tryRead()`.
+2. Sets mode to `'nonblocking'` — `onmessage` becomes available.
+3. Drained messages are delivered to the `onmessage` handler when it is set.
+
+**Mode switching is not automatic** — the programmer is responsible for coordinating both sides. The typical pattern is:
+
+1. Worker sends an RPC to tell main which mode to use for sending.
+2. Main calls `port.setMode(newMode)` to switch its send transport.
+3. Worker calls `port.setMode(newMode)` to switch its receive transport.
+
+### `port.close()`
+
+Destroys the SABPipe and closes the native `MessagePort`. All subsequent operations throw.
+
+### `port.buffer` → `SharedArrayBuffer`
+
+The underlying SABPipe buffer.
+
+### MWChannel Usage Example
+
+```javascript
+// === Main thread ===
+import { MWChannel } from 'sab-message-port';
+
+const worker = new Worker('./worker.js', { type: 'module' });
+const port = new MWChannel('m');
+port.postInit(worker, { channel: 'events' });
+
+port.onmessage = (e) => { /* worker→main always arrives here */ };
+
+// Send in blocking mode (default — worker reads via SABPipe)
+port.postMessage(events);
+
+// Worker requests nonblocking mode:
+port.setMode('nonblocking');
+port.postMessage(events);  // now sent via native MessagePort
+
+// === Worker ===
+import { MWChannel } from 'sab-message-port';
+
+self.onmessage = (e) => {
+  if (e.data.type !== 'MWChannel') return;
+  const port = MWChannel.from(e.data);
+
+  // Start in blocking mode (default)
+  while (running) {
+    const events = port.read();  // blocks via SABPipe
+    for (const evt of events) handle(evt);
+  }
+
+  // Switch to nonblocking
+  port.postMessage({ cmd: 'set_mode', mode: 'nonblocking' }); // tell main
+  port.setMode('nonblocking');
+  port.onmessage = (e) => handle(e.data);
+};
+```
+
+---
+
 ## 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.
@@ -430,6 +600,36 @@ Sustained throughput (3 second run, ~500 byte messages):
 
 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.
 
+### Round-Trip Comparison
+
+Bidirectional echo test — main sends a message, worker echoes it back, repeat. 1000 round-trips, 118-byte messages. Node.js worker threads.
+
+| Configuration | Avg Latency | Messages/sec | Throughput | Relative |
+|---------------|-------------|-------------|------------|----------|
+| MWChannel (blocking worker) | ~16 µs/rt | ~63,000 msg/s | ~14 MB/s | 1.00x |
+| Native MessagePort | ~18 µs/rt | ~56,000 msg/s | ~13 MB/s | 1.15x |
+| SABMessagePort (blocking worker) | ~23 µs/rt | ~43,000 msg/s | ~10 MB/s | 1.49x |
+| SABMessagePort (async both sides) | ~26 µs/rt | ~38,000 msg/s | ~9 MB/s | 1.66x |
+
+MWChannel wins because it combines blocking `Atomics.wait` reads (low wake-up latency) with native `MessagePort` writes (zero SABPipe overhead for the worker→main direction). SABMessagePort pays the SABPipe cost in both directions.
+
+*Measured with Node.js.*
+
+### Round-Trip Comparison (Chrome)
+
+Same test, Chrome 137 with cross-origin isolation headers.
+
+| Configuration | Avg Latency | Messages/sec | Throughput | Relative |
+|---------------|-------------|-------------|------------|----------|
+| Native MessagePort | ~33 µs/rt | ~30,000 msg/s | ~6.8 MB/s | 1.00x |
+| MWChannel (blocking worker) | ~46 µs/rt | ~21,500 msg/s | ~4.9 MB/s | 1.40x |
+| SABMessagePort (blocking worker) | ~47 µs/rt | ~21,300 msg/s | ~4.8 MB/s | 1.41x |
+| SABMessagePort (async both sides) | ~66 µs/rt | ~15,100 msg/s | ~3.4 MB/s | 1.99x |
+
+In Chrome, native `MessagePort` is fastest for round-trips. MWChannel and SABMessagePort blocking are nearly identical — Chrome's `Atomics.wait` wake-up latency is higher than Node.js, reducing the advantage of blocking reads. Async SABMessagePort remains the slowest at ~2x.
+
+*Measured with Chrome.*
+
 ## Requirements
 
 - Node.js >= 16 or any browser with `SharedArrayBuffer` support

package/dist/SABMessagePort.min.js

@@ -1 +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};
+var p=new TextEncoder,y=new TextDecoder,R=!1,n=R?(...c)=>console.log("[SABPipe]",...c):()=>{},u=class c{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(e,t=131072,s=0,i=null){this._sab=typeof t=="number"?new SharedArrayBuffer(t):t;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-c.DATA_OFFSET,e==="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(e==="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-c.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 e=0;e<this.c.CONTROL_TOP;e++)Atomics.store(this.i32,e,this.c.STATUS_DISPOSED);for(let e=0;e<this.c.CONTROL_TOP;e++)Atomics.notify(this.i32,e,1/0);this.i32=null,this.u8=null,this._sab=null}}close(){this.destroy()}_create_write_queue(){let e,t,s=new Promise((i,r)=>{e=i,t=r});return{queue:[],finishWritePromise:s,finishWriteResolveFunc:e,finishWriteRejectFunc:t}}_json_to_chunks(e){let t=p.encode(JSON.stringify(e)),s=[],i=Math.ceil(t.length/this._max_chunk)||1;for(let r=0;r<i;r++){let o=t.subarray(r*this._max_chunk,(r+1)*this._max_chunk);s.push(o)}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 e=this._payload_in_progress.chunks.length;for(let s=0;s<e;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]=e,this.i32[this.c.PART_INDEX]=s,this.i32[this.c.W_DATA_LEN]=i.length,n(`_write: signaling RW_CAN_READ, part ${s}/${e}`),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 t=this._payload_in_progress;this._payload_in_progress=null,t.finishWriteResolveFunc()}finally{this._writing=!1}}async _waitForCanWrite(){for(;;){let e=Atomics.load(this.i32,this.c.RW_SIGNAL);if(e===this.c.RW_CAN_WRITE)return;e===this.c.STATUS_DISPOSED&&this._checkDisposed();let t=Atomics.waitAsync(this.i32,this.c.RW_SIGNAL,e);t.async&&await t.value}}_read(e=!0,t=1/0){if(!this.isReader)throw new Error("Only reader can read");this._checkDisposed(),n(`_read: starting, blocking=${e}, timeout=${t}`);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(!e)return n("_read: non-blocking, no data"),!1;let w=r?t:1/0;n(`_read: entering Atomics.wait, signal=${a}, timeout=${w}`);let g=Atomics.wait(this.i32,this.c.RW_SIGNAL,a,w);if(n(`_read: Atomics.wait returned ${g}`),g==="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 h=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+h);if(s.push(d),n(`_read: got part ${_}/${i}, len=${h}, 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 o;if(s.length===1)o=s[0];else{let a=s.reduce((_,d)=>_+d.length,0);o=new Uint8Array(a);let h=0;for(let _ of s)o.set(_,h),h+=_.length}let l=JSON.parse(y.decode(o));return l.reverse(),this._read_queue=l.concat(this._read_queue),!0}async _waitForCanRead(e=1/0){let t=e===1/0?1/0:Date.now()+e;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=t===1/0?1/0:Math.max(0,t-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(l=>setTimeout(()=>l("timed-out"),i))])==="timed-out")return!1}}}async _asyncRead(e=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=${e}`);let t=[],s=!0;for(;;){let o=s?e:1/0;if(n(`_asyncRead: waiting for can read, timeout=${o}`),!await this._waitForCanRead(o))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],h=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(t.push(d),n(`_asyncRead: got part ${_}/${h}, 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,_>=h-1){n("_asyncRead: last part received");break}}let i;if(t.length===1)i=t[0];else{let o=t.reduce((a,h)=>a+h.length,0);i=new Uint8Array(o);let l=0;for(let a of t)i.set(a,l),l+=a.length}let r=JSON.parse(y.decode(i));return r.reverse(),this._read_queue=r.concat(this._read_queue),!0}finally{this._reading=!1}}postMessage(e){if(!this.isWriter)throw new Error("Only writer can write");this._checkDisposed(),this._write_queue.queue.push(e);let t=this._write_queue.finishWritePromise;return this._asyncWrite().catch(()=>{}),t}read(e=1/0,t=!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(t,e),this._popMessages(s))}tryRead(e=1){return this.read(0,!1,e)}tryPeek(){if(!this.isReader)throw new Error("Only reader can peek");if(this._onmessage!==null)throw new Error("Cannot call tryPeek while onmessage is active");return this._checkDisposed(),this._read_queue.length===0&&this._read(!1,0),this._read_queue.length>0?this._read_queue[this._read_queue.length-1]:null}async asyncRead(e=1/0,t=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(t):(await this._asyncRead(e),this._popMessages(t))}set onmessage(e){if(!this.isReader)throw new Error("Only reader can set onmessage");this._onmessage=e??null,e!==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 e=this._read_queue.pop();try{this._onmessage({data:e})}catch{}}if(this._onmessage===null)break;await this._asyncRead()}}catch{}finally{this._messageLoopActive=!1}}}_popMessages(e){if(e===1)return this._read_queue.length>0?this._read_queue.pop():null;{let t=Math.min(e,this._read_queue.length);return t===0?[]:this._read_queue.splice(-t)}}},m=class c{constructor(e="a",t=256){if(e!=="a"&&e!=="b")throw new Error("side must be 'a' or 'b'");this._sab=typeof t=="number"?new SharedArrayBuffer(t*1024):t;let s=this._sab.byteLength/2;e==="a"?(this._writer=new u("w",this._sab,0,s),this._reader=new u("r",this._sab,s,s)):(this._reader=new u("r",this._sab,0,s),this._writer=new u("w",this._sab,s,s))}static from(e){if(e?.type!=="SABMessagePort")throw new Error("Not a SABMessagePort init message");return new c("b",e.buffer)}postInit(e=null,t={}){let s=[{type:"SABMessagePort",buffer:this._sab,...t},[this._sab]];if(e===null)return s;e.postMessage(...s)}postMessage(e){return this._writer.postMessage(e)}set onmessage(e){this._reader.onmessage=e}get onmessage(){return this._reader.onmessage}asyncRead(e,t){return this._reader.asyncRead(e,t)}read(e,t,s){return this._reader.read(e,t,s)}tryRead(e){return this._reader.tryRead(e)}tryPeek(){return this._reader.tryPeek()}close(){this._writer.destroy(),this._reader.destroy()}get buffer(){return this._sab}},A=class c{constructor(e,t=128){if(e!=="m"&&e!=="w")throw new Error("side must be 'm' or 'w'");this._side=e,this._mode="blocking",this._onmessage=null,this._pendingDrain=[],e==="m"&&(this._sab=new SharedArrayBuffer(t*1024),this._channel=new MessageChannel,this._nativePort=this._channel.port1,this._sabWriter=new u("w",this._sab))}static from(e){if(e?.type!=="MWChannel")throw new Error("Not a MWChannel init message");let t=new c("w");return t._sab=e.buffer,t._nativePort=e.port,t._sabReader=new u("r",t._sab),t._nativePort.start(),t}postInit(e=null,t={}){if(this._side!=="m")throw new Error("postInit is only for main side");let s=this._channel.port2,i={type:"MWChannel",buffer:this._sab,port:s,...t},r=[s];if(e===null)return[i,r];e.postMessage(i,r)}postMessage(e){if(this._side==="m"){if(this._mode==="blocking")return this._sabWriter.postMessage(e);this._nativePort.postMessage(e)}else this._nativePort.postMessage(e)}set onmessage(e){if(this._side==="m")this._onmessage=e,this._nativePort.onmessage=e;else{if(this._mode==="blocking")throw new Error("Cannot set onmessage in blocking mode \u2014 use read()/tryRead()");if(this._onmessage=e,e&&this._pendingDrain.length>0){let t=this._pendingDrain;this._pendingDrain=[];for(let s of t)try{e({data:s})}catch{}}this._nativePort.onmessage=e}}get onmessage(){return this._onmessage}read(e,t,s){if(this._side!=="w")throw new Error("read() is only for worker side");if(this._mode!=="blocking")throw new Error("read() only available in blocking mode");return this._sabReader.read(e,t,s)}tryRead(e){if(this._side!=="w")throw new Error("tryRead() is only for worker side");if(this._mode!=="blocking")throw new Error("tryRead() only available in blocking mode");return this._sabReader.tryRead(e)}tryPeek(){if(this._side!=="w")throw new Error("tryPeek() is only for worker side");if(this._mode!=="blocking")throw new Error("tryPeek() only available in blocking mode");return this._sabReader.tryPeek()}asyncRead(e,t){if(this._side!=="w")throw new Error("asyncRead() is only for worker side");if(this._mode!=="blocking")throw new Error("asyncRead() only available in blocking mode");return this._sabReader.asyncRead(e,t)}setMode(e){if(e!=="blocking"&&e!=="nonblocking")throw new Error("mode must be 'blocking' or 'nonblocking'");if(this._mode!==e)if(this._side==="m")this._mode=e;else if(e==="blocking")this._nativePort.onmessage=null,this._onmessage=null,this._mode="blocking";else{let t;for(;(t=this._sabReader.tryRead())!==null;)this._pendingDrain.push(t);this._mode="nonblocking"}}close(){this._side==="m"?this._sabWriter.destroy():this._sabReader.destroy(),this._nativePort.close()}get buffer(){return this._sab}};export{A as MWChannel,m as SABMessagePort,u as SABPipe};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sab-message-port",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Worker IPC over SharedArrayBuffer — blocking reads without the event loop",
   "type": "module",
   "exports": {

package/src/SABMessagePort.js

@@ -637,6 +637,21 @@ export class SABPipe {
     return this.read(0, false, max_num_messages);
   }
 
+  /**
+   * Non-blocking peek - returns the next message without removing it from the queue.
+   * If the queue is empty, attempts a non-blocking read from the SAB first.
+   * @returns {*|null} - The next message, or null if no data available
+   */
+  tryPeek() {
+    if (!this.isReader) throw new Error('Only reader can peek');
+    if (this._onmessage !== null) throw new Error('Cannot call tryPeek while onmessage is active');
+    this._checkDisposed();
+    if (this._read_queue.length === 0) {
+      this._read(false, 0);
+    }
+    return this._read_queue.length > 0 ? this._read_queue[this._read_queue.length - 1] : null;
+  }
+
   /**
    * Async read message(s) from the channel. Main-thread safe.
    * @param {number} timeout - Timeout in ms
@@ -791,6 +806,10 @@ export class SABMessagePort {
     return this._reader.tryRead(max_num_messages);
   }
 
+  tryPeek() {
+    return this._reader.tryPeek();
+  }
+
   close() {
     this._writer.destroy();
     this._reader.destroy();
@@ -800,3 +819,197 @@ export class SABMessagePort {
     return this._sab;
   }
 }
+
+
+// ════════════════════════════════════════════════════════════════
+// MWChannel — MessagePort + SABPipe Wrapper
+//
+// Combines a native MessagePort with a SABPipe pair, allowing the
+// worker side to switch between non-blocking (MessagePort) and
+// blocking (SABPipe) receive modes at runtime.
+// Main thread always receives via MessagePort (never blocks).
+// Worker always sends via MessagePort (worker→main is always non-blocking).
+// The SABPipe is one-directional: main→worker only.
+// ════════════════════════════════════════════════════════════════
+
+export class MWChannel {
+
+  /**
+   * @param {'m'|'w'} side - 'm' (main thread) or 'w' (worker thread)
+   * @param {number} sabSizeKB - SABPipe buffer size in KB (default 128). Main side only.
+   */
+  constructor(side, sabSizeKB = 128) {
+    if (side !== 'm' && side !== 'w') throw new Error("side must be 'm' or 'w'");
+    this._side = side;
+    this._mode = 'blocking'; // default: worker starts in blocking mode
+    this._onmessage = null;
+    this._pendingDrain = [];
+
+    if (side === 'm') {
+      this._sab = new SharedArrayBuffer(sabSizeKB * 1024);
+      this._channel = new MessageChannel();
+      this._nativePort = this._channel.port1;
+      this._sabWriter = new SABPipe('w', this._sab);
+    }
+    // Worker side: _sab, _nativePort, _sabReader initialized by from()
+  }
+
+  /**
+   * Creates the worker side from a received init message.
+   * @param {object} initMsg - Must have type='MWChannel', buffer, port
+   */
+  static from(initMsg) {
+    if (initMsg?.type !== 'MWChannel') {
+      throw new Error('Not a MWChannel init message');
+    }
+    const mw = new MWChannel('w');
+    mw._sab = initMsg.buffer;
+    mw._nativePort = initMsg.port;
+    mw._sabReader = new SABPipe('r', mw._sab);
+    mw._nativePort.start();
+    return mw;
+  }
+
+  /**
+   * Sends init message containing the SAB and a MessagePort to the other side.
+   * If target is null, returns [msg, transferList] for manual sending.
+   */
+  postInit(target = null, extraProps = {}) {
+    if (this._side !== 'm') throw new Error('postInit is only for main side');
+    const port2 = this._channel.port2;
+    const msg = { type: 'MWChannel', buffer: this._sab, port: port2, ...extraProps };
+    const transfer = [port2];
+    if (target === null) return [msg, transfer];
+    target.postMessage(msg, transfer);
+  }
+
+  /**
+   * Send a message.
+   * Main: sends via SABPipe (blocking mode) or native MessagePort (nonblocking mode).
+   * Worker: always sends via native MessagePort.
+   */
+  postMessage(msg) {
+    if (this._side === 'm') {
+      if (this._mode === 'blocking') {
+        return this._sabWriter.postMessage(msg);
+      } else {
+        this._nativePort.postMessage(msg);
+      }
+    } else {
+      this._nativePort.postMessage(msg);
+    }
+  }
+
+  /**
+   * Event handler for incoming messages.
+   * Main: always delegates to native MessagePort.onmessage.
+   * Worker: only available in nonblocking mode (throws in blocking mode).
+   */
+  set onmessage(handler) {
+    if (this._side === 'm') {
+      this._onmessage = handler;
+      this._nativePort.onmessage = handler;
+    } else {
+      if (this._mode === 'blocking') {
+        throw new Error('Cannot set onmessage in blocking mode — use read()/tryRead()');
+      }
+      this._onmessage = handler;
+      // Deliver any pending drained messages from mode switch
+      if (handler && this._pendingDrain.length > 0) {
+        const pending = this._pendingDrain;
+        this._pendingDrain = [];
+        for (const msg of pending) {
+          try { handler({ data: msg }); } catch (e) { /* handler errors don't break setup */ }
+        }
+      }
+      this._nativePort.onmessage = handler;
+    }
+  }
+
+  get onmessage() {
+    return this._onmessage;
+  }
+
+  /**
+   * Blocking synchronous read from SABPipe. Worker side, blocking mode only.
+   */
+  read(timeout, blocking, max_num_messages) {
+    if (this._side !== 'w') throw new Error('read() is only for worker side');
+    if (this._mode !== 'blocking') throw new Error('read() only available in blocking mode');
+    return this._sabReader.read(timeout, blocking, max_num_messages);
+  }
+
+  /**
+   * Non-blocking read from SABPipe. Worker side, blocking mode only.
+   */
+  tryRead(max_num_messages) {
+    if (this._side !== 'w') throw new Error('tryRead() is only for worker side');
+    if (this._mode !== 'blocking') throw new Error('tryRead() only available in blocking mode');
+    return this._sabReader.tryRead(max_num_messages);
+  }
+
+  /**
+   * Non-blocking peek from SABPipe. Worker side, blocking mode only.
+   */
+  tryPeek() {
+    if (this._side !== 'w') throw new Error('tryPeek() is only for worker side');
+    if (this._mode !== 'blocking') throw new Error('tryPeek() only available in blocking mode');
+    return this._sabReader.tryPeek();
+  }
+
+  /**
+   * Async read from SABPipe. Worker side, blocking mode only.
+   */
+  asyncRead(timeout, max_num_messages) {
+    if (this._side !== 'w') throw new Error('asyncRead() is only for worker side');
+    if (this._mode !== 'blocking') throw new Error('asyncRead() only available in blocking mode');
+    return this._sabReader.asyncRead(timeout, max_num_messages);
+  }
+
+  /**
+   * Switch mode.
+   * Main: switches send transport ('blocking' = SABPipe, 'nonblocking' = native MessagePort).
+   * Worker: switches receive transport ('blocking' = SABPipe reads, 'nonblocking' = MessagePort onmessage).
+   */
+  setMode(mode) {
+    if (mode !== 'blocking' && mode !== 'nonblocking') {
+      throw new Error("mode must be 'blocking' or 'nonblocking'");
+    }
+    if (this._mode === mode) return;
+
+    if (this._side === 'm') {
+      this._mode = mode;
+    } else {
+      // Worker side
+      if (mode === 'blocking') {
+        // Switching to blocking: detach native port handler
+        this._nativePort.onmessage = null;
+        this._onmessage = null;
+        this._mode = 'blocking';
+      } else {
+        // Switching to nonblocking: drain SABPipe
+        let msg;
+        while ((msg = this._sabReader.tryRead()) !== null) {
+          this._pendingDrain.push(msg);
+        }
+        this._mode = 'nonblocking';
+      }
+    }
+  }
+
+  /**
+   * Close the channel. Destroys SABPipe and closes native MessagePort.
+   */
+  close() {
+    if (this._side === 'm') {
+      this._sabWriter.destroy();
+    } else {
+      this._sabReader.destroy();
+    }
+    this._nativePort.close();
+  }
+
+  get buffer() {
+    return this._sab;
+  }
+}