thread-stream 4.0.0 → 4.2.0

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tap:*)",
+      "Bash(node:*)",
+      "Bash(for i in 1 2 3 4 5)",
+      "Bash(do)",
+      "Bash(echo:*)",
+      "Bash(done)",
+      "Bash(npm test:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
       contents: read
     steps:
       - name: Check out repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
@@ -38,17 +38,17 @@ jobs:
       contents: read
     strategy:
       matrix:
-        node-version: [20, 22, 24]
+        node-version: [20, 22, 24, 26]
         os: [macos-latest, ubuntu-latest, windows-latest]
 
     steps:
       - name: Check out repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           persist-credentials: false
 
       - name: Setup Node ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
 

package/README.md

@@ -39,6 +39,8 @@ stream.flush(function () {
 })
 ```
 
+`flush(cb)` waits for the worker destination flush when supported (`flush`, `flushSync`, or pending `drain`).
+
 In `worker.js`:
 
 ```js
@@ -87,7 +89,8 @@ This module works with `yarn` in PnP (plug'n play) mode too!
 ### Emit events
 
 You can emit events on the ThreadStream from your worker using [`worker.parentPort.postMessage()`](https://nodejs.org/api/worker_threads.html#workerparentport).
-The message (JSON object) must have the following data structure:
+Messages that do not carry a thread-stream protocol `code` are ignored.
+For custom events, the message (JSON object) must have the following data structure:
 
 ```js
 parentPort.postMessage({

package/index.d.ts

@@ -59,6 +59,13 @@ declare class ThreadStream extends EventEmitter {
    * Calling the {@link write()} method after calling {@link end()} will emit an error.
    */
   end(): void
+  /**
+   * Flush the stream asynchronously.
+   *
+   * The callback is invoked once data has been consumed by the worker and the
+   * worker destination has acknowledged the flush.
+   */
+  flush(cb?: (err?: Error) => void): void
   /**
    * Flush the stream synchronously.
    * This method should be called in the shutdown phase to make sure that all data has been flushed.

package/index.js

@@ -8,16 +8,33 @@ const { pathToFileURL } = require('url')
 const { wait } = require('./lib/wait')
 const {
   WRITE_INDEX,
-  READ_INDEX
+  READ_INDEX,
+  SEQ_INDEX
 } = require('./lib/indexes')
 const buffer = require('buffer')
 const assert = require('assert')
 
 const kImpl = Symbol('kImpl')
 
-// V8 limit for string size
+// Maximum pending buffered data before forcing a synchronous drain
 const MAX_STRING = buffer.constants.MAX_STRING_LENGTH
 
+function noop () {}
+
+function updateState (stream, fn) {
+  Atomics.add(stream[kImpl].state, SEQ_INDEX, 1)
+  fn()
+  Atomics.add(stream[kImpl].state, SEQ_INDEX, 1)
+  Atomics.notify(stream[kImpl].state, SEQ_INDEX)
+}
+
+function resetIndexes (stream) {
+  updateState(stream, () => {
+    Atomics.store(stream[kImpl].state, READ_INDEX, 0)
+    Atomics.store(stream[kImpl].state, WRITE_INDEX, 0)
+  })
+}
+
 class FakeWeakRef {
   constructor (value) {
     this._value = value
@@ -54,6 +71,7 @@ function createWorker (stream, opts) {
 
   const worker = new Worker(toExecute, {
     ...opts.workerOpts,
+    name: opts.workerOpts?.name || 'thread-stream',
     trackUnmanagedFds: false,
     workerData: {
       filename: filename.indexOf('file://') === 0
@@ -90,66 +108,46 @@ function drain (stream) {
 }
 
 function nextFlush (stream) {
-  const writeIndex = Atomics.load(stream[kImpl].state, WRITE_INDEX)
-  let leftover = stream[kImpl].data.length - writeIndex
+  while (true) {
+    const writeIndex = Atomics.load(stream[kImpl].state, WRITE_INDEX)
+    const leftover = stream[kImpl].data.length - writeIndex
+
+    if (leftover > 0) {
+      if (stream[kImpl].bufLen === 0) {
+        stream[kImpl].flushing = false
 
-  if (leftover > 0) {
-    if (stream[kImpl].buf.length === 0) {
-      stream[kImpl].flushing = false
+        if (stream[kImpl].ending) {
+          end(stream)
+        } else if (stream[kImpl].needDrain) {
+          process.nextTick(drain, stream)
+        }
 
-      if (stream[kImpl].ending) {
-        end(stream)
-      } else if (stream[kImpl].needDrain) {
-        process.nextTick(drain, stream)
+        return
       }
 
-      return
+      write(stream, leftover, noop)
+      continue
     }
 
-    let toWrite = stream[kImpl].buf.slice(0, leftover)
-    let toWriteBytes = Buffer.byteLength(toWrite)
-    if (toWriteBytes <= leftover) {
-      stream[kImpl].buf = stream[kImpl].buf.slice(leftover)
-      // process._rawDebug('writing ' + toWrite.length)
-      write(stream, toWrite, nextFlush.bind(null, stream))
-    } else {
-      // multi-byte utf-8
-      stream.flush(() => {
-        // err is already handled in flush()
+    if (leftover === 0) {
+      if (writeIndex === 0 && stream[kImpl].bufLen === 0) {
+        // we had a flushSync in the meanwhile
+        return
+      }
+      waitForRead(stream, () => {
         if (stream.destroyed) {
           return
         }
 
-        Atomics.store(stream[kImpl].state, READ_INDEX, 0)
-        Atomics.store(stream[kImpl].state, WRITE_INDEX, 0)
-        Atomics.notify(stream[kImpl].state, READ_INDEX)
-
-        // Find a toWrite length that fits the buffer
-        // it must exists as the buffer is at least 4 bytes length
-        // and the max utf-8 length for a char is 4 bytes.
-        while (toWriteBytes > stream[kImpl].data.length) {
-          leftover = leftover / 2
-          toWrite = stream[kImpl].buf.slice(0, leftover)
-          toWriteBytes = Buffer.byteLength(toWrite)
-        }
-        stream[kImpl].buf = stream[kImpl].buf.slice(leftover)
-        write(stream, toWrite, nextFlush.bind(null, stream))
+        resetIndexes(stream)
+        nextFlush(stream)
       })
-    }
-  } else if (leftover === 0) {
-    if (writeIndex === 0 && stream[kImpl].buf.length === 0) {
-      // we had a flushSync in the meanwhile
       return
     }
-    stream.flush(() => {
-      Atomics.store(stream[kImpl].state, READ_INDEX, 0)
-      Atomics.store(stream[kImpl].state, WRITE_INDEX, 0)
-      Atomics.notify(stream[kImpl].state, READ_INDEX)
-      nextFlush(stream)
-    })
-  } else {
+
     // This should never happen
     destroy(stream, new Error('overwritten'))
+    return
   }
 }
 
@@ -162,13 +160,19 @@ function onWorkerMessage (msg) {
     return
   }
 
+  // Node.js watch mode may send internal worker messages that do not
+  // participate in thread-stream's worker protocol.
+  if (msg?.code == null) {
+    return
+  }
+
   switch (msg.code) {
     case 'READY':
       // Replace the FakeWeakRef with a
       // proper one.
       this.stream = new WeakRef(stream)
 
-      stream.flush(() => {
+      waitForRead(stream, () => {
         stream[kImpl].ready = true
         stream.emit('ready')
       })
@@ -183,6 +187,19 @@ function onWorkerMessage (msg) {
         stream.emit(msg.name, msg.args)
       }
       break
+    case 'FLUSHED': {
+      if (msg.context !== 'thread-stream') {
+        destroy(stream, new Error('this should not happen: ' + msg.code))
+        break
+      }
+
+      const cb = stream[kImpl].flushCallbacks.get(msg.id)
+      if (cb) {
+        stream[kImpl].flushCallbacks.delete(msg.id)
+        process.nextTick(cb)
+      }
+      break
+    }
     case 'WARNING':
       process.emitWarning(msg.err)
       break
@@ -226,7 +243,11 @@ class ThreadStream extends EventEmitter {
     this[kImpl].finished = false
     this[kImpl].errored = null
     this[kImpl].closed = false
-    this[kImpl].buf = ''
+    this[kImpl].buf = []
+    this[kImpl].bufHead = 0
+    this[kImpl].bufLen = 0
+    this[kImpl].flushCallbacks = new Map()
+    this[kImpl].nextFlushId = 0
 
     // TODO (fix): Make private?
     this.worker = createWorker(this, opts) // TODO (fix): make private
@@ -236,6 +257,7 @@ class ThreadStream extends EventEmitter {
   }
 
   write (data) {
+    const dataBuf = Buffer.isBuffer(data) ? data : Buffer.from(data)
     if (this[kImpl].destroyed) {
       error(this, new Error('the worker has exited'))
       return false
@@ -246,7 +268,7 @@ class ThreadStream extends EventEmitter {
       return false
     }
 
-    if (this[kImpl].flushing && this[kImpl].buf.length + data.length >= MAX_STRING) {
+    if (this[kImpl].flushing && this[kImpl].bufLen + dataBuf.length >= MAX_STRING) {
       try {
         writeSync(this)
         this[kImpl].flushing = true
@@ -256,7 +278,8 @@ class ThreadStream extends EventEmitter {
       }
     }
 
-    this[kImpl].buf += data
+    this[kImpl].buf.push(dataBuf)
+    this[kImpl].bufLen += dataBuf.length
 
     if (this[kImpl].sync) {
       try {
@@ -273,7 +296,7 @@ class ThreadStream extends EventEmitter {
       setImmediate(nextFlush, this)
     }
 
-    this[kImpl].needDrain = this[kImpl].data.length - this[kImpl].buf.length - Atomics.load(this[kImpl].state, WRITE_INDEX) <= 0
+    this[kImpl].needDrain = this[kImpl].data.length - this[kImpl].bufLen - Atomics.load(this[kImpl].state, WRITE_INDEX) <= 0
     return !this[kImpl].needDrain
   }
 
@@ -287,28 +310,15 @@ class ThreadStream extends EventEmitter {
   }
 
   flush (cb) {
-    if (this[kImpl].destroyed) {
-      if (typeof cb === 'function') {
-        process.nextTick(cb, new Error('the worker has exited'))
-      }
-      return
-    }
+    cb = typeof cb === 'function' ? cb : noop
 
-    // TODO write all .buf
-    const writeIndex = Atomics.load(this[kImpl].state, WRITE_INDEX)
-    // process._rawDebug(`(flush) readIndex (${Atomics.load(this.state, READ_INDEX)}) writeIndex (${Atomics.load(this.state, WRITE_INDEX)})`)
-    wait(this[kImpl].state, READ_INDEX, writeIndex, Infinity, (err, res) => {
+    flushBuffer(this, (err) => {
       if (err) {
-        destroy(this, err)
         process.nextTick(cb, err)
         return
       }
-      if (res === 'not-equal') {
-        // TODO handle deadlock
-        this.flush(cb)
-        return
-      }
-      process.nextTick(cb)
+
+      requestWorkerFlush(this, cb)
     })
   }
 
@@ -366,6 +376,93 @@ class ThreadStream extends EventEmitter {
   }
 }
 
+function flushBuffer (stream, cb) {
+  if (stream[kImpl].destroyed) {
+    process.nextTick(cb, new Error('the worker has exited'))
+    return
+  }
+
+  if (!stream[kImpl].sync && (stream[kImpl].flushing || stream[kImpl].bufLen > 0)) {
+    setImmediate(flushBuffer, stream, cb)
+    return
+  }
+
+  waitForRead(stream, cb)
+}
+
+function waitForRead (stream, cb) {
+  const writeIndex = Atomics.load(stream[kImpl].state, WRITE_INDEX)
+  wait(stream[kImpl].state, READ_INDEX, writeIndex, Infinity, (err, res) => {
+    if (err) {
+      destroy(stream, err)
+      cb(err)
+      return
+    }
+
+    if (res !== 'ok') {
+      waitForRead(stream, cb)
+      return
+    }
+
+    cb()
+  })
+}
+
+function requestWorkerFlush (stream, cb) {
+  if (stream[kImpl].destroyed) {
+    process.nextTick(cb, new Error('the worker has exited'))
+    return
+  }
+
+  if (!stream[kImpl].ready) {
+    const onReady = () => {
+      cleanup()
+      requestWorkerFlush(stream, cb)
+    }
+    const onClose = () => {
+      cleanup()
+      process.nextTick(cb, new Error('the worker has exited'))
+    }
+    const cleanup = () => {
+      stream.off('ready', onReady)
+      stream.off('close', onClose)
+    }
+
+    stream.once('ready', onReady)
+    stream.once('close', onClose)
+    return
+  }
+
+  const id = ++stream[kImpl].nextFlushId
+  stream[kImpl].flushCallbacks.set(id, cb)
+
+  try {
+    stream.worker.postMessage({
+      code: 'FLUSH',
+      context: 'thread-stream',
+      id
+    })
+  } catch (err) {
+    stream[kImpl].flushCallbacks.delete(id)
+    destroy(stream, err)
+    process.nextTick(cb, err)
+  }
+}
+
+function failPendingFlushCallbacks (stream, err) {
+  const callbacks = stream[kImpl].flushCallbacks
+  if (callbacks.size === 0) {
+    return
+  }
+
+  const flushErr = err || new Error('the worker has exited')
+
+  for (const cb of callbacks.values()) {
+    process.nextTick(cb, flushErr)
+  }
+  callbacks.clear()
+}
+
 function error (stream, err) {
   setImmediate(() => {
     stream.emit('error', err)
@@ -377,6 +474,7 @@ function destroy (stream, err) {
     return
   }
   stream[kImpl].destroyed = true
+  failPendingFlushCallbacks(stream, err)
 
   if (err) {
     stream[kImpl].errored = err
@@ -398,13 +496,43 @@ function destroy (stream, err) {
   }
 }
 
-function write (stream, data, cb) {
+function write (stream, maxBytes, cb) {
   // data is smaller than the shared buffer length
   const current = Atomics.load(stream[kImpl].state, WRITE_INDEX)
-  const length = Buffer.byteLength(data)
-  stream[kImpl].data.write(data, current)
-  Atomics.store(stream[kImpl].state, WRITE_INDEX, current + length)
-  Atomics.notify(stream[kImpl].state, WRITE_INDEX)
+  let offset = current
+  let remaining = maxBytes
+
+  while (remaining > 0 && stream[kImpl].bufLen !== 0) {
+    const head = stream[kImpl].bufHead
+    const buf = stream[kImpl].buf[head]
+
+    if (buf.length <= remaining) {
+      buf.copy(stream[kImpl].data, offset)
+      offset += buf.length
+      remaining -= buf.length
+      stream[kImpl].bufLen -= buf.length
+      stream[kImpl].bufHead = head + 1
+
+      if (stream[kImpl].bufHead === stream[kImpl].buf.length) {
+        stream[kImpl].buf.length = 0
+        stream[kImpl].bufHead = 0
+      } else if (stream[kImpl].bufHead >= 1024 && stream[kImpl].bufHead * 2 >= stream[kImpl].buf.length) {
+        stream[kImpl].buf.splice(0, stream[kImpl].bufHead)
+        stream[kImpl].bufHead = 0
+      }
+      continue
+    }
+
+    buf.copy(stream[kImpl].data, offset, 0, remaining)
+    stream[kImpl].buf[head] = buf.subarray(remaining)
+    stream[kImpl].bufLen -= remaining
+    offset += remaining
+    remaining = 0
+  }
+
+  updateState(stream, () => {
+    Atomics.store(stream[kImpl].state, WRITE_INDEX, offset)
+  })
   cb()
   return true
 }
@@ -421,9 +549,10 @@ function end (stream) {
     let readIndex = Atomics.load(stream[kImpl].state, READ_INDEX)
 
     // process._rawDebug('writing index')
-    Atomics.store(stream[kImpl].state, WRITE_INDEX, -1)
+    updateState(stream, () => {
+      Atomics.store(stream[kImpl].state, WRITE_INDEX, -1)
+    })
     // process._rawDebug(`(end) readIndex (${Atomics.load(stream.state, READ_INDEX)}) writeIndex (${Atomics.load(stream.state, WRITE_INDEX)})`)
-    Atomics.notify(stream[kImpl].state, WRITE_INDEX)
 
     // Wait for the process to complete
     let spins = 0
@@ -463,44 +592,19 @@ function writeSync (stream) {
   }
   stream[kImpl].flushing = false
 
-  while (stream[kImpl].buf.length !== 0) {
+  while (stream[kImpl].bufLen !== 0) {
     const writeIndex = Atomics.load(stream[kImpl].state, WRITE_INDEX)
-    let leftover = stream[kImpl].data.length - writeIndex
+    const leftover = stream[kImpl].data.length - writeIndex
     if (leftover === 0) {
       flushSync(stream)
-      Atomics.store(stream[kImpl].state, READ_INDEX, 0)
-      Atomics.store(stream[kImpl].state, WRITE_INDEX, 0)
-      Atomics.notify(stream[kImpl].state, READ_INDEX)
+      resetIndexes(stream)
       continue
     } else if (leftover < 0) {
       // stream should never happen
       throw new Error('overwritten')
     }
 
-    let toWrite = stream[kImpl].buf.slice(0, leftover)
-    let toWriteBytes = Buffer.byteLength(toWrite)
-    if (toWriteBytes <= leftover) {
-      stream[kImpl].buf = stream[kImpl].buf.slice(leftover)
-      // process._rawDebug('writing ' + toWrite.length)
-      write(stream, toWrite, cb)
-    } else {
-      // multi-byte utf-8
-      flushSync(stream)
-      Atomics.store(stream[kImpl].state, READ_INDEX, 0)
-      Atomics.store(stream[kImpl].state, WRITE_INDEX, 0)
-      Atomics.notify(stream[kImpl].state, READ_INDEX)
-
-      // Find a toWrite length that fits the buffer
-      // it must exists as the buffer is at least 4 bytes length
-      // and the max utf-8 length for a char is 4 bytes.
-      while (toWriteBytes > stream[kImpl].buf.length) {
-        leftover = leftover / 2
-        toWrite = stream[kImpl].buf.slice(0, leftover)
-        toWriteBytes = Buffer.byteLength(toWrite)
-      }
-      stream[kImpl].buf = stream[kImpl].buf.slice(leftover)
-      write(stream, toWrite, cb)
-    }
+    write(stream, leftover, cb)
   }
 }
 

package/lib/indexes.js

@@ -1,9 +1,11 @@
 'use strict'
 
+const SEQ_INDEX = 2
 const WRITE_INDEX = 4
 const READ_INDEX = 8
 
 module.exports = {
   WRITE_INDEX,
-  READ_INDEX
+  READ_INDEX,
+  SEQ_INDEX
 }

package/lib/wait.js

@@ -50,12 +50,21 @@ function waitDiff (state, index, expected, timeout, done) {
       return
     }
 
-    // Wait for value to change from expected
+    // Wait for value to change from expected.
+    // If we are notified, resume immediately even if the value cycled back
+    // to the same number before we could re-read it.
     const remaining = max === Infinity ? WAIT_MS : Math.min(WAIT_MS, Math.max(1, max - Date.now()))
     const result = Atomics.waitAsync(state, index, expected, remaining)
 
     if (result.async) {
-      result.value.then(check)
+      result.value.then((res) => {
+        if (res === 'ok') {
+          done(null, 'ok')
+          return
+        }
+
+        check()
+      })
     } else {
       // Value already changed (not-equal) - recheck on next tick
       setImmediate(check)

package/lib/worker.js

@@ -2,7 +2,8 @@
 
 const { realImport, realRequire } = require('real-require')
 const { workerData, parentPort } = require('worker_threads')
-const { WRITE_INDEX, READ_INDEX } = require('./indexes')
+const { StringDecoder } = require('string_decoder')
+const { WRITE_INDEX, READ_INDEX, SEQ_INDEX } = require('./indexes')
 const { waitDiff } = require('./wait')
 
 const {
@@ -12,13 +13,111 @@ const {
 } = workerData
 
 let destination
+const flushQueue = []
+let flushing = false
 
 const state = new Int32Array(stateBuf)
 const data = Buffer.from(dataBuf)
+const decoder = new StringDecoder('utf8')
 
 // Keep the event loop alive - Atomics.waitAsync promises don't prevent worker exit
 const keepAlive = setInterval(() => {}, 60 * 60 * 1000)
 
+function onParentPortMessage (msg) {
+  if (!msg || msg.code !== 'FLUSH' || msg.context !== 'thread-stream') {
+    return
+  }
+
+  flushQueue.push(msg.id)
+  processFlushQueue()
+}
+
+function processFlushQueue () {
+  if (flushing || !destination) {
+    return
+  }
+
+  const id = flushQueue.shift()
+  if (id === undefined) {
+    return
+  }
+
+  flushing = true
+  flushDestination((err) => {
+    flushing = false
+
+    if (err) {
+      parentPort.postMessage({
+        code: 'ERROR',
+        err
+      })
+      return
+    }
+
+    parentPort.postMessage({
+      code: 'FLUSHED',
+      context: 'thread-stream',
+      id
+    })
+
+    processFlushQueue()
+  })
+}
+
+function flushDestination (cb) {
+  if (typeof destination?.flush === 'function') {
+    if (destination.flush.length === 0) {
+      try {
+        const result = destination.flush()
+        if (result && typeof result.then === 'function') {
+          result.then(() => cb(), cb)
+        } else {
+          cb()
+        }
+      } catch (err) {
+        cb(err)
+      }
+      return
+    }
+
+    let done = false
+    const onDone = (err) => {
+      if (done) {
+        return
+      }
+      done = true
+      cb(err)
+    }
+
+    try {
+      const result = destination.flush(onDone)
+      if (result && typeof result.then === 'function') {
+        result.then(() => onDone(), onDone)
+      }
+    } catch (err) {
+      onDone(err)
+    }
+    return
+  }
+
+  if (typeof destination?.flushSync === 'function') {
+    try {
+      destination.flushSync()
+      cb()
+    } catch (err) {
+      cb(err)
+    }
+    return
+  }
+
+  if (destination?.writableNeedDrain && !destination?.writableEnded) {
+    destination.once('drain', cb)
+    return
+  }
+
+  cb()
+}
+
 async function start () {
   let worker
   try {
@@ -93,12 +192,16 @@ async function start () {
       process.exit(0)
     })
   })
+
+  processFlushQueue()
 }
 
 // No .catch() handler,
 // in case there is an error it goes
 // to unhandledRejection
 start().then(function () {
+  parentPort.on('message', onParentPortMessage)
+
   parentPort.postMessage({
     code: 'READY'
   })
@@ -106,18 +209,30 @@ start().then(function () {
   process.nextTick(run)
 })
 
+function readState () {
+  while (true) {
+    const seq = Atomics.load(state, SEQ_INDEX)
+
+    if ((seq & 1) !== 0) {
+      continue
+    }
+
+    const current = Atomics.load(state, READ_INDEX)
+    const end = Atomics.load(state, WRITE_INDEX)
+
+    if (seq === Atomics.load(state, SEQ_INDEX)) {
+      return { current, end, seq }
+    }
+  }
+}
+
 function run () {
-  const current = Atomics.load(state, READ_INDEX)
-  const end = Atomics.load(state, WRITE_INDEX)
+  const { current, end, seq } = readState()
 
   // process._rawDebug(`pre state ${current} ${end}`)
 
   if (end === current) {
-    if (end === data.length) {
-      waitDiff(state, READ_INDEX, end, Infinity, run)
-    } else {
-      waitDiff(state, WRITE_INDEX, end, Infinity, run)
-    }
+    waitDiff(state, SEQ_INDEX, seq, Infinity, run)
     return
   }
 
@@ -125,11 +240,15 @@ function run () {
 
   if (end === -1) {
     // process._rawDebug('end')
+    const remaining = decoder.end()
+    if (remaining.length > 0) {
+      destination.write(remaining)
+    }
     destination.end()
     return
   }
 
-  const toWrite = data.toString('utf8', current, end)
+  const toWrite = decoder.write(data.subarray(current, end))
   // process._rawDebug('worker writing: ' + toWrite)
 
   const res = destination.write(toWrite)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thread-stream",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "A streaming way to send data to a Node.js Worker Thread",
   "main": "index.js",
   "types": "index.d.ts",
@@ -8,30 +8,28 @@
     "node": ">=20"
   },
   "dependencies": {
-    "real-require": "^0.2.0"
+    "real-require": "^1.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.0.2",
     "@yao-pkg/pkg": "^6.0.0",
-    "borp": "^0.21.0",
+    "borp": "^1.0.0",
     "desm": "^1.3.0",
     "eslint": "^9.39.1",
     "fastbench": "^1.0.1",
-    "husky": "^9.0.6",
-    "neostandard": "^0.12.2",
-    "pino-elasticsearch": "^8.0.0",
-    "sonic-boom": "^4.0.1",
+    "neostandard": "^0.13.0",
+    "pino-elasticsearch": "^9.0.0",
+    "sonic-boom": "^5.0.0",
     "ts-node": "^10.8.0",
     "typescript": "~5.7.3"
   },
   "scripts": {
     "build": "tsc --noEmit",
     "lint": "eslint",
-    "test": "npm run lint && npm run build && npm run transpile && borp --pattern 'test/*.test.{js,mjs}'",
-    "test:ci": "npm run lint && npm run transpile && borp --pattern 'test/*.test.{js,mjs}'",
-    "test:yarn": "npm run transpile && borp --pattern 'test/*.test.js'",
-    "transpile": "sh ./test/ts/transpile.sh",
-    "prepare": "husky install"
+    "test": "npm run lint && npm run build && npm run transpile && borp --pattern \"test/*.test.{js,mjs}\"",
+    "test:ci": "npm run lint && npm run transpile && borp --pattern \"test/*.test.{js,mjs}\"",
+    "test:yarn": "npm run transpile && borp --pattern \"test/*.test.js\"",
+    "transpile": "sh ./test/ts/transpile.sh"
   },
   "repository": {
     "type": "git",

package/test/flush-worker.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const { EventEmitter } = require('events')
+const { parentPort } = require('worker_threads')
+
+function createDestination (mode) {
+  const destination = new EventEmitter()
+  destination.writableEnded = false
+  destination.writableNeedDrain = false
+
+  destination.write = function () {
+    if (mode === 'drain') {
+      destination.writableNeedDrain = true
+      setTimeout(() => {
+        destination.writableNeedDrain = false
+        parentPort.postMessage({
+          code: 'EVENT',
+          name: 'destination-drain'
+        })
+        destination.emit('drain')
+      }, 50)
+    }
+
+    return true
+  }
+
+  destination.end = function () {
+    destination.writableEnded = true
+    destination.emit('close')
+  }
+
+  if (mode === 'flush') {
+    destination.flush = function (cb) {
+      setTimeout(() => {
+        parentPort.postMessage({
+          code: 'EVENT',
+          name: 'destination-flushed'
+        })
+        cb()
+      }, 50)
+    }
+  }
+
+  if (mode === 'flush-sync') {
+    destination.flushSync = function () {
+      parentPort.postMessage({
+        code: 'EVENT',
+        name: 'destination-flush-sync'
+      })
+    }
+  }
+
+  if (mode === 'exit-on-flush') {
+    destination.flush = function (_cb) {
+      setTimeout(() => {
+        process.exit(0)
+      }, 20)
+    }
+  }
+
+  return destination
+}
+
+async function run (opts) {
+  return createDestination(opts.mode)
+}
+
+module.exports = run

package/test/flush.test.js

@@ -0,0 +1,112 @@
+'use strict'
+
+const { test } = require('node:test')
+const assert = require('node:assert')
+const { once } = require('node:events')
+const { join } = require('node:path')
+const ThreadStream = require('..')
+
+function createStream (mode) {
+  return new ThreadStream({
+    filename: join(__dirname, 'flush-worker.js'),
+    workerData: { mode },
+    sync: false
+  })
+}
+
+test('flush waits for worker destination.flush(cb)', async function () {
+  const stream = createStream('flush')
+  let flushed = false
+
+  stream.on('destination-flushed', () => {
+    flushed = true
+  })
+
+  assert.ok(stream.write('hello'))
+
+  await new Promise((resolve, reject) => {
+    stream.flush((err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+
+  assert.strictEqual(flushed, true)
+
+  const close = once(stream, 'close')
+  stream.end()
+  await close
+})
+
+test('flush falls back to destination.flushSync()', async function () {
+  const stream = createStream('flush-sync')
+  let called = false
+
+  stream.on('destination-flush-sync', () => {
+    called = true
+  })
+
+  assert.ok(stream.write('hello'))
+
+  await new Promise((resolve, reject) => {
+    stream.flush((err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+
+  assert.strictEqual(called, true)
+
+  const close = once(stream, 'close')
+  stream.end()
+  await close
+})
+
+test('flush waits for drain when destination has no flush API', async function () {
+  const stream = createStream('drain')
+  let drained = false
+
+  stream.on('destination-drain', () => {
+    drained = true
+  })
+
+  assert.ok(stream.write('hello'))
+
+  await new Promise((resolve, reject) => {
+    stream.flush((err) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve()
+    })
+  })
+
+  assert.strictEqual(drained, true)
+
+  const close = once(stream, 'close')
+  stream.end()
+  await close
+})
+
+test('pending flush callbacks fail when worker exits', async function () {
+  const stream = createStream('exit-on-flush')
+  const close = once(stream, 'close')
+
+  assert.ok(stream.write('hello'))
+
+  const err = await new Promise((resolve) => {
+    stream.flush(resolve)
+  })
+
+  assert.ok(err)
+  assert.strictEqual(err.message, 'the worker has exited')
+
+  await close
+})

package/test/message-without-code.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const { Writable } = require('stream')
+const { parentPort } = require('worker_threads')
+
+async function run () {
+  parentPort.postMessage({
+    internal: 'watch-mode'
+  })
+
+  return new Writable({
+    autoDestroy: true,
+    write (chunk, enc, cb) {
+      cb()
+    }
+  })
+}
+
+module.exports = run

package/test/multibyte-overrun.test.mjs

@@ -0,0 +1,33 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import ThreadStream from '../index.js'
+import { join } from 'desm'
+import { file } from './helper.js'
+
+test('preserves multibyte records that cross the buffer boundary', async () => {
+  const dest = file()
+  const stream = new ThreadStream({
+    bufferSize: 128,
+    filename: join(import.meta.url, 'to-file.js'),
+    workerData: { dest },
+    sync: false
+  })
+
+  let expected = ''
+
+  for (let i = 0; i < 1000; i++) {
+    const line = `{"idx":${i},"alert":"🚨"}\n`
+    expected += line
+    stream.write(line)
+  }
+
+  await new Promise((resolve, reject) => {
+    stream.once('error', reject)
+    stream.once('close', resolve)
+    stream.end()
+  })
+
+  const data = await readFile(dest, 'utf8')
+  assert.strictEqual(data, expected)
+})

package/test/report-thread-name.js

@@ -0,0 +1,16 @@
+'use strict'
+
+const { Writable } = require('stream')
+const { threadName, parentPort } = require('worker_threads')
+
+module.exports = function () {
+  parentPort.once('message', function ({ port }) {
+    port.postMessage({ threadName })
+  })
+
+  return new Writable({
+    write (chunk, encoding, callback) {
+      callback()
+    }
+  })
+}

package/test/thread-management.test.js

@@ -27,6 +27,9 @@ test('emit error if thread exits', async function (t) {
   })
 
   const closed = once(stream, 'close').catch(() => {})
+  // Keep a persistent error listener to avoid unhandled late error events
+  // reported as asynchronous activity by stricter test runners.
+  stream.on('error', () => {})
 
   stream.on('ready', () => {
     stream.write('hello world\n')
@@ -53,6 +56,9 @@ test('emit error if thread have unhandledRejection', async function (t) {
   })
 
   const closed = once(stream, 'close').catch(() => {})
+  // Keep a persistent error listener to avoid unhandled late error events
+  // reported as asynchronous activity by stricter test runners.
+  stream.on('error', () => {})
 
   stream.on('ready', () => {
     stream.write('hello world\n')
@@ -79,6 +85,9 @@ test('emit error if worker stream emit error', async function (t) {
   })
 
   const closed = once(stream, 'close').catch(() => {})
+  // Keep a persistent error listener to avoid unhandled late error events
+  // reported as asynchronous activity by stricter test runners.
+  stream.on('error', () => {})
 
   stream.on('ready', () => {
     stream.write('hello world\n')
@@ -105,6 +114,9 @@ test('emit error if thread have uncaughtException', async function (t) {
   })
 
   const closed = once(stream, 'close').catch(() => {})
+  // Keep a persistent error listener to avoid unhandled late error events
+  // reported as asynchronous activity by stricter test runners.
+  stream.on('error', () => {})
 
   stream.on('ready', () => {
     stream.write('hello world\n')

package/test/watch-mode.test.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const { test } = require('node:test')
+const assert = require('node:assert')
+const { once } = require('events')
+const { join } = require('path')
+const ThreadStream = require('..')
+
+test('ignores worker messages without a protocol code', async function () {
+  const stream = new ThreadStream({
+    filename: join(__dirname, 'message-without-code.js'),
+    sync: false
+  })
+
+  const errors = []
+  stream.on('error', err => {
+    errors.push(err)
+  })
+
+  const ready = once(stream, 'ready')
+  const close = once(stream, 'close')
+
+  assert.ok(stream.write('hello world\n'))
+  stream.end()
+
+  await ready
+  await close
+
+  assert.deepStrictEqual(errors, [])
+})

package/test/worker-name.test.js

@@ -0,0 +1,43 @@
+'use strict'
+
+const { test } = require('node:test')
+const assert = require('node:assert')
+const { join } = require('path')
+const { once } = require('events')
+const { MessageChannel } = require('worker_threads')
+const ThreadStream = require('..')
+
+// threadName was added in Node.js v22.20.0 and v24.6.0
+const [major, minor] = process.versions.node.split('.').map(Number)
+const supportsThreadName = (major === 22 && minor >= 20) || major >= 24
+
+test('worker has default name "thread-stream"', { skip: !supportsThreadName }, async function (t) {
+  const { port1, port2 } = new MessageChannel()
+  const stream = new ThreadStream({
+    filename: join(__dirname, 'report-thread-name.js'),
+    sync: true
+  })
+
+  t.after(() => stream.end())
+
+  stream.emit('message', { port: port1 }, [port1])
+  const [{ threadName }] = await once(port2, 'message')
+  assert.strictEqual(threadName, 'thread-stream')
+})
+
+test('worker name can be overridden via workerOpts', { skip: !supportsThreadName }, async function (t) {
+  const { port1, port2 } = new MessageChannel()
+  const stream = new ThreadStream({
+    filename: join(__dirname, 'report-thread-name.js'),
+    workerOpts: {
+      name: 'my-custom-worker'
+    },
+    sync: true
+  })
+
+  t.after(() => stream.end())
+
+  stream.emit('message', { port: port1 }, [port1])
+  const [{ threadName }] = await once(port2, 'message')
+  assert.strictEqual(threadName, 'my-custom-worker')
+})

package/.husky/pre-commit

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npm test

package/CLAUDE.md

@@ -1,53 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Build & Test Commands
-
-```sh
-npm test                    # Run linter (standard), type check, transpile, and all tests
-npm run build               # Type check only (tsc --noEmit)
-npm run transpile           # Generate transpiled test files for various ES targets
-
-# Run a single test file
-npx tap test/base.test.js
-
-# Run only JavaScript tests (faster)
-npx tap "test/**/*.test.*js"
-
-# Run only TypeScript tests
-npx tap --ts test/*.test.*ts
-```
-
-## Code Style
-
-This project uses [Standard](https://standardjs.com/) for linting. No semicolons, 2-space indentation.
-
-## Architecture
-
-thread-stream is a library for streaming data to a Node.js Worker Thread using SharedArrayBuffer for high-performance inter-thread communication.
-
-### Core Components
-
-- **index.js** - Main `ThreadStream` class extending EventEmitter. Manages the worker lifecycle, handles writes via SharedArrayBuffer, and coordinates synchronization using Atomics.
-
-- **lib/worker.js** - Runs in the Worker Thread. Loads the user-provided destination module, reads data from SharedArrayBuffer, and writes to the destination stream. Handles both ESM and CommonJS modules, including yarn PnP compatibility.
-
-- **lib/indexes.js** - Defines SharedArrayBuffer index constants (`WRITE_INDEX`, `READ_INDEX`) used for Atomics coordination.
-
-- **lib/wait.js** - Async polling utilities (`wait`, `waitDiff`) for cross-thread synchronization without blocking the main thread.
-
-### Data Flow
-
-1. Main thread writes strings to an internal buffer, then copies to SharedArrayBuffer
-2. Atomics.notify signals the worker that data is available
-3. Worker reads from SharedArrayBuffer via Atomics.load and writes to destination stream
-4. Worker updates READ_INDEX and notifies main thread when done
-5. Special index values (-1 for end, -2 for error) signal stream termination
-
-### Key Features
-
-- **Sync/async modes** - `sync: true` blocks until data is written; async mode uses `setImmediate` batching
-- **Backpressure** - Handles `drain` events from destination streams
-- **GC cleanup** - Uses FinalizationRegistry to terminate orphaned workers
-- **TypeScript support** - Workers can be `.ts` files (requires ts-node)