@nxtedition/shared 4.0.1 → 4.0.3

package/README.md

@@ -23,10 +23,10 @@ npm install @nxtedition/shared
 ## Usage
 
 ```js
-import { State, Reader, Writer } from '@nxtedition/shared'
+import { SharedStateBuffer, Reader, Writer } from '@nxtedition/shared'
 
-// Allocate shared memory (pass state.buffer to a worker thread)
-const state = new State(1024 * 1024) // 1 MB ring buffer
+// Allocate shared memory (pass state to a worker thread)
+const state = new SharedStateBuffer(1024 * 1024) // 1 MB ring buffer
 
 // --- Writer side (e.g. main thread) ---
 const w = new Writer(state)
@@ -87,12 +87,12 @@ if (!ok) {
 
 ```js
 // main.js
-import { State, Writer } from '@nxtedition/shared'
+import { SharedStateBuffer, Writer } from '@nxtedition/shared'
 import { Worker } from 'node:worker_threads'
 
-const state = new State(1024 * 1024)
+const state = new SharedStateBuffer(1024 * 1024)
 const worker = new Worker('./reader-worker.js', {
-  workerData: state.buffer,
+  workerData: state,
 })
 
 const w = new Writer(state)
@@ -117,20 +117,17 @@ poll()
 
 ## API
 
-### `new State(size: number)` / `new State(buffer: SharedArrayBuffer)`
+### `new SharedStateBuffer(size: number)`
 
-Allocates or wraps a shared memory buffer for the ring buffer. The first 128 bytes are reserved for state (read/write pointers); the rest is the data region.
+Extends `SharedArrayBuffer`. Allocates a shared memory buffer for the ring buffer. The first 128 bytes are reserved for state (read/write pointers); the rest is the data region. Overhead (length header + alignment + next-header slot) is added automatically so that a single write of `size` bytes is always guaranteed to fit.
 
-- **size** — Data capacity in bytes (must be a positive integer, max ~2 GB)
-- **buffer** — An existing `SharedArrayBuffer` to wrap
+- **size** — Maximum payload size in bytes for a single write (must be a positive integer, max ~2 GB)
 
-#### `state.buffer`
+Since `SharedStateBuffer` extends `SharedArrayBuffer`, pass it directly to a worker thread.
 
-The underlying `SharedArrayBuffer`. Pass this to a worker thread to share the ring buffer.
+### `new Reader(sharedBuffer: SharedArrayBuffer)`
 
-### `new Reader(state: State | SharedArrayBuffer)`
-
-Creates a reader for the ring buffer. Accepts a `State` instance or a `SharedArrayBuffer` directly (shorthand for `new Reader(new State(buf))`).
+Creates a reader for the ring buffer.
 
 #### `reader.readSome(next, opaque?)`
 
@@ -147,9 +144,9 @@ Return `false` from the callback to stop reading early. Returns the number of me
 
 Messages are batched: up to 1024 items or 256 KiB per call.
 
-### `new Writer(state: State | SharedArrayBuffer, options?)`
+### `new Writer(sharedBuffer: SharedArrayBuffer, options?)`
 
-Creates a writer for the ring buffer. Accepts a `State` instance or a `SharedArrayBuffer` directly (shorthand for `new Writer(new State(buf))`).
+Creates a writer for the ring buffer.
 
 **Options:**
 

package/lib/index.d.ts

@@ -11,21 +11,21 @@ export interface WriterOptions {
     };
 }
 /**
- * Shared ring buffer state. Allocates or wraps a SharedArrayBuffer where the
- * first 128 bytes are reserved for read/write pointers and the rest is the
- * data region.
+ * Shared ring buffer state. Extends SharedArrayBuffer where the first 128
+ * bytes are reserved for read/write pointers and the rest is the data region.
+ *
+ * The `size` parameter is the guaranteed max payload for a single write.
+ * Overhead (length header + alignment + next-header slot) is added automatically.
  */
