Skip to content

Release notes

Eugene Lazutkin edited this page Nov 9, 2026 · 23 revisions

Release notes

Long-form per-release changelog for stream-chain. The repo's README.md carries cliff-notes for users skimming GitHub; this page is the canonical history with internal-change context, motivation, and credits.

4.4.2 — 2026-11-09

Patch release. One bug fix. No API changes.

Fixed

  • readableFrom() and readableWebStreamFrom() release their sources when a stream stops early. A break from for await, destroy(), cancel(), an aborted pipeTo(), a failing source, or a stop calls return() on each active iterator, innermost first, so a generator's finally runs. Before this release, a break skipped a source's finally. When the pump is waiting for demand, the iterators close one at a time, teardown waits for them, and a failing cleanup is reported. When a source operation is in progress, return() is called on all iterators at once and teardown doesn't wait, so a stalled source can't delay it (thx mayankdhingra02).

Notes

  • The utils page describes the teardown of both adapters.
  • The new Recipes page shows how to process a fetched response, parse Server-Sent Events, and feed a custom stream into a chain.
  • The test suites of stream-join (158 tests) and stream-sorting (175 tests) pass against this release on Node, Bun, and Deno. Both packages build on these adapters.

4.4.1 — 2026-10-28

Patch release. Two bug fixes. No API changes.

Fixed

  • gen(), fun(), pipe(), and the /core chain() pass null and undefined through again. Since 4.1.1 they dropped both at every stage, the rule of the stream drivers, while the documentation said they pass them on like any other value. They pass them again, as 4.1.0 did: between stages, as output, from many(), from a generator, and from a flush. A stage that returns nothing now gives undefined to the next stage, and a for await loop over the pipeline sees undefined items. Return none to drop a value in every context. asStream(), asWebStream(), and the chain() from stream-chain and stream-chain/web still drop null and undefined, since streams reserve them for end-of-stream. Regression tests in tests/core/test-null.js, tests/node/test-chain-null.js, and tests/web/test-web-chain-null.js.
  • A stream driver drops a null returned through finalValue(). In a Node chain() a finalValue(null) ended the stream and lost the values after it; in a Web chain() it emitted the null. Both now drop it like any other null, and gen() still emits it.

Notes

  • The gen(), fun(), asStream(), defs, chain(), and Concepts pages name every driver that passes null through and every driver that drops it.
  • stream-json's test suite (897 tests on Node, Bun, and Deno, plus its TypeScript tests and type checks) passes against this release, as it does against 4.4.0.

4.4.0 — 2026-10-28

Minor release. drain() ends a pipe() run on its stop without an exception, and a Stop can come from another library. New API: isStop() and stopErrorSymbol. One bug fix.

Added

  • isStop(error) and stopErrorSymbol. isStop() checks the mark every Stop carries, not its class, so a library can throw a Stop of its own class, marked with Symbol.for('object-stream.stopError'), without depending on stream-chain. stream-chain's pipelines recognize a stop the same way. See isStop() and stopErrorSymbol.

Changed

  • drain() ends a pipe() run on its Stop and returns the last value. Before, drain(pipe(...)) rejected with Stop when a stage stopped the pipeline, although pipe() had already flushed the stages after the stopper. This is a breaking change for code that caught that Stop to learn the run ended early: that code now takes the normal path. Iterate the run with for await to see the Stop. A Stop from any other iterable, a gen() run included, still reaches the caller, since a gen() pipeline keeps processing the inputs fed to it after a stop. See drain().

Fixed

  • asyncBlockWriter() keeps a surrogate pair in one write. When a string it received ended with the first half of a surrogate pair and that string filled a block, the two halves went to separate writes, and each half was written as U+FFFD: a 4-byte character became 6 bytes. The writer now holds the first half for the next write. stringerToFile() and the file stringers built on the writer get the fix. Contributed by edsonsims.

Notes

  • Every internal symbol is a well-known name too, Symbol.for('object-stream.<name>'), as the public markers already were.
  • The chain() page now explains the AbortError that pipeline() from stream/promises reports after a stop when its last step is an async generator function. It is Node's behavior; a Writable destination, the callback form, and for await end cleanly.
  • stream-json's test suite (875 tests on Node, Bun, and Deno, plus its type checks) passes against this release, and drain(pipe(parseFile(), …)) with a stage that stops resolves, where 4.3.0 rejected with Stop.
  • Dev dependencies bumped (@types/node).

4.3.0 — 2026-10-26

Minor release. Pipelines release their resources when they end early, a stop flushes the stages after it the same way everywhere, and a leading byte-order mark is dropped. New API: a flushable abort, close() on the file sinks, and an ignoreBOM option.

Added

  • flushable(write, final, abort). The optional third function releases a stage's resources when the pipeline ends abnormally: an error in another stage, an early break, a destroyed or cancelled stream, or a stop by this stage or a later one. It is stored under abortSymbol, also available as chain.abortSymbol. gen(), pipe(), asStream(), and asWebStream() call it at most once, and never after the stage's own final completed. See flushable().
  • close() on asyncBlockWriter() and stringerToFile(). It releases the file handle and drops the buffered tail. It is also the writer's abort, so a pipeline closes the file when it ends early; call it yourself when you drive the writer some other way.
  • ignoreBOM. fixUtf8Stream(), the JSONL parsers, parseFile(), and asyncBlockReader() take ignoreBOM: true to keep a leading byte-order mark.

Changed

  • A stop flushes the stages after the stopper, on every owner. Before, asStream() and the Node chain() flushed every stage after a stop, the stages before the stopper included, while asWebStream(), the web chain(), and pipe() flushed none, so a sink after the stopper (a stringerToFile(), a batch()) lost what it buffered. Now the stages after the stopper are flushed, and the stopper and the stages before it are released through their abort. On the Node owners, the stages before the stopper are no longer flushed. With gen() and fun(), the flush you call with none covers only the stages after the stopper. See defs.
  • A Stop lands at the right stage. A thrown Stop works the same as a returned stop, a Stop that leaves a pipe() used as a stage stops at that stage, and a stop during the flush ends the stopper's output while the flush goes on with the stages after it.
  • pipe() flushes before it releases. After a stop, it flushes the stages after the stopper, then releases the stopper and the stages before it, as the stream owners do, so a failing release never costs the flushed output.

