sab-message-port 1.0.2 → 1.0.3

package/README.md

@@ -289,6 +289,36 @@ const msgs = port.tryRead(10);    // up to 10 messages (array, newest first) or
 
 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.queueLimit` (getter/setter)
+
+Optional per-queue message count limit. When the queue exceeds the limit, the **oldest** messages are silently discarded. Applies to both the internal write queue and read queue.
+
+- **`null`** (default): No limit — queues grow without bound.
+- **Non-negative integer**: Maximum number of messages allowed in each queue.
+- Setting a lower limit immediately trims the existing queue.
+
+```javascript
+const port = new SABMessagePort('a', 256, 5);  // queueLimit=5 via constructor
+port.queueLimit = 10;   // change at runtime
+port.queueLimit = null;  // disable
+```
+
+The third constructor parameter (`queueLimit`) sets the initial limit. `SABMessagePort.from(initMsg, queueLimit)` also accepts it.
+
+### `port.onQueueOverflow` (getter/setter)
+
+Callback invoked **before** a queue is truncated due to exceeding its `queueLimit`. Receives the overflowing queue array by reference — the callback can inspect, log, or modify it. After the callback returns, the queue is truncated only if it still exceeds the limit.
+
+```javascript
+port.onQueueOverflow = (queue) => {
+  console.warn(`Dropping ${queue.length - port.queueLimit} messages`);
+  // Or handle manually: queue.splice(0, queue.length - port.queueLimit);
+};
+```
+
+- **`null`** (default): No callback — overflow is silently truncated.
+- Propagates to both internal SABPipe instances (writer and reader).
+
 ### `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).
@@ -305,7 +335,7 @@ Unidirectional channel — one end writes, the other reads. Used internally by `
 
 All messages must be **JSON-serializable**. Message ordering is **FIFO**.
 
-### `new SABPipe(role, sabOrSize = 131072, byteOffset = 0, sectionSize = null)`
+### `new SABPipe(role, sabOrSize = 131072, byteOffset = 0, sectionSize = null, queueLimit = null)`
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
@@ -313,6 +343,7 @@ All messages must be **JSON-serializable**. Message ordering is **FIFO**.
 | `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`. |
+| `queueLimit` | `null` | Max messages in the queue. `null` = unlimited. When exceeded, oldest messages are discarded. |
 
 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.
 
@@ -381,6 +412,14 @@ Event-driven handler. Setting a function starts a continuous async read loop; se
 
 ### Shared
 
+#### `pipe.queueLimit` (getter/setter)
+
+Optional per-queue message count limit. See [`SABMessagePort.queueLimit`](#portqueuelimit-gettersetter) for details.
+
+#### `pipe.onQueueOverflow` (getter/setter)
+
+Callback invoked before queue truncation. See [`SABMessagePort.onQueueOverflow`](#portonqueueoverflow-gettersetter) for details.
+
 #### `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.
