@nxtedition/shared 4.0.3 → 4.0.5

package/README.md

@@ -183,7 +183,7 @@ Immediately publishes the pending write position to the reader. Unlike `uncork`,
 
 ## Benchmarks
 
-Measured on AMD EPYC 9355P (4.28 GHz), Node.js 25.6.0, 8 MiB ring buffer, Docker (x64-linux).
+Measured on AMD EPYC 9355P (4.29 GHz), Node.js 25.6.1, 8 MiB ring buffer, Docker (x64-linux).
 
 Each benchmark writes batches of fixed-size messages from the main thread and
 reads them in a worker thread. The shared ring buffer is compared against
@@ -193,38 +193,39 @@ Node.js `postMessage` (structured clone).
 
 |   Size | shared (buffer) | shared (string) | postMessage (buffer) | postMessage (string) |
 | -----: | --------------: | --------------: | -------------------: | -------------------: |
-|   64 B |   **901 MiB/s** |       410 MiB/s |             25 MiB/s |             42 MiB/s |
-|  256 B |  **2.67 GiB/s** |       896 MiB/s |             88 MiB/s |            158 MiB/s |
-|  1 KiB |  **4.88 GiB/s** |      1.26 GiB/s |            328 MiB/s |            498 MiB/s |
-|  4 KiB |  **9.22 GiB/s** |      1.50 GiB/s |           1.14 GiB/s |           1.70 GiB/s |
-| 16 KiB | **10.90 GiB/s** |      1.56 GiB/s |           4.29 GiB/s |           6.27 GiB/s |
-| 64 KiB |     13.03 GiB/s |      1.55 GiB/s |          10.10 GiB/s |      **15.18 GiB/s** |
+|   64 B |   **838 MiB/s** |       388 MiB/s |             24 MiB/s |             42 MiB/s |
+|  256 B |  **2.65 GiB/s** |      1.46 GiB/s |             89 MiB/s |            168 MiB/s |
+|  1 KiB |  **4.95 GiB/s** |      4.86 GiB/s |            339 MiB/s |            525 MiB/s |
+|  4 KiB |      8.42 GiB/s | **15.11 GiB/s** |           1.12 GiB/s |           1.86 GiB/s |
+| 16 KiB |     12.02 GiB/s | **33.27 GiB/s** |           4.12 GiB/s |           6.02 GiB/s |
+| 64 KiB |     12.96 GiB/s | **43.66 GiB/s** |           9.33 GiB/s |          14.73 GiB/s |
 
 ### Message rate
 
 |   Size | shared (buffer) | shared (string) | postMessage (buffer) | postMessage (string) |
 | -----: | --------------: | --------------: | -------------------: | -------------------: |
-|   64 B |   **14.76 M/s** |        6.72 M/s |              405 K/s |              688 K/s |
-|  256 B |   **11.20 M/s** |        3.67 M/s |              360 K/s |              648 K/s |
-|  1 KiB |    **5.12 M/s** |        1.32 M/s |              336 K/s |              510 K/s |
-|  4 KiB |    **2.42 M/s** |         394 K/s |              298 K/s |              445 K/s |
-| 16 KiB |     **714 K/s** |         102 K/s |              281 K/s |              411 K/s |
-| 64 KiB |         213 K/s |          25 K/s |              165 K/s |          **249 K/s** |
+|   64 B |   **13.73 M/s** |        6.35 M/s |              391 K/s |              693 K/s |
+|  256 B |   **11.14 M/s** |        6.14 M/s |              366 K/s |              689 K/s |
+|  1 KiB |    **5.19 M/s** |        5.09 M/s |              348 K/s |              538 K/s |
+|  4 KiB |        2.21 M/s |    **3.96 M/s** |              295 K/s |              488 K/s |
+| 16 KiB |         788 K/s |    **2.18 M/s** |              270 K/s |              395 K/s |
+| 64 KiB |         212 K/s |     **715 K/s** |              153 K/s |              241 K/s |
 
 ### Key findings
 
 - **Small messages (64–256 B):** The shared ring buffer with `Buffer.set` delivers
-  **14.8–11.2 M msg/s** — up to **36x faster** than `postMessage` (buffer) and
-  **21x faster** than `postMessage` (string). Per-message overhead dominates at
+  **13.7–11.1 M msg/s** — up to **35x faster** than `postMessage` (buffer) and
+  **20x faster** than `postMessage` (string). Per-message overhead dominates at
   these sizes, and avoiding structured cloning makes the biggest difference.
 