Fixed

  • Teardown releases generator stages. When an asStream() or asWebStream() stage is destroyed, cancelled, or aborted, a generator stage suspended at a yield is closed, so its finally runs; a generator whose values all get dropped is stopped before its next yield. Contributed by mkantautas.
  • The Node chain() destroys its inner streams when it is destroyed before both of its sides finish, as stream.pipeline() does, without passing the error down.
  • A leading BOM is dropped. fixUtf8Stream() and asyncBlockReader() drop a U+FEFF that starts the input, bytes or strings, on Node, Bun, Deno, and browsers, and keep a later one. stream-json's parsers, which start with fixUtf8Stream(), accept a BOM-prefixed document again once they take this release. Reported by nemphys.
  • A stop with a failing cleanup surfaces the cleanup error alone, in place of an AggregateError that held the internal Stop.

Notes

  • Each flushable stage gets its final or its abort, once, never both: an owner records which stages finished, so no stage is aborted twice or after its own final completed.
  • stream-json's test suite (762 tests on Node, Bun, and Deno, plus its type checks) passes against this release.
  • Deno's TextDecoder drops a U+FEFF that starts a later decode() call in streaming mode (denoland/deno#37090), so the leading-BOM rule is applied by hand on every runtime.
  • Dev dependencies bumped (@types/node, nano-benchmark, prettier).

4.2.6 — 2026-09-26

Patch release. Three bug fixes. No API changes.

Fixed

  • fun() keeps the outputs of overlapping calls apart. A composed fun() pipeline held one output buffer for all its calls, so calling it again before an asynchronous call settled mixed the two calls' values, and one of them could fail with a TypeError or resolve to null. Each call now collects into its own buffer, the way gen() always did. Reported by oss-security-shopify; the report was handled as a bug, not a security advisory, since both calls come from the same application. Regression tests in tests/core/test-fun-direct.js.
  • lines() handles a CRLF split across chunks. When \r ended one chunk and \n started the next, the emitted line kept a trailing \r; the same text in one chunk did not. The JSONL parser was unaffected (JSON.parse ignores the whitespace). First direct tests for lines() in tests/core/test-lines.js.
  • asyncBlockWriter refuses every call after a failed write. After a failed block write, final write, or close, the next call used to reopen the file with 'w', truncating what had been written, and carry on without an error. Every later call now throws an Error whose cause is the original failure, and the file is kept as it was. New tests in tests/node/test-asyncBlockWriter.js.

Notes

  • fixUtf8Stream()'s input contract is documented: one stream carries either bytes or strings, not both. Its unused internal buffer was removed, with no change in behavior.
  • The JSONL splitter was audited for rescanning on every chunk and measured linear on Node and Bun, 1 to 16 MB in a single line; bench/jsonl-long-line.js stays as the regression meter.
  • Dev dependencies bumped (@types/node, prettier, tape-six).

4.2.5 — 2026-06-07

Patch release. Plugs a file-descriptor leak in asyncBlockWriter on its own write failure. No API changes.

Fixed

  • asyncBlockWriter releases its FileHandle when its own block write fails. Previously only the final tail-write path (final()) released the handle on failure; a failure in a data-pass block write (or the lazy open it triggers) leaked the fd, because the flushable's final() never runs on an aborted pipeline. The data-pass write() is now guarded the same way: on failure it closes the handle before the error propagates, and a write+close double-fault still surfaces an AggregateError([writeErr, closeErr]) in that order. This covers the stage's own I/O failures only — a resource-owning sink still cannot observe an unrelated stage throwing elsewhere in the pipe; release from your own catch/finally for that case. Regression test in tests/node/test-resource-cleanup.js.

4.2.4 — 2026-06-07

Patch release. Fixes a regression introduced in 4.2.3: a failed pipe() could throw a spurious AggregateError carrying the same error twice. No API changes.

Fixed

  • A failed pipe() propagates the original error, not an AggregateError. 4.2.3 ran pipe()'s end-of-input flush in a finally, so on a data-pass error it re-drove the pipeline to flush. A stateful flushable that throws before consuming its buffer (e.g. stream-json's jsonVerifier on malformed input) then re-ran the same work over the same dirty buffer and threw a second, logically-identical error — which pipe() wrapped as AggregateError([E, E]), obscuring the real error and its {message, line, pos, offset} fields. pipe() now flushes only after the data pass completes: a throw propagates and the flush is skipped. An exception is not recoverable — a failed pipeline is not finalized.

Notes

  • The flush no longer runs on stop, a throw, or an early break. Finalizing a pipeline that didn't complete is wrong (it re-runs failed work and emits partial tails); the flush is reserved for clean completion. Resource-owning source stages still release inline (a generator source gets it.return() from the executor's abort path, unchanged since 4.2.2). A resource-owning sink that needs release on abort guards its own code with try/catch, or the caller does so in a catch/finally — the exception always propagates intact, never suppressed, so it stays actionable.
  • The genuine cleanup-double-fault AggregateError in asyncBlockReader / asyncBlockWriter / exec (an I/O op and a separate close() both failing) is unchanged — those combine two genuinely distinct failures and never re-run the work that threw.

4.2.3 — 2026-06-07

Patch release. Resource-cleanup fixes in the functional (pipe / gen) path and the asyncBlock* helpers, plus richer error reporting when cleanup itself fails. No API changes.