-export declare class State {
-    readonly buffer: SharedArrayBuffer;
+export declare class SharedStateBuffer extends SharedArrayBuffer {
     constructor(size: number);
-    constructor(buffer: SharedArrayBuffer);
 }
 /**
  * Reader for the ring buffer.
  */
 export declare class Reader {
     #private;
-    constructor(state: State | SharedArrayBuffer);
+    constructor(sharedBuffer: SharedArrayBuffer);
     readSome<U>(next: (data: BufferRegion, opaque?: U) => void | boolean, opaque?: U): number;
 }
 /**
@@ -33,22 +33,25 @@ export declare class Reader {
  */
 export declare class Writer {
     #private;
-    constructor(state: State | SharedArrayBuffer, { yield: onYield, logger }?: WriterOptions);
+    constructor(sharedBuffer: SharedArrayBuffer, { yield: onYield, logger }?: WriterOptions);
     /**
      * Synchronously writes a message. Blocks (via `Atomics.wait`) until buffer space is available.
      * Writing more than "len" bytes in the callback will cause undefined behavior.
      */
-    writeSync<U>(len: number, fn: (data: BufferRegion, opaque?: U) => number, opaque?: U): void;
+    writeSync(len: number, fn: (data: BufferRegion) => number): void;
+    writeSync<U>(len: number, fn: (data: BufferRegion, opaque: U) => number, opaque: U): void;
     /**
      * Non-blocking write attempt. Returns `false` if the buffer is full.
      * Writing more than "len" bytes in the callback will cause undefined behavior.
      */
-    tryWrite<U>(len: number, fn: (data: BufferRegion, opaque?: U) => number, opaque?: U): boolean;
+    tryWrite(len: number, fn: (data: BufferRegion) => number): boolean;
+    tryWrite<U>(len: number, fn: (data: BufferRegion, opaque: U) => number, opaque: U): boolean;
     /**
      * Batches multiple writes within the callback. The write pointer is only
      * published to the reader when cork returns, reducing atomic operation overhead.
      */
-    cork<T>(callback?: () => T): T | undefined;
+    cork(): void;
+    cork<T>(callback: () => T): T;
     /**
      * Publishes the pending write position to the reader.
      */

package/lib/index.js

@@ -29,38 +29,25 @@ const HWM_COUNT = 1024 // 1024 items
  
 
 /**
- * Shared ring buffer state. Allocates or wraps a SharedArrayBuffer where the
- * first 128 bytes are reserved for read/write pointers and the rest is the
- * data region.
+ * Shared ring buffer state. Extends SharedArrayBuffer where the first 128
+ * bytes are reserved for read/write pointers and the rest is the data region.
+ *
+ * The `size` parameter is the guaranteed max payload for a single write.
+ * Overhead (length header + alignment + next-header slot) is added automatically.
  */
-export class State {
-           buffer                   
-
-                           
-                                        
-  constructor(sizeOrBuffer                            ) {
-    if (sizeOrBuffer instanceof SharedArrayBuffer) {
-      if (sizeOrBuffer.byteLength < STATE_BYTES + 8) {
-        throw new RangeError('SharedArrayBuffer too small for ring buffer state')
-      }
-      if (sizeOrBuffer.byteLength >= 2 ** 31) {
-        throw new RangeError('Shared buffer size exceeds maximum of 2GB')
-      }
-      this.buffer = sizeOrBuffer
-    } else {
-      const size = sizeOrBuffer
-      if (!Number.isInteger(size)) {
-        throw new TypeError('size must be a positive integer')
-      }
-      if (size <= 0) {
-        throw new RangeError('size must be a positive integer')
-      }
-      if (size >= 2 ** 31 - 11) {
-        throw new RangeError('size exceeds maximum of 2GB minus header size')
-      }
-      // 128 bytes for state + data region (rounded up to 4-byte boundary for Int32Array).
-      this.buffer = new SharedArrayBuffer(STATE_BYTES + ((size + 8 + 3) & ~3))
+export class SharedStateBuffer extends SharedArrayBuffer {
+  constructor(size        ) {
+    if (!Number.isInteger(size)) {
+      throw new TypeError('size must be a positive integer')
+    }
+    if (size <= 0) {
+      throw new RangeError('size must be a positive integer')
+    }
+    if (size >= 2 ** 31) {
+      throw new RangeError('size exceeds maximum of 2GB')
     }
+    // Data region: aligned payload + 4-byte length header + 4-byte next-header slot.
+    super(STATE_BYTES + ((size + 3) & ~3) + 8)
   }
 }
 
@@ -74,8 +61,7 @@ export class Reader {
   #data              
   #readPos        
 
-  constructor(state                           ) {
-    const sharedBuffer = state instanceof SharedArrayBuffer ? state : state.buffer
+  constructor(sharedBuffer                   ) {
     const size = sharedBuffer.byteLength - STATE_BYTES
 
     this.#state = new Int32Array(sharedBuffer, 0, STATE_BYTES >> 2)
@@ -183,9 +169,7 @@ export class Writer {
   #logger                                                      
   #uncorkBound            
 
-  constructor(state                           , { yield: onYield, logger }                = {}) {
-    const sharedBuffer = state instanceof SharedArrayBuffer ? state : state.buffer
-
+  constructor(sharedBuffer                   , { yield: onYield, logger }                = {}) {
     if (onYield != null && typeof onYield !== 'function') {
       throw new TypeError('onYield must be a function')
     }
@@ -384,7 +368,9 @@ export class Writer {
    * Synchronously writes a message. Blocks (via `Atomics.wait`) until buffer space is available.
    * Writing more than "len" bytes in the callback will cause undefined behavior.
    */
-  writeSync   (len        , fn                                            , opaque    ) {
+                                                                  
+                                                                                           
+  writeSync   (len        , fn                                            , opaque    )       {
     if (typeof len !== 'number') {
       throw new TypeError('"len" must be a non-negative number')
     }
@@ -438,7 +424,9 @@ export class Writer {
    * Non-blocking write attempt. Returns `false` if the buffer is full.
    * Writing more than "len" bytes in the callback will cause undefined behavior.
    */
-  tryWrite   (len        , fn                                            , opaque    ) {
+                                                                    
+                                                                                             
+  tryWrite   (len        , fn                                            , opaque    )          {
     if (typeof len !== 'number') {
       throw new TypeError('"len" must be a non-negative number')
     }
@@ -472,6 +460,8 @@ export class Writer {
    * Batches multiple writes within the callback. The write pointer is only
    * published to the reader when cork returns, reducing atomic operation overhead.
    */
+              
+                               
   cork   (callback          ) {
     this.#corked += 1
     if (callback != null) {
@@ -486,7 +476,7 @@ export class Writer {
   /**
    * Publishes the pending write position to the reader.
    */
-  uncork() {
+  uncork()       {
     if (this.#corked === 0) {
       return
     }
@@ -497,7 +487,7 @@ export class Writer {
     }
   }
 
-  flushSync() {
+  flushSync()       {
     if (this.#pending > 0) {
       Atomics.store(this.#state, WRITE_INDEX, this.#writePos)
       this.#pending = 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/shared",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -26,5 +26,6 @@
     "oxlint-tsgolint": "^0.13.0",
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
-  }
+  },
+  "gitHead": "239c3eeff1f228d4d71ff6f8c884642f359065b5"
 }