stream-chain

library4.2.3jsnpmunverified

Build object-stream pipelines from plain functions, generators, Node streams, or Web streams with automatic backpressure. Version 4.2.3, released March 2025, requires Node >=22. Unlike 'pump' or 'pipeline', every stage can be a sync/async function, generator, or stream — no boilerplate. Ships TypeScript types, zero dependencies, and runs on Node, Bun, and Deno. Includes built-in JSONL parsing/writing. Actively maintained with weekly releases.

devops database

npm install stream-chain

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STREAM-CHAIN

stream-chain

devopsjavascriptv4.2.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

chain

✓ import chain from 'stream-chain'

✗ const { chain } = require('stream-chain')

Default export. CJS require() works but only as 'stream-chain' default — never destructure.

Chain

✓ import type { Chain } from 'stream-chain'

✗ import { Chain } from 'stream-chain'

Chain is a type (the Duplex subclass). Import with 'import type' in TypeScript.

gen

✓ import { gen } from 'stream-chain'

✗ import gen from 'stream-chain'

Named export, not default. Generates an async generator from an array of functions.

Creates a JSONL processing pipeline: parse, filter inactive records, enrich asynchronously, stringify, and write to file with backpressure.

import chain from 'stream-chain'; import { chain as fileChain } from 'stream-chain/file.js'; import { parser } from 'stream-chain/jsonl/parser.js'; import { stringify } from 'stream-chain/jsonl/stringify.js'; import { createWriteStream } from 'node:fs'; import { pipeline } from 'node:stream/promises'; const inputFile = process.env.INPUT_FILE ?? 'data.jsonl'; const outputFile = process.env.OUTPUT_FILE ?? 'output.jsonl'; // Build a pipeline: read JSONL -> filter -> enrich -> write JSONL const p = chain([ parser(), ({ value }) => (value.active ? value : chain.none), async (record) => ({ ...record, enriched: true }), stringify(), ]); // Pipe file into pipeline and out to another file const source = createReadStream(inputFile); const dest = createWriteStream(outputFile); pipeline(source, p, dest).then(() => console.log('done'));

Debug

Known issues

breakingError [ERR_REQUIRE_ESM]: require() of ES Module not supported. stream-chain@4.x is ESM-only.

fix

Use import, or downgrade to stream-chain@3.x (CJS).

affects: >=4.0.0

breakingTypeError [ERR_INVALID_ARG_TYPE]: The 'chunk' argument must be of type object or an instance of Buffer or Uint8Array. Received undefined

fix

Ensure all functions in the chain return a value or explicitly return chain.none to drop a record. Do not return undefined.

affects: >=4.0.0

deprecatedWarning: stream-chain/jsonl/read.js is deprecated. Use stream-chain/jsonl/file/parser.js instead.

fix

Replace import 'stream-chain/jsonl/read.js' with 'stream-chain/jsonl/file/parser.js'.

affects: >=4.0.0 <5.0.0

gotchaMemory grows unexpectedly when using chain.many() instead of generators for fan-out.

fix

Use async generators (function* or async function*) for stages that emit multiple values per input; chain.many() buffers all values in memory.

affects: >=1.0.0

gotchaPipeline stalls silently when a stage throws synchronously inside a generator function.

fix

Upgrade to 4.3.0+ or wrap generator body in try-catch and emit errors via the stream's 'error' event.

affects: >=3.0.0 <4.3.0

breakingTypeError: chain is not a function after importing from 'stream-chain/web'.

fix

The /web subpath exports a different API (Web Streams). Use import chain from 'stream-chain' for Node streams, or import { chain } from 'stream-chain/web'.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'pipe')

Using chain() with an empty array or forgetting to call chain() (it returns a stream).

fix

Pass an array of stages to chain(): const pipeline = chain([stage1, stage2]);

Error [ERR_STREAM_PREMATURE_CLOSE]: Premature close

Source stream ends before all data is consumed, or pipeline is manually destroyed while processing.

fix

Use pipeline() from 'stream/promises' to properly manage backpressure and cleanup: await pipeline(source, chain(...), dest);

TypeError: chain.none is not a function

Using chain.none inside a stage that returns a function instead of calling it.

fix

chain.none is a symbol, not a function. Return it directly: return chain.none;

SyntaxError: Unexpected token 'export' (When using require)

stream-chain@4 is ESM-only, but code is using require() (CommonJS).

fix

Convert to ES modules (set type: module in package.json) and use import, or downgrade to stream-chain@3.

Upgrade

Version history

4.2.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node