Home

Dashboard

About

stream-fork is a toolkit of 1→N stream combinators — sinks that distribute every chunk to N downstream sinks under different dispatch shapes, with proper backpressure handling. Three primitives cover the three useful control-flow shapes; a small set of picker helpers compose with route into common load-balance, shard, and routing patterns.

Available in two flavors that share the same options surface: Node Streams (the default stream-fork entry — wraps Writable) and Web Streams (stream-fork/web — wraps WritableStream). The Web fork is a backpressure-preserving generalization of ReadableStream.tee() to N outputs.

stream-fork has zero runtime dependencies. It is a sibling to stream-join (N→1) and stream-json in the stream-chain family. Distributed under the New BSD license.

Documentation

Main components

• fork — broadcast: every chunk to every live output; the slowest gates upstream. The default export — import fork from 'stream-fork' (Node) or import fork from 'stream-fork/web' (Web) returns this.
• route — single-target dispatch: a per-chunk pick(chunk[, encoding]) selects exactly one output.
• filter — subset broadcast: one predicate per output decides whether that output receives the chunk.

Helpers

• utils (pickRoundRobin, pickByHash, pickByKey, pickFirstMatch) — picker factories under stream-fork/utils/ that compose with route to express round-robin load balance, stable hash sharding, explicit key→index routing, and priority routing with catch-all. Shared between Node and Web trees.

Other

• Release notes — detailed change history.

Installation

npm i stream-fork

Quick example (Node Streams)

import fork from 'stream-fork';
import fs from 'node:fs';
import zlib from 'node:zlib';

const gzip = zlib.createGzip();
gzip.pipe(fs.createWriteStream('log.txt.gz'));

// push every chunk to both the gzip chain and stdout
dataSource.pipe(fork([gzip, process.stdout]));

Quick example (Web Streams)

import fork from 'stream-fork/web';

// dataSource is a ReadableStream; sinkA / sinkB are WritableStreams
await dataSource.pipeTo(fork([sinkA, sinkB]));

Engines

• Node.js 22+ (Node Streams flavor).
• Modern browsers, Deno 2+, Bun 1+ (Web Streams flavor — needs a WritableStream global).
• Cross-runtime checks: npm run test:bun, npm run test:deno, npm run test:browser.