@@ -404,7 +443,7 @@ The worker can also switch between blocking (SABPipe) and non-blocking (MessageP
 - **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)`
+### `new MWChannel(side, sabSizeKB = 128, queueLimit = null)`
 
 Creates a new channel.
 
@@ -412,13 +451,14 @@ Creates a new channel.
 |-----------|---------|-------------|
 | `side` | (required) | `'m'` (main thread) or `'w'` (worker). Throws if invalid. |
 | `sabSizeKB` | `128` | SABPipe buffer size in KB. Main side only. |
+| `queueLimit` | `null` | Max messages in the queue. `null` = unlimited. |
 
 ```javascript
 const port = new MWChannel('m');         // 128 KB SABPipe buffer
 const port = new MWChannel('m', 256);   // 256 KB SABPipe buffer
 ```
 
-### `MWChannel.from(initMsg)`
+### `MWChannel.from(initMsg, queueLimit = null)`
 
 Creates the worker side from a received init message. The init message must have `type: 'MWChannel'`.
 
@@ -499,6 +539,14 @@ Switching to `'nonblocking'`:
 2. Main calls `port.setMode(newMode)` to switch its send transport.
 3. Worker calls `port.setMode(newMode)` to switch its receive transport.
 
+### `port.queueLimit` (getter/setter)
+
+Optional per-queue message count limit. Delegates to the underlying SABPipe (`_sabWriter` on main, `_sabReader` on worker). Also enforces on the `_pendingDrain` buffer during mode switches.
+
+### `port.onQueueOverflow` (getter/setter)
+
+Callback invoked before queue truncation. Delegates to the underlying SABPipe and also fires for `_pendingDrain` overflow. See [`SABMessagePort.onQueueOverflow`](#portonqueueoverflow-gettersetter) for details.
+
 ### `port.close()`
 
 Destroys the SABPipe and closes the native `MessagePort`. All subsequent operations throw.

package/dist/SABMessagePort.min.js

@@ -1 +1 @@
-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};
+var A=new TextEncoder,m=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(e,t=131072,i=0,s=null,r=null){this._sab=typeof t=="number"?new SharedArrayBuffer(t):t;let h=s??this._sab.byteLength-i;if(this.i32=new Int32Array(this._sab,i,h>>2),this.u8=new Uint8Array(this._sab,i,h),this.maxChunk=h-u.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._queueLimit=r,this._onQueueOverflow=null,this._max_chunk=h-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 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()}get queueLimit(){return this._queueLimit}get onQueueOverflow(){return this._onQueueOverflow}set onQueueOverflow(e){this._onQueueOverflow=e??null}set queueLimit(e){if(e!==null&&(!Number.isInteger(e)||e<0))throw new Error("queueLimit must be null or a non-negative integer");this._queueLimit=e,e!==null&&(this.isWriter&&this._write_queue.queue.length>e&&(this._onQueueOverflow&&this._onQueueOverflow(this._write_queue.queue),this._write_queue.queue.length>e&&this._write_queue.queue.splice(0,this._write_queue.queue.length-e)),this.isReader&&this._read_queue&&this._read_queue.length>e&&(this._onQueueOverflow&&this._onQueueOverflow(this._read_queue),this._read_queue.length>e&&(this._read_queue.length=e)))}_enforceQueueLimit(){this._queueLimit!==null&&this._read_queue.length>this._queueLimit&&(this._onQueueOverflow&&this._onQueueOverflow(this._read_queue),this._read_queue.length>this._queueLimit&&(this._read_queue.length=this._queueLimit))}_create_write_queue(){let e,t,i=new Promise((s,r)=>{e=s,t=r});return{queue:[],finishWritePromise:i,finishWriteResolveFunc:e,finishWriteRejectFunc:t}}_json_to_chunks(e){let t=A.encode(JSON.stringify(e)),i=[],s=Math.ceil(t.length/this._max_chunk)||1;for(let r=0;r<s;r++){let h=t.subarray(r*this._max_chunk,(r+1)*this._max_chunk);i.push(h)}return i}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 i=0;i<e;i++){i>0&&(await this._waitForCanWrite(),Atomics.load(this.i32,this.c.RW_SIGNAL)===this.c.STATUS_DISPOSED&&this._checkDisposed());let s=this._payload_in_progress.chunks[i];this.u8.set(s,this.c.DATA_OFFSET),this.i32[this.c.NUM_PARTS]=e,this.i32[this.c.PART_INDEX]=i,this.i32[this.c.W_DATA_LEN]=s.length,n(`_write: signaling RW_CAN_READ, part ${i}/${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 i=[],s=1,r=!0;for(;;){let o=Atomics.load(this.i32,this.c.RW_SIGNAL);if(n(`_read: signal=${o}, RW_CAN_READ=${this.c.RW_CAN_READ}`),o===this.c.STATUS_DISPOSED&&this._checkDisposed(),o!==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=${o}, timeout=${w}`);let g=Atomics.wait(this.i32,this.c.RW_SIGNAL,o,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 a=this.i32[this.c.W_DATA_LEN];s=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+a);if(i.push(d),n(`_read: got part ${_}/${s}, 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),r=!1,_>=s-1){n("_read: last part received");break}}let h;if(i.length===1)h=i[0];else{let o=i.reduce((_,d)=>_+d.length,0);h=new Uint8Array(o);let a=0;for(let _ of i)h.set(_,a),a+=_.length}let c=JSON.parse(m.decode(h));return c.reverse(),this._read_queue=c.concat(this._read_queue),this._enforceQueueLimit(),!0}async _waitForCanRead(e=1/0){let t=e===1/0?1/0:Date.now()+e;for(;;){let i=Atomics.load(this.i32,this.c.RW_SIGNAL);if(i===this.c.RW_CAN_READ)return!0;i===this.c.STATUS_DISPOSED&&this._checkDisposed();let s=t===1/0?1/0:Math.max(0,t-Date.now());if(s===0)return!1;let r=Atomics.waitAsync(this.i32,this.c.RW_SIGNAL,i);if(r.async){if(s===1/0)await r.value;else if(await Promise.race([r.value,new Promise(c=>setTimeout(()=>c("timed-out"),s))])==="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=[],i=!0;for(;;){let h=i?e: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 o=this.i32[this.c.W_DATA_LEN],a=this.i32[this.c.NUM_PARTS],_=this.i32[this.c.PART_INDEX],d=this.u8.slice(this.c.DATA_OFFSET,this.c.DATA_OFFSET+o);if(t.push(d),n(`_asyncRead: got part ${_}/${a}, 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),i=!1,_>=a-1){n("_asyncRead: last part received");break}}let s;if(t.length===1)s=t[0];else{let h=t.reduce((o,a)=>o+a.length,0);s=new Uint8Array(h);let c=0;for(let o of t)s.set(o,c),c+=o.length}let r=JSON.parse(m.decode(s));return r.reverse(),this._read_queue=r.concat(this._read_queue),this._enforceQueueLimit(),!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),this._queueLimit!==null&&this._write_queue.queue.length>this._queueLimit&&(this._onQueueOverflow&&this._onQueueOverflow(this._write_queue.queue),this._write_queue.queue.length>this._queueLimit&&this._write_queue.queue.splice(0,this._write_queue.queue.length-this._queueLimit));let t=this._write_queue.finishWritePromise;return this._asyncWrite().catch(()=>{}),t}read(e=1/0,t=!0,i=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(i):(this._read(t,e),this._popMessages(i))}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)}}},p=class u{constructor(e="a",t=256,i=null){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 l("w",this._sab,0,s,i),this._reader=new l("r",this._sab,s,s,i)):(this._reader=new l("r",this._sab,0,s,i),this._writer=new l("w",this._sab,s,s,i))}static from(e,t=null){if(e?.type!=="SABMessagePort")throw new Error("Not a SABMessagePort init message");return new u("b",e.buffer,t)}postInit(e=null,t={}){let i=[{type:"SABMessagePort",buffer:this._sab,...t},[this._sab]];if(e===null)return i;e.postMessage(...i)}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,i){return this._reader.read(e,t,i)}tryRead(e){return this._reader.tryRead(e)}tryPeek(){return this._reader.tryPeek()}get queueLimit(){return this._writer.queueLimit}set queueLimit(e){this._writer.queueLimit=e,this._reader.queueLimit=e}get onQueueOverflow(){return this._writer.onQueueOverflow}set onQueueOverflow(e){this._writer.onQueueOverflow=e,this._reader.onQueueOverflow=e}close(){this._writer.destroy(),this._reader.destroy()}get buffer(){return this._sab}},y=class u{constructor(e,t=128,i=null){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=[],this._queueLimit=i,this._onQueueOverflow=null,e==="m"&&(this._sab=new SharedArrayBuffer(t*1024),this._channel=new MessageChannel,this._nativePort=this._channel.port1,this._sabWriter=new l("w",this._sab,void 0,void 0,i))}static from(e,t=null){if(e?.type!=="MWChannel")throw new Error("Not a MWChannel init message");let i=new u("w");return i._queueLimit=t,i._sab=e.buffer,i._nativePort=e.port,i._sabReader=new l("r",i._sab,void 0,void 0,t),i._nativePort.start(),i}postInit(e=null,t={}){if(this._side!=="m")throw new Error("postInit is only for main side");let i=this._channel.port2,s={type:"MWChannel",buffer:this._sab,port:i,...t},r=[i];if(e===null)return[s,r];e.postMessage(s,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 i of t)try{e({data:i})}catch{}}this._nativePort.onmessage=e}}get onmessage(){return this._onmessage}read(e,t,i){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,i)}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._queueLimit!==null&&this._pendingDrain.length>this._queueLimit&&(this._onQueueOverflow&&this._onQueueOverflow(this._pendingDrain),this._pendingDrain.length>this._queueLimit&&this._pendingDrain.splice(0,this._pendingDrain.length-this._queueLimit)),this._mode="nonblocking"}}get queueLimit(){return this._side==="m"?this._sabWriter.queueLimit:this._sabReader.queueLimit}set queueLimit(e){if(e!==null&&(!Number.isInteger(e)||e<0))throw new Error("queueLimit must be null or a non-negative integer");this._queueLimit=e,this._side==="m"?this._sabWriter.queueLimit=e:this._sabReader.queueLimit=e,e!==null&&this._pendingDrain.length>e&&(this._onQueueOverflow&&this._onQueueOverflow(this._pendingDrain),this._pendingDrain.length>e&&this._pendingDrain.splice(0,this._pendingDrain.length-e))}get onQueueOverflow(){return this._onQueueOverflow}set onQueueOverflow(e){this._onQueueOverflow=e??null,this._side==="m"?this._sabWriter.onQueueOverflow=e:this._sabReader&&(this._sabReader.onQueueOverflow=e)}close(){this._side==="m"?this._sabWriter.destroy():this._sabReader.destroy(),this._nativePort.close()}get buffer(){return this._sab}};export{y as MWChannel,p as SABMessagePort,l as SABPipe};

package/package.json

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

package/src/SABMessagePort.js

@@ -140,7 +140,7 @@ export class SABPipe {
   static RW_CAN_READ = 1;
 
 
-  constructor(role, sabOrSize = 131072, byteOffset = 0, sectionSize = null) {  // 128 KB default
+  constructor(role, sabOrSize = 131072, byteOffset = 0, sectionSize = null, queueLimit = null) {  // 128 KB default
     this._sab = typeof sabOrSize === 'number'
         ? new SharedArrayBuffer(sabOrSize)
         : sabOrSize;
@@ -164,6 +164,8 @@ export class SABPipe {
       this._onmessage = null;
       this._messageLoopActive = false;
     } else throw new Error("Invalid role parameter: must be 'r' or 'w'");
+    this._queueLimit = queueLimit;
+    this._onQueueOverflow = null;
     this._max_chunk = size - SABPipe.DATA_OFFSET;
   }
 
@@ -202,6 +204,48 @@ export class SABPipe {
     this.destroy();
   }
 
+  get queueLimit() {
+    return this._queueLimit;
+  }
+
+  get onQueueOverflow() {
+    return this._onQueueOverflow;
+  }
+
+  set onQueueOverflow(handler) {
+    this._onQueueOverflow = handler ?? null;
+  }
+
+  set queueLimit(value) {
+    if (value !== null && (!Number.isInteger(value) || value < 0)) {
+      throw new Error('queueLimit must be null or a non-negative integer');
+    }
+    this._queueLimit = value;
+    if (value !== null) {
+      if (this.isWriter && this._write_queue.queue.length > value) {
+        if (this._onQueueOverflow) this._onQueueOverflow(this._write_queue.queue);
+        if (this._write_queue.queue.length > value) {
+          this._write_queue.queue.splice(0, this._write_queue.queue.length - value);
+        }
+      }
+      if (this.isReader && this._read_queue && this._read_queue.length > value) {
+        if (this._onQueueOverflow) this._onQueueOverflow(this._read_queue);
+        if (this._read_queue.length > value) {
+          this._read_queue.length = value;
+        }
+      }
+    }
+  }
+
+  _enforceQueueLimit() {
+    if (this._queueLimit !== null && this._read_queue.length > this._queueLimit) {
+      if (this._onQueueOverflow) this._onQueueOverflow(this._read_queue);
+      if (this._read_queue.length > this._queueLimit) {
+        this._read_queue.length = this._queueLimit;
+      }
+    }
+  }
+
   _create_write_queue() {
     let resolveFunc, rejectFunc;
     const finishWritePromise = new Promise((resolve, reject) => {
@@ -440,6 +484,7 @@ export class SABPipe {
 
     // Prepend to read_queue (new messages at front, oldest at end)
     this._read_queue = messages.concat(this._read_queue);
+    this._enforceQueueLimit();
 
     return true;
   }
@@ -570,6 +615,7 @@ export class SABPipe {
       const messages = JSON.parse(_decoder.decode(payloadBytes));
       messages.reverse();
       this._read_queue = messages.concat(this._read_queue);
+      this._enforceQueueLimit();
 
       return true;
     } finally {
@@ -594,6 +640,14 @@ export class SABPipe {
     // Push message to queue
     this._write_queue.queue.push(jsonMessage);
 
+    // Enforce queue limit — discard oldest (front) messages
+    if (this._queueLimit !== null && this._write_queue.queue.length > this._queueLimit) {
+      if (this._onQueueOverflow) this._onQueueOverflow(this._write_queue.queue);
+      if (this._write_queue.queue.length > this._queueLimit) {
+        this._write_queue.queue.splice(0, this._write_queue.queue.length - this._queueLimit);
+      }
+    }
+
     // Save promise BEFORE _asyncWrite() might replace _write_queue
     const promise = this._write_queue.finishWritePromise;
 
@@ -753,7 +807,7 @@ export class SABPipe {
 
 export class SABMessagePort {
 
-  constructor(side = 'a', sabOrSizeKB = 256) {
+  constructor(side = 'a', sabOrSizeKB = 256, queueLimit = null) {
     if (side !== 'a' && side !== 'b') throw new Error("side must be 'a' or 'b'");
 
     this._sab = (typeof sabOrSizeKB === 'number')
@@ -763,19 +817,19 @@ export class SABMessagePort {
     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);
+      this._writer = new SABPipe('w', this._sab, 0, sectionSize, queueLimit);
+      this._reader = new SABPipe('r', this._sab, sectionSize, sectionSize, queueLimit);
     } else {
-      this._reader = new SABPipe('r', this._sab, 0, sectionSize);
-      this._writer = new SABPipe('w', this._sab, sectionSize, sectionSize);
+      this._reader = new SABPipe('r', this._sab, 0, sectionSize, queueLimit);
+      this._writer = new SABPipe('w', this._sab, sectionSize, sectionSize, queueLimit);
     }
   }
 
-  static from(initMsg) {
+  static from(initMsg, queueLimit = null) {
     if (initMsg?.type !== 'SABMessagePort') {
       throw new Error('Not a SABMessagePort init message');
     }
-    return new SABMessagePort('b', initMsg.buffer);
+    return new SABMessagePort('b', initMsg.buffer, queueLimit);
   }
 
   postInit(target = null, extraProps = {}) {
@@ -810,6 +864,24 @@ export class SABMessagePort {
     return this._reader.tryPeek();
   }
 
+  get queueLimit() {
+    return this._writer.queueLimit;
+  }
+
+  set queueLimit(value) {
+    this._writer.queueLimit = value;
+    this._reader.queueLimit = value;
+  }
+
+  get onQueueOverflow() {
+    return this._writer.onQueueOverflow;
+  }
+
+  set onQueueOverflow(handler) {
+    this._writer.onQueueOverflow = handler;
+    this._reader.onQueueOverflow = handler;
+  }
+
   close() {
     this._writer.destroy();
     this._reader.destroy();
@@ -838,18 +910,20 @@ 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) {
+  constructor(side, sabSizeKB = 128, queueLimit = null) {
     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 = [];
+    this._queueLimit = queueLimit;
+    this._onQueueOverflow = null;
 
     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);
+      this._sabWriter = new SABPipe('w', this._sab, undefined, undefined, queueLimit);
     }
     // Worker side: _sab, _nativePort, _sabReader initialized by from()
   }
@@ -858,14 +932,15 @@ export class MWChannel {
    * Creates the worker side from a received init message.
    * @param {object} initMsg - Must have type='MWChannel', buffer, port
    */
-  static from(initMsg) {
+  static from(initMsg, queueLimit = null) {
     if (initMsg?.type !== 'MWChannel') {
       throw new Error('Not a MWChannel init message');
     }
     const mw = new MWChannel('w');
+    mw._queueLimit = queueLimit;
     mw._sab = initMsg.buffer;
     mw._nativePort = initMsg.port;
-    mw._sabReader = new SABPipe('r', mw._sab);
+    mw._sabReader = new SABPipe('r', mw._sab, undefined, undefined, queueLimit);
     mw._nativePort.start();
     return mw;
   }
@@ -992,11 +1067,53 @@ export class MWChannel {
         while ((msg = this._sabReader.tryRead()) !== null) {
           this._pendingDrain.push(msg);
         }
+        if (this._queueLimit !== null && this._pendingDrain.length > this._queueLimit) {
+          if (this._onQueueOverflow) this._onQueueOverflow(this._pendingDrain);
+          if (this._pendingDrain.length > this._queueLimit) {
+            this._pendingDrain.splice(0, this._pendingDrain.length - this._queueLimit);
+          }
+        }
         this._mode = 'nonblocking';
       }
     }
   }
 
+  get queueLimit() {
+    if (this._side === 'm') return this._sabWriter.queueLimit;
+    return this._sabReader.queueLimit;
+  }
+
+  set queueLimit(value) {
+    if (value !== null && (!Number.isInteger(value) || value < 0)) {
+      throw new Error('queueLimit must be null or a non-negative integer');
+    }
+    this._queueLimit = value;
+    if (this._side === 'm') {
+      this._sabWriter.queueLimit = value;
+    } else {
+      this._sabReader.queueLimit = value;
+    }
+    if (value !== null && this._pendingDrain.length > value) {
+      if (this._onQueueOverflow) this._onQueueOverflow(this._pendingDrain);
+      if (this._pendingDrain.length > value) {
+        this._pendingDrain.splice(0, this._pendingDrain.length - value);
+      }
+    }
+  }
+
+  get onQueueOverflow() {
+    return this._onQueueOverflow;
+  }
+
+  set onQueueOverflow(handler) {
+    this._onQueueOverflow = handler ?? null;
+    if (this._side === 'm') {
+      this._sabWriter.onQueueOverflow = handler;
+    } else if (this._sabReader) {
+      this._sabReader.onQueueOverflow = handler;
+    }
+  }
+
   /**
    * Close the channel. Destroys SABPipe and closes native MessagePort.
    */