@nxtedition/shared 4.0.2 → 4.0.4

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,29 +11,30 @@ 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);
-    readSome<U>(next: (data: BufferRegion, opaque?: U) => void | boolean, opaque?: U): number;
+    constructor(sharedBuffer: SharedArrayBuffer);
+    readSome(next: (data: BufferRegion) => void | boolean): number;
+    readSome<U>(next: (data: BufferRegion, opaque: U) => void | boolean, opaque: U): number;
 }
 /**
  * Writer for the ring buffer.
  */
 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.

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)
@@ -97,7 +83,9 @@ export class Reader {
     this.#readPos = Atomics.load(this.#state, READ_INDEX) | 0
   }
 
-  readSome   (next                                                    , opaque    ) {
+                                                                
+                                                                                         
+  readSome   (next                                                    , opaque    )         {
     let count = 0
     let bytes = 0
 
@@ -183,9 +171,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')
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/shared",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -27,5 +27,5 @@
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   },
-  "gitHead": "c1c62c2a04a4f39c1450622ce6d5935e499a1128"
+  "gitHead": "6c260546e469c6cb70b5d35a20d3b0efcbf9629b"
 }