Fixed

  • pipe() flushes in a finally. A stop, throw, or early break in the data pass previously skipped the end-of-input flush, so a flushable sink's final() (e.g. asyncBlockWriter / stringerToFile closing its FileHandle) never ran — a confirmed file-handle leak (measured +1 fd). The flush now always runs.
  • asyncBlockWriter / asyncBlockReader always release their handle. A failed final write no longer skips the writer's close(); a throwing close() in the reader no longer masks the body error. exec.abort no longer silently drops the source generator's cleanup error.
  • Cleanup double-faults become an AggregateError. When an operation and its cleanup both throw, the two are reported together — .errors in chronological [first, second] order — instead of one masking the other. Wrapping happens only when the primary is a real Error, so gen()'s non-Error cancel sentinel keeps its identity. Single failures still propagate unwrapped (a bare Stop is still a Stop).

Notes

  • stop / finalValue are documented as supported from generators (none / many stay pointless there — a generator expresses both natively via yield / yield*). The rule: issue stop / finalValue, then return. Stream pipelines absorb a stop as a clean end; functional pipelines propagate it (catch for cleanup).
  • The finalValue auto-exit-generator alternative was benchmarked and rejected (a consistent ~2–3% regression on the generator-stage hot path); the documented rule above is the contract.

4.2.2 — 2026-05-29

Patch release. A correctness fix in the shared executor — source generators are now released when a pipeline ends abnormally, closing a file-handle leak on file-backed pipelines — plus removal of dead, undocumented runtime exports.

Fixed

  • Source generators are released on abnormal termination. exec's generator driver (nextGen) left a source generator suspended at its yield when iteration ended abnormally — a downstream stage throwing, a consumer cancelling (for-await break), or a stop. Its finally {} never ran, so a resource-owning source leaked: asyncBlockReader's FileHandle was never closed, and Node's GC finalizer later raised ERR_INVALID_STATE: A FileHandle object was closed during garbage collection. nextGen now calls it.return() on abnormal exit (awaited for an async generator) before re-throwing the original error — matching for await...of's AsyncIteratorClose semantics, where the original error wins over any cleanup error. This affects the pure pipe/drain (gen()) path used by parseFile() and stringerToFile() on errors or early termination; the asStream / asWebStream paths already cleaned up via the Node Duplex / stream destroy lifecycle.

Removed

  • Dead, undocumented runtime exports. None were typed (all absent from the .d.ts surface) or reachable through a documented entry point:
    • The legacy gen.next async-generator trampoline — gen() has been a push→pull bridge over the shared executor since 4.1.0; the trampoline was retained "for compatibility" but had no callers.
    • The fun.next / fun.collect / fun.asArray attachments and their named exports — fun.js now exports {fun} only. The collect / asArray functions remain (used internally).
    • The exec.next / exec.flush property attachments on the internal exec factory — the named next / flush exports (consumed by the four compositors) are unchanged.