-- **Medium to large messages (1–16 KiB):** `Buffer.set` via the ring buffer
-  maintains its lead, reaching **10.9 GiB/s** at 16 KiB — **1.7–5.4x faster**
-  than the best `postMessage` variant.
+- **Medium messages (1 KiB):** `Buffer.set` and string are nearly identical
+  (**4.95 vs 4.86 GiB/s**), both **~9x faster** than the best `postMessage`
+  variant.
 
-- **Very large messages (64 KiB):** `postMessage` (string) overtakes the shared
-  buffer at **15.2 GiB/s** vs **13.0 GiB/s**. At this size, structured cloning
-  overhead is amortized and the kernel's optimized `memcpy` dominates.
+- **Large messages (4–64 KiB):** Shared string overtakes `Buffer.set` and
+  scales to **43.7 GiB/s** at 64 KiB — **3.4x faster** than `Buffer.set` and
+  **3.0x faster** than `postMessage` (string). At every size, the shared ring
+  buffer outperforms `postMessage`.
 
 - **Caveat:** The string benchmark uses ASCII-only content. Multi-byte UTF-8
   strings will not hit V8's vectorized fast path and will be significantly slower.

package/lib/index.d.ts

@@ -26,7 +26,8 @@ export declare class SharedStateBuffer extends SharedArrayBuffer {
 export declare class Reader {
     #private;
     constructor(sharedBuffer: SharedArrayBuffer);
-    readSome<U>(next: (data: BufferRegion, opaque?: U) => void | boolean, opaque?: U): number;
+    readSome(next: (data: BufferRegion) => void | boolean): number;
+    readSome<U>(next: (data: BufferRegion, opaque: U) => void | boolean, opaque: U): number;
 }
 /**
  * Writer for the ring buffer.

package/lib/index.js

@@ -16,6 +16,8 @@ const STATE_BYTES = 128
 const HWM_BYTES = 256 * 1024 // 256 KiB
 const HWM_COUNT = 1024 // 1024 items
 
+const isProduction = process.env.NODE_ENV === 'production'
+
                                
                 
                 
@@ -59,7 +61,6 @@ export class Reader {
   #size        
   #int32            
   #data              
-  #readPos        
 
   constructor(sharedBuffer                   ) {
     const size = sharedBuffer.byteLength - STATE_BYTES
@@ -77,13 +78,11 @@ export class Reader {
       byteOffset: 0,
       byteLength: 0,
     }
-
-    // Local copy of the pointer. The `| 0` is a hint to the V8 JIT
-    // compiler that this is a 32-bit integer, enabling optimizations.
-    this.#readPos = Atomics.load(this.#state, READ_INDEX) | 0
   }
 
-  readSome   (next                                                    , opaque    ) {
+                                                                
+                                                                                         
+  readSome   (next                                                    , opaque    )         {
     let count = 0
     let bytes = 0
 
@@ -91,14 +90,9 @@ export class Reader {
     const int32 = this.#int32
     const size = this.#size
     const data = this.#data
-    let readPos = this.#readPos
-    let writePos = state[WRITE_INDEX] | 0
 
-    // First, check if the local writePos matches the readPos.
-    // If so, refresh it from shared memory in case the writer has added data.
-    if (readPos === writePos) {
-      writePos = Atomics.load(state, WRITE_INDEX) | 0
-    }
+    let readPos = state[READ_INDEX] | 0
+    let writePos = state[WRITE_INDEX] | 0
 
     // Process messages in a batch to minimize loop and atomic operation overhead.
     while (count < HWM_COUNT && bytes < HWM_BYTES && readPos !== writePos) {
@@ -113,7 +107,7 @@ export class Reader {
         readPos = 0
         // After wrapping, we must re-check against the writer's position.
         // It's possible the writer is now at a position > 0.
-        writePos = Atomics.load(state, WRITE_INDEX) | 0
+        writePos = state[WRITE_INDEX] | 0
       } else {
         if (dataLen < 0) {
           throw new Error('Invalid data length')
@@ -140,12 +134,10 @@ export class Reader {
       }
     }
 
-    this.#readPos = readPos
-
     // IMPORTANT: The reader only updates its shared `readPos` after a batch
-    // is processed. This significantly reduces atomic operation overhead.
+    // is processed. This significantly reduces shared memory overhead.
     if (bytes > 0) {
-      Atomics.store(state, READ_INDEX, readPos)
+      state[READ_INDEX] = readPos | 0
     }
 
     return count
@@ -192,8 +184,8 @@ export class Writer {
 
     // Local copies of the pointers. The `| 0` is a hint to the V8 JIT
     // compiler that these are 32-bit integers, enabling optimizations.
-    this.#readPos = Atomics.load(this.#state, READ_INDEX) | 0
-    this.#writePos = Atomics.load(this.#state, WRITE_INDEX) | 0
+    this.#readPos = this.#state[READ_INDEX] | 0
+    this.#writePos = this.#state[WRITE_INDEX] | 0
 
     this.#yielding = 0
     this.#corked = 0
@@ -231,12 +223,11 @@ export class Writer {
     if (delay > 0) {
       Atomics.wait(this.#state, READ_INDEX, this.#readPos, delay)
     } else {
-      // @ts-expect-error Atomics.pause is Stage 3, available in Node.js 25+
       Atomics.pause()
     }
 
     // After waking up, refresh the local view of the reader's position.
-    this.#readPos = Atomics.load(this.#state, READ_INDEX) | 0
+    this.#readPos = this.#state[READ_INDEX] | 0
   }
 
   /**
@@ -260,12 +251,12 @@ export class Writer {
       }
 
       this.#readPos = state[READ_INDEX] | 0
-      if (this.#readPos === 0) {
+      if (this.#readPos < 4) {
         this.#yield(0)
       }
 
       // Not enough space at the end. Check if there's space at the beginning.
-      if (this.#readPos === 0) {
+      if (this.#readPos < 4) {
         // Reader is at the beginning, so no space to wrap around into.
         return false
       }
@@ -276,13 +267,13 @@ export class Writer {
       // Reset writer position to the beginning.
       this.#writePos = 0
 
-      if (this.#writePos + 4 > size) {
+      if (!isProduction && this.#writePos + 4 > size) {
         // assertion
         throw new Error(
           `Write position ${this.#writePos} with next header exceeds buffer size ${size}`,
         )
       }
-      if (this.#writePos === this.#readPos) {
+      if (!isProduction && this.#writePos === this.#readPos) {
         // assertion
         throw new Error(
           `Write position ${this.#writePos} cannot equal read position ${this.#readPos}`,
@@ -290,6 +281,7 @@ export class Writer {
       }
 
       Atomics.store(state, WRITE_INDEX, this.#writePos)
+      this.#pending = 0
     }
 
     // Case 2: The writer has wrapped around. [ 0 ... W - R ... s ]
@@ -329,7 +321,7 @@ export class Writer {
     }
 
     const size = this.#size
-    if (dataPos + dataLen > size) {
+    if (!isProduction && dataPos + dataLen > size) {
       // assertion
       throw new Error(`Data position ${dataPos} with length ${dataLen} exceeds buffer size ${size}`)
     }
@@ -337,11 +329,11 @@ export class Writer {
     const alignedLen = (dataLen + 3) & ~3
     const nextPos = this.#writePos + 4 + alignedLen
 
-    if (nextPos + 4 > size) {
+    if (!isProduction && nextPos + 4 > size) {
       // assertion
       throw new Error(`Write position ${nextPos} with next header exceeds buffer size ${size}`)
     }
-    if (nextPos === this.#readPos) {
+    if (!isProduction && nextPos === this.#readPos) {
       // assertion
       throw new Error(`Write position ${nextPos} cannot equal read position ${this.#readPos}`)
     }
@@ -413,7 +405,8 @@ export class Writer {
 
     this.#write(len, fn, opaque)
 
-    if (this.#writePos === this.#readPos) {
+    if (!isProduction && this.#writePos === this.#readPos) {
+      // assertion
       throw new Error(
         `Write position ${this.#writePos} cannot equal read position ${this.#readPos}`,
       )
@@ -447,7 +440,8 @@ export class Writer {
 
     this.#write(len, fn, opaque)
 
-    if (this.#writePos === this.#readPos) {
+    if (!isProduction && this.#writePos === this.#readPos) {
+      // assertion
       throw new Error(
         `Write position ${this.#writePos} cannot equal read position ${this.#readPos}`,
       )

package/lib/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

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