@nxtedition/shared 3.0.0 → 3.0.1

package/lib/index.js

@@ -0,0 +1,481 @@
+// By placing the read and write indices far apart (multiples of a common
+// cache line size, 64 bytes), we prevent "false sharing". This is a
+// low-level CPU optimization where two cores writing to different variables
+// that happen to be on the same cache line would otherwise constantly
+// invalidate each other's caches, hurting performance.
+// Int32 is 4 bytes, so an index of 16 means 16 * 4 = 64 bytes offset.
+const WRITE_INDEX = 0
+const READ_INDEX = 16
+
+// High-Water Mark for batching operations to reduce the frequency
+// of expensive atomic writes.
+const HWM_BYTES = 256 * 1024 // 256 KiB
+const HWM_COUNT = 1024 // 1024 items
+
+                                
+                                
+                                 
+ 
+
+                               
+                
+                
+                
+                
+                    
+                    
+ 
+
+/**
+ * Allocates the shared memory buffers.
+ */
+export function alloc(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 - 8) {
+    throw new RangeError('size exceeds maximum of 2GB minus header size')
+  }
+
+  return {
+    // A small buffer for sharing state (read/write pointers).
+    sharedState: new SharedArrayBuffer(128),
+    // The main buffer for transferring data.
+    // We need another 8 bytes for entry headers.
+    sharedBuffer: new SharedArrayBuffer(size + 8),
+  }
+}
+
+                         
+                                                                                         
+                                                                
+ 
+
+/**
+ * Creates a reader for the ring buffer.
+ */
+export function reader({ sharedState, sharedBuffer }               )         {
+  if (!(sharedState instanceof SharedArrayBuffer)) {
+    throw new TypeError('sharedState must be a SharedArrayBuffer')
+  }
+  if (!(sharedBuffer instanceof SharedArrayBuffer)) {
+    throw new TypeError('sharedBuffer must be a SharedArrayBuffer')
+  }
+  if (sharedBuffer.byteLength >= 2 ** 31) {
+    throw new RangeError('Shared buffer size exceeds maximum of 2GB')
+  }
+
+  const state = new Int32Array(sharedState)
+  const size = sharedBuffer.byteLength
+  const buffer = Buffer.from(sharedBuffer)
+  const view = new DataView(sharedBuffer)
+
+  // This object is reused to avoid creating new objects in a hot path.
+  // This helps V8 maintain a stable hidden class for the object,
+  // which is a key optimization (zero-copy read).
+  const data               = { buffer, view, offset: 0, length: 0, byteOffset: 0, byteLength: 0 }
+
+  // Local copies of the pointers. The `| 0` is a hint to the V8 JIT
+  // compiler that these are 32-bit integers, enabling optimizations.
+  let readPos = Atomics.load(state, READ_INDEX) | 0
+  let writePos = Atomics.load(state, WRITE_INDEX) | 0
+
+  function readSome   (
+    next                                                    ,
+    opaque    ,
+  )         {
+    let count = 0
+    let bytes = 0
+
+    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
+    }
+
+    // Process messages in a batch to minimize loop and atomic operation overhead.
+    while (count < HWM_COUNT && bytes < HWM_BYTES && readPos !== writePos) {
+      const dataPos = readPos + 4
+      const dataLen = view.getInt32(dataPos - 4, true) | 0
+
+      bytes += 4
+
+      // A length of -1 is a special marker indicating the writer has
+      // wrapped around to the beginning of the buffer.
+      if (dataLen === -1) {
+        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
+      } else {
+        if (dataLen < 0) {
+          throw new Error('Invalid data length')
+        }
+        if (dataPos + dataLen > size) {
+          throw new Error('Data exceeds buffer size')
+        }
+
+        readPos += 4 + dataLen
+
+        bytes += dataLen
+        count += 1
+
+        // This is a "zero-copy" operation. We don't copy the data out.
+        // Instead, we pass a "view" into the shared buffer.
+        data.offset = dataPos
+        data.byteOffset = dataPos
+        data.length = dataLen
+        data.byteLength = dataLen
+
+        if (next(data, opaque) === false) {
+          break
+        }
+      }
+    }
+
+    // IMPORTANT: The reader only updates its shared `readPos` after a batch
+    // is processed. This significantly reduces atomic operation overhead.
+    if (bytes > 0) {
+      Atomics.store(state, READ_INDEX, readPos)
+    }
+
+    return count
+  }
+
+  return { readSome }
+}
+
+                                
+                    
+                                                   
+ 
+
+                         
+                                                                    
+                                                                                             
+                                                                  
+                                                                                           
+                               
+              
+                
+                   
+ 
+
+/**
+ * Creates a writer for the ring buffer.
+ */
+export function writer(
+  { sharedState, sharedBuffer }               ,
+  { yield: onYield, logger }                = {},
+)         {
+  if (!(sharedState instanceof SharedArrayBuffer)) {
+    throw new TypeError('sharedState must be a SharedArrayBuffer')
+  }
+  if (!(sharedBuffer instanceof SharedArrayBuffer)) {
+    throw new TypeError('sharedBuffer must be a SharedArrayBuffer')
+  }
+  if (sharedBuffer.byteLength >= 2 ** 31) {
+    throw new RangeError('Shared buffer size exceeds maximum of 2GB')
+  }
+
+  const state = new Int32Array(sharedState)
+  const size = sharedBuffer.byteLength
+  const buffer = Buffer.from(sharedBuffer)
+  const view = new DataView(sharedBuffer)
+
+  // This object is reused to avoid creating new objects in a hot path.
+  // This helps V8 maintain a stable hidden class for the object,
+  // which is a key optimization (zero-copy read).
+  const data               = { buffer, view, offset: 0, length: 0, byteOffset: 0, byteLength: 0 }
+
+  // Local copies of the pointers. The `| 0` is a hint to the V8 JIT
+  // compiler that these are 32-bit integers, enabling optimizations.
+  let readPos = Atomics.load(state, READ_INDEX) | 0
+  let writePos = Atomics.load(state, WRITE_INDEX) | 0
+
+  let yielding = 0
+  let corked = 0
+  let pending = 0
+
+  if (onYield != null && typeof onYield !== 'function') {
+    throw new TypeError('onYield must be a function')
+  }
+
+  /**
+   * Pauses the writer thread to wait for the reader to catch up.
+   */
+  function _yield(delay        )       {
+    if (yielding > 128) {
+      throw new Error('Detected possible deadlock: writer yielding too many times')
+    }
+
+    // First, ensure the very latest write position is visible to the reader.
+    _flush()
+
+    if (onYield) {
+      yielding += 1
+      try {
+        // Call the user-provided yield function, if any. This can be important
+        // if the writer is waiting for the reader to process data which would
+        // otherwise deadlock.
+        onYield()
+      } finally {
+        yielding -= 1
+      }
+    }
+
+    // Atomics.wait is the most efficient way to pause. It puts the thread
+    // to sleep, consuming no CPU, until the reader changes the READ_INDEX.
+    if (delay > 0) {
+      Atomics.wait(state, READ_INDEX, 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.
+    readPos = Atomics.load(state, READ_INDEX) | 0
+  }
+
+  /**
+   * Tries to acquire enough space in the buffer for a new message.
+   */
+  function _acquire(len        )          {
+    // Total space required: payload + its 4-byte length header + a potential
+    // 4-byte header for the *next* message (for wrap-around check).
+    const required = len + 4 + 4
+
+    if (writePos >= readPos) {
+      // Case 1: The writer is ahead of the reader. [ 0 - R ... W - size ]
+      // There is free space from W to the end (s) and from 0 to R.
+
+      if (size - writePos >= required) {
+        // Enough space at the end of the buffer.
+        return true
+      }
+
+      readPos = state[READ_INDEX] | 0
+      if (readPos === 0) {
+        _yield(0)
+      }
+
+      // Not enough space at the end. Check if there's space at the beginning.
+      if (readPos === 0) {
+        // Reader is at the beginning, so no space to wrap around into.
+        return false
+      }
+
+      // Mark the current position with a wrap-around signal (-1).
+      view.setInt32(writePos, -1, true)
+
+      // Reset writer position to the beginning.
+      writePos = 0
+
+      if (writePos + 4 > size) {
+        // assertion
+        throw new Error(`Write position ${writePos} with next header exceeds buffer size ${size}`)
+      }
+      if (writePos === readPos) {
+        // assertion
+        throw new Error(`Write position ${writePos} cannot equal read position ${readPos}`)
+      }
+
+      Atomics.store(state, WRITE_INDEX, writePos)
+    }
+
+    // Case 2: The writer has wrapped around. [ 0 ... W - R ... s ]
+    // The only free space is between W and R.
+
+    readPos = state[READ_INDEX] | 0
+    if (readPos - writePos < required) {
+      _yield(0)
+    }
+
+    return readPos - writePos >= required
+  }
+
+  /**
+   * "Uncorks" the stream by publishing the pending write position.
+   * This is called from a microtask to batch atomic stores.
+   */
+  function _uncork()       {
+    corked -= 1
+    if (corked === 0) {
+      _flush()
+    }
+  }
+
+  function _flush()       {
+    if (pending > 0) {
+      Atomics.store(state, WRITE_INDEX, writePos)
+      pending = 0
+    }
+  }
+
+  /**
+   * Performs the actual write into the buffer after space has been acquired.
+   */
+  function _write   (
+    dataCap        ,
+    fn                                            ,
+    opaque    ,
+  )       {
+    const dataPos = writePos + 4
+
+    data.offset = dataPos
+    data.byteOffset = dataPos
+    data.length = dataCap
+    data.byteLength = dataCap
+
+    // The user-provided function writes the data and returns the final position.
+    // We calculate the actual bytes written from that.
+    // NOTE: This is unsafe as the user function can write beyond the reserved length.
+    const dataLen = fn(data, opaque) - dataPos
+
+    if (!Number.isFinite(dataLen)) {
+      throw new TypeError('"fn" must return the number of bytes written')
+    }
+    if (dataLen < 0) {
+      throw new RangeError(`"fn" returned a negative number ${dataLen}`)
+    }
+    if (dataLen > dataCap) {
+      throw new RangeError(`"fn" returned a number ${dataLen} that exceeds capacity ${dataCap}`)
+    }
+
+    if (dataPos + dataLen > size) {
+      // assertion
+      throw new Error(`Data position ${dataPos} with length ${dataLen} exceeds buffer size ${size}`)
+    }
+
+    const nextPos = writePos + 4 + dataLen
+
+    if (nextPos + 4 > size) {
+      // assertion
+      throw new Error(`Write position ${nextPos} with next header exceeds buffer size ${size}`)
+    }
+    if (nextPos === readPos) {
+      // assertion
+      throw new Error(`Write position ${nextPos} cannot equal read position ${readPos}`)
+    }
+
+    // Write the actual length of the data into the 4-byte header.
+    view.setInt32(writePos, dataLen, true)
+    writePos += 4 + dataLen
+    pending += 4 + dataLen
+
+    // This is the "corking" optimization. Instead of calling Atomics.store
+    // on every write, we batch them. We either write when a certain
+    // amount of data is pending (HWM_BYTES) or at the end of the current
+    // event loop tick. This drastically reduces atomic operation overhead.
+    if (pending >= HWM_BYTES) {
+      Atomics.store(state, WRITE_INDEX, writePos)
+      pending = 0
+    } else if (corked === 0) {
+      corked += 1
+      setImmediate(_uncork)
+    }
+  }
+
+  /**
+   * Public write method. Acquires space and synchronously writes data with a timeout. Will
+   * wait until space is available.
+   * Writing more than "len" bytes in the callback will cause undefined behavior.
+   */
+  function writeSync   (
+    len        ,
+    fn                                            ,
+    opaque    ,
+  )       {
+    if (typeof len !== 'number') {
+      throw new TypeError('"len" must be a non-negative number')
+    }
+    if (len < 0) {
+      throw new RangeError(`"len" ${len} is negative`)
+    }
+    if (len >= 2 ** 31 || len > size - 8) {
+      throw new Error(`"len" ${len} exceeds maximum allowed size ${size - 8}`)
+    }
+    if (typeof fn !== 'function') {
+      throw new TypeError('"fn" must be a function')
+    }
+
+    if (!_acquire(len)) {
+      const startTime = performance.now()
+      let yieldCount = 0
+      let yieldTime = 0
+      for (let n = 0; !_acquire(len); n++) {
+        if (performance.now() - startTime > 60e3) {
+          throw new Error('Timeout while waiting for space in the buffer')
+        }
+        _yield(3)
+        yieldCount += 1
+        yieldTime += 3
+      }
+      const elapsedTime = performance.now() - startTime
+      logger?.warn(
+        { yieldLength: len, readPos, writePos, elapsedTime, yieldCount, yieldTime },
+        'yielded',
+      )
+    }
+
+    _write(len, fn, opaque)
+
+    if (writePos === readPos) {
+      throw new Error(`Write position ${writePos} cannot equal read position ${readPos}`)
+    }
+  }
+
+  /**
+   * Public write method. Acquires space and tries to write data.
+   * Writing more than "len" bytes in the callback will cause undefined behavior.
+   */
+
+  function tryWrite   (
+    len        ,
+    fn                                            ,
+    opaque    ,
+  )          {
+    if (typeof len !== 'number') {
+      throw new TypeError('"len" must be a non-negative number')
+    }
+    if (len < 0) {
+      throw new RangeError(`"len" ${len} is negative`)
+    }
+    if (len >= 2 ** 31 || len > size - 8) {
+      throw new Error(`"len" ${len} exceeds maximum allowed size ${size - 8}`)
+    }
+    if (typeof fn !== 'function') {
+      throw new TypeError('"fn" must be a function')
+    }
+
+    if (!_acquire(len)) {
+      return false
+    }
+
+    _write(len, fn, opaque)
+
+    if (writePos === readPos) {
+      throw new Error(`Write position ${writePos} cannot equal read position ${readPos}`)
+    }
+
+    return true
+  }
+
+  function cork   (callback          )                {
+    corked += 1
+    if (callback != null) {
+      try {
+        return callback()
+      } finally {
+        _uncork()
+      }
+    }
+  }
+
+  return { tryWrite, writeSync, cork, uncork: _uncork, flushSync: _flush }
+}

package/package.json

@@ -1,66 +1,30 @@
 {
   "name": "@nxtedition/shared",
-  "version": "3.0.0",
-  "description": "Ring Buffer for NodeJS cross Worker communication",
-  "main": "index.js",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nxtedition/shared.git"
-  },
-  "author": "Robert Nagy <ronagy@icloud.com>",
-  "license": "MIT License",
-  "bugs": {
-    "url": "https://github.com/nxtedition/shared/issues"
-  },
+  "version": "3.0.1",
   "type": "module",
-  "homepage": "https://github.com/nxtedition/shared#readme",
-  "lint-staged": {
-    "*.{js,jsx,ts}": [
-      "eslint",
-      "prettier --write"
-    ]
-  },
-  "prettier": {
-    "printWidth": 100,
-    "semi": false,
-    "singleQuote": true,
-    "jsxSingleQuote": true
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
   },
-  "eslintConfig": {
-    "root": true,
-    "parserOptions": {
-      "ecmaFeatures": {
-        "ecmaVersion": 2020
-      }
-    },
-    "extends": [
-      "standard",
-      "prettier",
-      "prettier/prettier"
-    ],
-    "rules": {
-      "quotes": [
-        "error",
-        "single",
-        {
-          "avoidEscape": true,
-          "allowTemplateLiterals": true
-        }
-      ]
-    }
+  "scripts": {
+    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
+    "prepublishOnly": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "test:ci": "node --test"
   },
   "devDependencies": {
-    "eslint": "^8.12.0",
-    "eslint-config-prettier": "^8.4.0",
-    "eslint-config-standard": "^16.0.3",
-    "eslint-plugin-import": "^2.25.4",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^6.0.0",
-    "husky": "^7.0.4",
-    "lint-staged": "^12.3.7",
-    "prettier": "^2.6.2"
-  },
-  "scripts": {
-    "prepare": "husky install"
+    "@types/node": "^25.2.3",
+    "amaroc": "^1.0.1",
+    "oxlint-tsgolint": "^0.13.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.9.3"
   }
 }

package/.editorconfig

@@ -1,12 +0,0 @@
-root = true
-
-[*]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false

package/.husky/pre-commit

@@ -1,3 +0,0 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-npx lint-staged