Notes

  • Minor internal cleanup: one catch { (optional catch binding) where the error binding was already unused.

4.2.1 — 2026-05-29

Patch release. Factory-bundled JSONL entry points — the ergonomic adapter surface stream-json's JSONL needs to delegate here — plus a bugfix removing checkedParse(), which 4.2.0 exposed by mistake.

Added

  • Factory-bundled JSONL entries under stream-chain/node/jsonl/ and stream-chain/web/jsonl/. Each is one factory that carries the substrate adapters as methods, so jsonlParser.asStream(options) / jsonlParser.asWebStream(options) (and the stringer equivalents) work without separately importing the suffixed parserStream / parserWebStream modules.
    • stream-chain/node/jsonl/parser.js — jsonlParser() returns the gen() chain; .asStream (Node Duplex) and .asWebStream (Web pair) attached.
    • stream-chain/web/jsonl/parser.js — browser-safe; .asWebStream only (never pulls in node:stream).
    • stream-chain/node/jsonl/stringer.js — jsonlStringer() returns a Node Transform; .asStream is the factory itself, .asWebStream returns a Web TransformStream.
    • stream-chain/web/jsonl/stringer.js — browser-safe; returns a Web TransformStream, .asWebStream is itself.
    • Two curated barrels, stream-chain/node/jsonl and stream-chain/web/jsonl, export {jsonlParser, jsonlStringer} for the substrate (new exports keys back them).
    • The option/item type names match stream-json's — JsonlParserOptions, JsonlItem, JsonlStringerOptions — and a no-op checkErrors? option is accepted, so stream-json's deprecated JSONL users can migrate by changing only the import specifier. See jsonl § Factory-bundled entries for the full surface and a migration table.
  • The four existing JSONL adapter modules now also export their option types (ParserOptions, ParserWebStreamOptions, StringerOptions, StringerWebStreamOptions), previously declared but un-exported.

Fixed

  • Removed the standalone checkedParse() export from stream-chain/jsonl/parser.js. It was exposed in 4.2.0 by mistake — it has no use case outside the parser module (used exactly once internally), and the bogus arguments.length-based public signature it shipped with was never exercised. It is inlined back into its single call site. The streaming parser, the errorIndicator API, and ignoreErrors are unaffected.

Notes

  • The bundled entries delegate to the existing adapter modules; no parsing/serialization logic is duplicated. The Web-flavored entries are covered by the browser-safety test (no node:* imports in their transitive graph).
  • Internal: the per-line JSONL parser was refactored to select its error-handling closure once up front (function-form vs constant errorIndicator, ignoreErrors, default) rather than re-checking per line — behavior is unchanged.
  • These entries exist primarily to unblock stream-json's JSONL delegation: with the adapter surface matched, stream-json can repoint its JSONL re-exports here and eventually delete its own JSONL surface as an import-only swap.

4.2.0 — 2026-05-29

Minor release. New JSONL file-edge components for local-file pipelines, a richer JSONL error-handling API absorbed from stream-json, and a /core chain string-source pass-through fix. Everything else is additive; the only borderline-breaking change is the /core chain no longer iterating a string input character-by-character.

Added

  • JSONL file-edge composites under stream-chain/jsonl/file/ (Node-only).

    • parseFile(options) — returns a gen() pipeline shaped as (path) => AsyncGenerator<{key, value}>. Internally composes asyncBlockReader with the standard JSONL parser; forwards all parser options.
    • stringerToFile(path, options) — returns a gen() pipeline shaped as (value) => AsyncGenerator<never>. Terminal sink that composes the function-pipeline stringer with asyncBlockWriter; the writer's flushable final() closes the file handle on flush.
    • Drop straight into chain([...]) (the chain factory wraps them into one fused asStream internally), or drive directly with pipe(...) + drain(...) for the substrate-free gen path. See jsonl § File-edge composites for the full story and bench/jsonl-file.js for the round-trip numbers.
  • JSONL errorIndicator API on parser({...}), parserStream, and parserWebStream. Presence-checked ('errorIndicator' in options), so errorIndicator: undefined is meaningful and distinct from "not set":

    • errorIndicator: undefined — drop bad lines without bumping the line counter (sequential keys).
    • errorIndicator: null (or any constant) — emit the value in place of the failed line, counter bumps.
    • errorIndicator: (error, input, reviver) => unknown — function form; return value replaces the line, undefined return drops without bumping.
    • The legacy ignoreErrors: true shortcut is preserved unchanged for backwards compatibility (drops but the counter bumps every line → gappy keys). errorIndicator wins when both are set.
  • Raw jsonlParser(options?) — per-line factory without the fixUtf8Stream -> lines input front. For callers whose chunks already arrive line-aligned. Parallels stream-json's jsonParser raw export.

  • Standalone checkedParse(input, reviver?, errorIndicator?) — single-line parser. Behaves exactly like JSON.parse(input, reviver) unless errorIndicator is passed, in which case parse failures invoke the function form (or return the constant) instead of throwing. arguments.length < 3 is what distinguishes "omitted-indicator throws" from "explicit undefined catches".

  • Function-pipeline JSONL stringer at src/jsonl/stringer.js. Flushable; canonical building block alongside the existing Transform / TransformStream variants. Same options as stringerStream.

  • Supporting helpers in src/utils/:

    • pipe(...stages) — one-shot single-value driver for a gen pipeline. Runs g(value) then g(none) so flushable sinks close. Substrate-free.
    • drain(asyncIter) — awaits an async iterable, returns its last yielded value. Standard way to await a pipe(...)(value) whose output you don't otherwise want.
    • asyncBlockReader(options?) — Node-only (path) => AsyncGenerator<string> over fs/promises.open + StringDecoder('utf8').
    • asyncBlockWriter(path, options?) — Node-only flushable that buffers and writes fixed-size blocks via fileHandle.write, closing the handle on flush.

Fixed

  • /core chain string-source iteration footgun. chain([...])('input.json') previously walked 'i','n','p',... into the first stage because strings carry a Symbol.iterator and /core's outer for await (const v of input) yield* g(v) happily iterated them. The driver now passes strings through as a single value, and the same check carves out other non-iterables (numbers, booleans, plain objects, …) so they don't throw on for await either. Arrays, generators, async iterables, Map, Set still iterate as before; null / undefined still yield empty. Borderline-breaking — anyone relying on per-character iteration of a string source loses it (the explicit replacement is [...'hello']). Surfaced 2026-05-28 wiring stream-json's parseFile.

  • Empty JSONL lines now dropped silently across all parser variants. Was: JSON.parse('') threw without ignoreErrors set. This is part of the errorIndicator work and applies uniformly to parser / parserStream / parserWebStream regardless of which error-handling option (if any) is set.

Notes

  • Bench. bench/jsonl-file.js (50k JSONL rows fixture, nano-bench driven) compares the new file-edge components against the equivalent fs.createReadStream + parserStream + ... + stringerStream + fs.createWriteStream arrangement. Round-trip is ~40% faster; parse-with-in-pipeline-work is ~10% faster; parse-and-drain-externally is ~20% slower (the per-token gen async-bridge cost — same lesson as the sink-placement principle stream-json saw in its 2026-05-28 file-edge bench). See the bench header for which shape applies to which workload.

  • stream-json proxy unblocked. The errorIndicator / checkedParse API absorption makes stream-json's src/core/jsonl/parser.js a candidate to collapse to a proxy re-export of stream-chain's parser plus a couple of aliases. The stream-json side ships when its peerdep is bumped to ^4.2.0 (separate session).

  • Helpers duplicated for now. pipe, drain, asyncBlockReader, and asyncBlockWriter are intentionally mirrored between stream-chain and stream-json so each package stays self-contained. A future stream-json cleanup will collapse its copies into re-exports from stream-chain.

  • Docs lead. README gained a new "JSONL" section with a chain()-based round-trip example, wiki/jsonl.md grew a "File-edge composites" section, wiki/utils.md grew "Driving gen pipelines" and "Block I/O (Node-only)" sections, wiki/benchmarks.md was rewritten to match the actual bench/ contents, and wiki/Home.md index links the new helpers and components.

4.1.1 — 2026-05-24

Patch release. A performance release: the four compositors now share one sync-when-possible executor, and a memory-growth bug on backpressured many() expansion is fixed. No public API change and no behavior change — the full test suite passes identically before and after.

Internal: the shared executor

  • Unified exec engine (src/exec.js). gen(), fun(), asStream(), and asWebStream() previously each ran their own fused-pipeline executor; the Node and Web wrappers used an async function applyFns that returned a Promise on every call and awaited between every push. They now share a single sync-when-possible, value-or-promise executor: it threads a value through the function-list and emits via a push callback, staying fully synchronous until the first real promise (an async stage, a thenable value, or a backpressuring push) appears — then it suspends and resumes. Synchronous pipelines no longer pay a per-item microtask. exec is internal (not exported).
  • gen() is now a push→pull bridge over the shared executor rather than a recursive async function*; the legacy trampoline is retained as gen.next for compatibility but is no longer used internally.
  • The bounded-queue guarantee is unchanged: the executor honors the push return value, so when an enqueue backpressures it suspends at that push and the readable queue stays at hwm + 1 regardless of how many values one input produces.

Fixed

  • O(n)→O(1) allocation on backpressured many(). When a single input expanded to a chunk-sized many([...]) and the consumer backpressured from the first element, the many() (and flush) traversal allocated one closure + promise per remaining element — O(N) live allocations, observable as heavy GC on large fan-outs (e.g. a JSON tokenizer emitting one many(tokens) per input buffer). Both paths are now resumable, allocating one closure per actual suspension. A heap-delta regression gate (bench/json-exec/correctness/bounded-alloc.js) pins the allocation flat across N = 1e4…1e6.

Performance

  • Executor-layer microbenchmarks (synthetic, nano-bench): asStream ≈ 26% faster, asWebStream ≈ 10% faster than the old applyFns path; exec is the fastest of the in-process fun/gen/exec trio.
  • End-to-end against stream-json via npm link: real createReadStream file pipelines 20–26% faster (json-filter, json-transform, json-count); a chunk-size sweep that previously blew up on whole-document input is now flat across chunk sizes.

Notes

  • No source change is required to benefit — the gains are automatic. See the updated Migration guide § 4 and asStream / asWebStream for the revised backpressure description (the earlier "~40% async penalty" caveat no longer applies).

4.1.0 — 2026-05-22

Minor release. Web Streams parity across the utility surface. Every Node-substrate primitive now has a Web counterpart with matching contract; substrate-agnostic helpers (dataSource, stream type guards) are exposed on every subpath.

New API

  • readableWebStreamFrom(iterable | options) in src/utils/readableWebStreamFrom.js. Web Streams counterpart to readableFrom(). Accepts a plain iterable, async iterable, iterator, 0-ary function (sync or async), or {iterable, strategy?} options object. Returns a ReadableStream. Per-item backpressure via desiredSize/pull(). Speaks the chain protocol on the producer side (returned none/null/undefined is skipped, stop terminates, many([...]) fans out, finalValue(v) is unwrapped). For the plain iterable case the platform's ReadableStream.from() is enough; reach for readableWebStreamFrom when you need function-source, promise-resolution, or chain-protocol awareness.

  • reduceWebStream(reducer, initial) / reduceWebStream(options) in src/utils/reduceWebStream.js. Web Streams counterpart to reduceStream(). Returns {writable, result, accumulator} — write into writable, await result for the final accumulator (resolves on clean close, rejects on abort or reducer error), or read the running value any time via the accumulator getter. Reducer is called with this bound to the return object so this.accumulator works inside (parity with reduceStream).

  • parserWebStream(options?) in src/jsonl/parserWebStream.js. Web Streams counterpart to parserStream. One-liner over asWebStream(parser({...})). Same reviver / ignoreErrors contract. Emitted records are {key, value} where key is the zero-based input line index.

  • stringerWebStream(options?) in src/jsonl/stringerWebStream.js. Web Streams counterpart to stringerStream. Implemented as a TransformStream because JSON.stringify is synchronous — the substrate's flush() callback handles the suffix/emptyValue emit, and there's no value in routing terminal text-emission through applyFns's per-chunk Promise allocation (stringer sits downstream of user code, not between intermediate function stages).

  • dataSource(fn) on /web and /core. Moved to src/dataSource.js (substrate-agnostic). Re-exported from all three subpath entries (stream-chain, stream-chain/web, stream-chain/core) and attached as chain.dataSource on each.

  • Node stream type guards in defs.js. isReadableNodeStream, isWritableNodeStream, isDuplexNodeStream joined the Web guards. Shape-based (no node:stream import), so callable from any substrate without pulling Node Streams into a browser bundle. Closes the symmetry with the Web guards (which had been exported since 4.0.0).

Fixes

  • parser({ignoreErrors: true}) correctly drops bad lines silently. The wiki documented "all JSON parsing errors are ignored silently", but the wrapper was emitting {key, value: defs.none} envelopes for unparseable lines — leaking the internal none sentinel to userland. Fix: src/jsonl/parser.js now returns defs.none from the wrapper when parseFn returns none, letting asStream / asWebStream's filter machinery drop the envelope. Both parserStream and parserWebStream inherit the fix through the shared parser() core.

Internal

  • Modernization sweep: options && options.X → options?.X across the source tree (20 sites, 10 files). For paired fallback chains, switched || to ?? only after per-site analysis confirmed the left-side type was object-or-undefined (QueuingStrategy, reviver-or-function). For initial-accumulator presence checks ('initial' in options), kept the explicit in operator — ?? would coalesce explicit null accumulators to the default, losing the semantic distinction.

  • reduceStream / reduceWebStream cleanup. Dropped a band-aid 'initial' in options && options.initial !== undefined check that worked around a normalization clobber bug. The wrap step now only writes initial into options when it was actually passed positionally, and a clean 'initial' in options presence check stands on its own. Both substrates aligned.

  • Stream type guards consolidated in defs.js. Node guards moved from inline definitions in src/index.js into defs.js alongside the Web guards. src/index.js now destructures them from the defs namespace like the Web guards.

  • dataSource extracted to its own module. Was inline in src/index.js. Now src/dataSource.js + .d.ts, parallel to gen.js / fun.js.

  • Wiki Node↔Web mapping table added to wiki/utils.md and wiki/jsonl.md headers. wiki/defs.md gained a "Stream type guards" section covering both substrates.

Tests

Test count: 322 tests / ~620 asserts on Node (up from 282 / 562 in 4.0.2). Browser bucket: 176 tests (up from 137). New suites:

  • tests/web/test-readableWebStreamFrom.js and tests/web/test-readableWebStreamFrom-lifecycle.js — smoke, protocol features, backpressure, cancel-halts-pump, error propagation.
  • tests/web/test-reduceWebStream.js — positional + options forms, sync + async reducers, abort, reducer-throws, this.accumulator Node-parity, live accumulator getter.
  • tests/web/test-jsonl-parserWebStream.js — smoke, chunked multi-byte boundaries, bad-JSON propagation, ignoreErrors drops bad lines, reviver, roundtrip via stringerWebStream.
  • tests/web/test-jsonl-stringerWebStream.js and tests/web/test-jsonl-stringerWebStream-lifecycle.js — smoke, custom-separator edges, abort, cancel, replacer-throws, empty-stream-flush.
  • tests/core/test-dataSource.js — substrate-agnostic dataSource behavior, per-subpath re-export.
  • tests/node/test-jsonl-parserStream.js — added ignoreErrors test that pins the silently-drops-bad-lines contract on the Node side.

All four runtimes green: Node 26 / Bun 1.3.14 / Deno 2.7 / headless Chromium via tape-six-playwright. ts-check + js-check + Prettier clean.

4.0.2 — 2026-05-21

Patch release. Restores fixUtf8Stream() portability across runtimes that don't expose node:string_decoder.

Fixes

  • fixUtf8Stream() no longer breaks browser consumers. 4.0.1's import {StringDecoder} from 'node:string_decoder' at module top crashed every browser ESM consumer of a fixUtf8Stream user on load — before any test or code ran. The bare node: specifier fails resolution in browsers, with no try/catch surface above.

    Fix: src/utils/fixUtf8Stream.js now defaults to a TextDecoder-backed factory (WHATWG standard, available in every supported runtime) and, on Node specifically, asynchronously upgrades to StringDecoder via import('node:string_decoder').then(...). Bun and Deno stay on TextDecoder per benchmark (Bun: roughly tied; Deno's TextDecoder actually beats its node-compat StringDecoder). Runtime detection uses the same idiom as tape-six's utils/timer.js.

    No top-level await — tests/node/test-cjs.cjs (require-of-ESM interop) stays green; an earlier TLA shape broke it across Node, Bun, and Deno during exploration.

    Decision data: bench/decoder-stringdecoder-vs-textdecoder.js (kept in-repo). Node 26: StringDecoder 2–4× faster on the decoder hot path; Bun 1.3.14: wash; Deno 2.7: TextDecoder beats StringDecoder via node-compat.

New API

  • whenReady() named export. Returns a Promise<void> that resolves when the Node-side upgrade has landed (or immediately on non-Node). Optional — fixUtf8Stream() always works; the dispatcher reads the current implementation at call time, so streams composed before the upgrade get the TextDecoder stage (correct, small overhead) and streams composed after get the StringDecoder stage. await whenReady() before composition guarantees the Node fast path from the first call.

Types

src/utils/fixUtf8Stream.d.ts now types the chunk parameter as string | Uint8Array | typeof none (was string | Buffer | typeof none). On Node, Buffer extends Uint8Array, so existing Node consumers still type-check. The /// <reference types="node" /> directive is gone — the file no longer depends on Node-only types.

4.0.1 — 2026-05-20

Patch release. Two cross-runtime compatibility fixes surfaced during a multi-runtime verification pass (Node 26, Bun 1.3.14, Deno 2.7, headless Chromium via tape-six-playwright).

Fixes

  • asWebStream() crash on Bun ≤1.3.14. src/asWebStream.js listens to controller.signal inside the WritableStream sink's start(controller) callback to wake a backpressured write when the writer aborts — without it, an aborted writer with a pending drain would deadlock. The signal is per WHATWG Streams §4.5.2 and works on Node 26 and Deno 2.7, but Bun 1.3.14's WritableStreamDefaultController returns undefined for .signal, causing every asWebStream instantiation on Bun to throw TypeError: undefined is not an object (evaluating 'controller.signal.addEventListener').

    Fix: optional-chained the listener (controller.signal?.addEventListener(...)). Bun loses the abort-wakeup safety net until upstream lands the fix — a consumer that aborts a writer with a pending backpressured write would deadlock, rare in practice. Normal write/close/cancel paths are unaffected.

    Upstream fix in flight: oven-sh/bun#31156 / PR #31157. The PR cites stream-chain v4 by name as the motivating downstream case and includes a regression test labeled "unblocks a pending write() from an abort listener — the stream-chain v4 use case." When the PR ships in Bun 1.3.15+, the optional chaining becomes a no-op and the abort-wakeup safety net is restored across all four runtimes.

  • fixUtf8Stream() bare string_decoder import. src/utils/fixUtf8Stream.js did import {StringDecoder} from 'string_decoder'. Node and Bun resolve this to the built-in fine, but Deno requires the explicit node: prefix for any built-in module import (TypeError: Import "string_decoder" not a dependency). Fix: import {StringDecoder} from 'node:string_decoder'. ESM hygiene anyway — the bare specifier has been deprecated in favor of node: prefixes since Node 16.

Internal — test suite reorganization

The test directory is now organized by execution environment, mirroring tape-six's configuration schema:

  • tests/core/ — substrate-agnostic tests (use the runChain(transducers, input) helper from tests/web-helpers.js, which drives a /web chain internally). Runs in browser AND CLI.
  • tests/web/ — Web Streams substrate. Runs in browser AND CLI.
  • tests/node/ — Node Streams substrate. Runs only in CLI.

Configured via tape6.tests (core + web) and tape6.cli (node) in package.json. The split lets the same test set drive Node 26, Bun 1.3.14, Deno 2.7, and headless Chromium without per-runtime patterns in the npm scripts.

New: browser testing via tape-six-playwright

npm run test:browser drives headless Chromium through tape-six-playwright, auto-starting tape6-server on port 55555 (env-overridable to avoid the default 3000 collision). Runs the browser-safe subset: 113 tests / 166 asserts covering asWebStream, /web chain, webStreamPuller, and defs in a real browser engine.

Two Bun-specific feature-probe skips were added in this release — tests/web/test-asWebStream-lifecycle.js and tests/web/test-webStreamPuller.js each detect the relevant Bun spec gaps at test start and t.skipTest(...) rather than failing. They auto-unskip when Bun ships the matching fixes, reported as skipped: 2 in npm run test:bun output for visibility.

Verification

All four runtimes green:

Runtime tests / asserts Status
Node 26 258 / 534 all pass
Bun 1.3.14 258 / 532 all pass (2 skipped via feature-probe)
Deno 2.7 258 / 534 all pass
Browser (Chromium) 113 / 166 all pass

Also covers Ubuntu 26.04: Playwright's manifest stops at ubuntu24.04, so the npm install postinstall fails to download Chromium on fresh 26.04. Workaround documented in AGENTS.md: npm install --ignore-scripts then PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 npx playwright install chromium. Install-time only; runtime needs no env.

4.0.0 — 2026-05-20

Major release. Substantial substrate and API expansion; small but breaking adjustments for CJS callers and existing consumers. See the dedicated Migration guide for a step-by-step upgrade walkthrough.

Breaking changes

  • ESM-only distribution. The package is "type": "module". The 3.x fallback that exposed chain as a callable from require('stream-chain') is gone — CJS callers now destructure: const {chain} = require('stream-chain'). Was the only required source change for most callers.
  • Node 22+ floor. Drops Node 16, 18, 20. Current supported majors are 22, 24, 26 (latest minor of each).
  • Per-item backpressure semantic shift. When a function returns many(...) or a generator yields multiple values, the runtime now awaits the drain signal between every push. Queue stays at hwm + 1 regardless of expansion factor. Cost: ~40% throughput hit on synchronous-heavy pipelines (the applyFns path is now async end-to-end). Benefit: bounded memory under unbounded expansion. No source change needed.
  • Generators-yield-plain convention. Generators (sync function* and async async function*) must yield plain values only — not none, stop, many(...), or finalValue(...). 3.x was inconsistent about handling these from generator output; 4.x is explicit that the behavior is undefined.

Subpath split: /node, /web, /core

The default stream-chain entry resolves to stream-chain/node (the canonical Node Streams runtime). Two new substrate-specific subpaths:

  • stream-chain/web — a native Web Streams chain. Returns {readable, writable} pairs built on ReadableStream / WritableStream. No node:stream interop layer — browser-safe and works in any environment with the Web Streams substrate.
  • stream-chain/core — substrate-free composition. Returns a callable async-iterable factory: (input?) => AsyncGenerator<R>. Useful for gen()/fun() composition without dragging in either substrate.

Existing 3.x code keeps working without source changes — the split is purely additive.

New: asWebStream(fn[, options])

Web Streams counterpart to asStream(). Returns a native {readable, writable} duplex pair (NOT a TransformStream — its transform() callback can't suspend mid-call for per-item drain). Per-item backpressure via a custom pull() callback that wakes a pending-drain Promise. Options accept Web Streams' standard QueuingStrategy shape: {strategy?, readableStrategy?, writableStrategy?}. Lifecycle matches TransformStream: reader.cancel(reason) propagates to the writable as an error; writer.abort(reason) errors both sides and unblocks pending backpressure; user-function errors propagate to both sides. See asWebStream().

Web Streams type guards in defs.js

isReadableWebStream, isWritableWebStream, isDuplexWebStream consolidated into stream-chain/defs.js as the single canonical source. Re-exported from stream-chain (and chain.X) and stream-chain/web.

New utilities: makeStreamPuller / makeWebStreamPuller

makeStreamPuller(readable) wraps a Node Readable as a non-destructive async iterator (thin facade over readable.iterator({destroyOnReturn: false})). Preserves the original 'error' value (no AbortError wrapping), synthesizes Error('Premature close') on destroy-without-end, and breaks out of for await without destroying the source.

makeWebStreamPuller(readable) wraps a Web ReadableStream similarly (built on stream[Symbol.asyncIterator]({preventCancel: true})) plus a cancel(reason) extension method — the iterator-protocol return() can't carry a cancel reason cleanly.

Both intended for downstream consumers (stream-join, stream-sorting) that need original-error preservation. Both implement [Symbol.asyncIterator] directly so for await works without ceremony. Live at stream-chain/utils/streamPuller.js and stream-chain/utils/webStreamPuller.js. See makeStreamPuller() and makeWebStreamPuller().

Lifecycle bug fixes in asStream / asWebStream

Five distinct issues found and fixed during the post-merge cleanup pass. Each ships with regression tests in tests/test-asStream-lifecycle.js and tests/test-asWebStream-lifecycle.js (257 / 534 asserts total, up from 237 / 513 in 3.6.3):

  • asWebStream writer.abort() deadlock when a sink write was awaiting backpressure. Spec serializes sink callbacks, so the abort sink couldn't fire to unblock the pending drain. Fix: listen to controller.signal in start() (the signal aborts before sink callbacks settle).
  • asWebStream reader.cancel() left writes silently failing. Should match TransformStream: propagate the cancel reason to the writable as an error so the producer learns. As a side effect, mid-chain errors in /web chains now reach the producer.
  • asWebStream double-close on the readable controller after cancel. Idempotent closeReadable / errorReadable helpers introduced.
  • asWebStream user-function errors weren't propagating to the readable. Downstream pipeTo'd stages would hang waiting for input. Fix: errorReadable(error) in write / close sink catch blocks before rethrowing.
  • asStream stream.destroy() deadlock while in-flight _write was awaiting paused. Node doesn't signal in-flight writes either. Fix: custom destroy(err, callback) sink in the Duplex options that calls resume().

Internal: type-guard + helper consolidation

  • isNodeStream defensive helper in src/index.js removed — no longer needed once web-stream guards drop the !isNodeStream check (Node and Web streams have non-overlapping method sets).
  • asStream.js and asWebStream.js simplified: dropped the inline "is plain value" fast-path (sync-when-possible processValue covers it), dropped duplicated stop-handler boilerplate, hoisted helpers (unblockDrain, closeReadable, errorReadable, absorbStop). Net: asStream.js 271 → 248 lines, asWebStream.js 302 → 282 lines.
  • Many-array iteration in the slow path no longer allocates an array iterator — walks the values directly with promise-chaining only when needed.

Test infrastructure

  • Tests renamed from .mjs / .mts to .js / .ts (the package is now "type": "module", so the explicit extensions are redundant).
  • New lifecycle test files: tests/test-asStream-lifecycle.js, tests/test-asWebStream-lifecycle.js, tests/test-streamPuller.js, tests/test-webStreamPuller.js.

Documentation

Conventions captured for the fleet

  • Special values in generators (don't yield none / many(...); stop / finalValue(...) supported) — documented in wiki/defs.md § Special values in generators.
  • If a module declares export default X, it must also declare export {X} for the same value. Fleet-wide rule, documented as topics/esm-default-export-with-named-mirror and slice 17 of the fleet-conventions-bundle.

3.6.3 — 2026-05-13

TypeScript inference fixes for nested and cross-type pipe compositions. Pure type-system patch — no runtime changes. Two distinct bugs found via strict probes of the existing 3.6.2 typings:

chain-of-chain W / R propagation

Ret<ChainOutput<W, R>> and Arg0<ChainOutput<W, R>> were collapsing to any because ChainOutput<W, R> = Omit<Duplex, ...> & ChainOutputExtensions<R> is structurally assignable to Duplex, so the broad F extends Readable | Transform | Duplex ? any branch in both Arg0 and Ret matched before any chain-specific check. W was also not structurally present (the alias parameter was unused in the body).

Fix: mirror the TypedDuplex phantom pattern. Added __streamTypeW(): W and __streamTypeR(): R phantom methods to ChainOutputExtensions (now parameterized by both W and R); added F extends ChainOutput<infer W, any> / F extends ChainOutput<any, infer R> as the first branch in Arg0 and Ret so chain-of-chain composition recovers both type parameters.

OutputType not distributing over fun(...) return shape

fun(...fns) returns (arg) => Many<R> | Promise<Many<R>>. When that function appeared inside another fun, gen, or chain, the outer's Ret ran OutputType<F> over the union — and UnpackReturnType checked ReturnType<F> extends Promise<unknown> against the whole union. The check failed on the Many<R> arm, the unwrap fell through unchanged, and the inner Promise<Many<R>> leaked downstream as R | Promise<Many<R>>. For fun-of-fun the pollution compounded to Many<R | Promise<Many<R>>> | Promise<Many<R | Promise<Many<R>>>>.

Fix: rewrite UnpackReturnType as a thin shim over a naked-T inner alias that distributes over union members and recurses on Promise<infer U>. Same form (AsyncGenerator -> Generator -> Promise-recurse -> T) handles Promise<Promise<X>> and the union arms uniformly.

Test coverage — composition matrix

Every pipe-like API (chain, fun, gen, asStream) is now exercised in every structurally-permitted position (first / middle / last) of every other pipe-like API. New tests cover:

  • Nested-position guards: chain([fn, X, fn]), fun(fn, X, fn), gen(fn, X, fn) for X in {fun, gen, asStream, nested chain}.
  • First-position guards: chain output as first item, fun(fun-out, fn), gen(gen-out, fn), plus the cross-type pairings.
  • Threading verification: a deliberately-mismatched-middle repro confirmed TypeScript pinpoints the mismatch on the middle item via the ChainList / FnList Ret<F1, I> walk.

Typings test count: 56 → 68 (tests/test-typings-chain.mts + tests/test-typings-gen-fun.mts).

Fleet conventions

Tarball now includes AGENTS.md and ARCHITECTURE.md alongside the existing llms.txt / llms-full.txt per the tarball AI-docs convention — useful for AI tools in downstream projects discovering the package via npm install.

Dev deps

@types/node ^25.6.0 -> ^25.7.0, nano-benchmark ^1.0.15 -> ^1.0.16, tape-six ^1.8.0 -> ^1.9.0, tape-six-proc ^1.2.8 -> ^1.2.9.

Earlier releases

Per-release cliff-notes reproduced from README.md. Pre-3.6.3 entries weren't written in the long-form style; the README versions are the canonical record for those versions.

  • 3.6.2 Improved TS typings: ChainOutput<W, R> propagates R to events and methods (thx Scover). Updated deps.
  • 3.6.1 Technical release: updated deps.
  • 3.6.0 Performance: sync-first fun() (~2.5× faster for sync pipelines, now returns Many | Promise<Many>). Sync fast path in gen() (~1.6× faster). Documented null/undefined handling differences. Wiki: renamed V2 files for Windows compatibility.
  • 3.5.1 Fixed finish event not firing after stop. Web stream detection uses duck-typing instead of instanceof (supports non-standard web streams) (thx Alex Yang). Performance: unified fast path in asStream().
  • 3.5.0 Variadic combineMany() and combineManyMut(). Fixed readableFrom() unhandled rejection bug. Improved TS typings, docs, and package.json metadata.
  • 3.4.1 Improved TS typings, added TypeScript typing tests, cleaned up dead code.
  • 3.4.0 Added Many-related helpers and chainUnchecked() for TS.
  • 3.3.2 Technical release: updated deps, more tests.
  • 3.3.1 Minor enhancement: more flexible split on lines.
  • 3.3.0 Added a way to ignore JSON parsing errors silently.
  • 3.2.0 Added TS typings and clearFunctionList().
  • 3.1.0 Added a seamless support for web streams.
  • 3.0.1 First release of 3.0. See wiki for details.
  • 3.0.0 New major version. Unreleased.
  • 2.2.5 Relaxed the definition of a stream (thx Rich Hodgkins).
  • 2.2.4 Bugfix: wrong const-ness in the async generator branch (thx Patrick Pang).
  • 2.2.3 Technical release. No need to upgrade.
  • 2.2.2 Technical release. No need to upgrade.
  • 2.2.1 Technical release: new symbols namespace, explicit license (thx Keen Yee Liau), added Greenkeeper.
  • 2.2.0 Added utilities: take, takeWhile, skip, skipWhile, fold, scan, Reduce, comp.
  • 2.1.0 Added simple transducers, dropped Node 6.
  • 2.0.3 Added TypeScript typings and the badge.
  • 2.0.2 Workaround for Node 6: use 'finish' event instead of _final().
  • 2.0.1 Improved documentation.
  • 2.0.0 Upgraded to use Duplex instead of EventEmitter as the base.
  • 1.0.3 Improved documentation.
  • 1.0.2 Better README.
  • 1.0.1 Fixed the README.
  • 1.0.0 The initial release.

Clone this wiki locally

⌂ 换网址