The node:stream/iter module provides a streaming API built on iterables\nrather than the event-driven Readable/Writable/Transform class hierarchy,\nor the Web Streams ReadableStream/WritableStream/TransformStream interfaces.
This module is available only when the --experimental-stream-iter CLI flag\nis enabled.
Streams are represented as AsyncIterable<Uint8Array[]> (async) or\nIterable<Uint8Array[]> (sync). There are no base classes to extend -- any\nobject implementing the iterable protocol can participate. Transforms are plain\nfunctions or objects with a transform method.
Data flows in batches (Uint8Array[] per iteration) to amortize the cost\nof async operations.
import { from, pull, text } from 'node:stream/iter';\nimport { compressGzip, decompressGzip } from 'node:zlib/iter';\n\n// Compress and decompress a string\nconst compressed = pull(from('Hello, world!'), compressGzip());\nconst result = await text(pull(compressed, decompressGzip()));\nconsole.log(result); // 'Hello, world!'\nconst { from, pull, text } = require('node:stream/iter');\nconst { compressGzip, decompressGzip } = require('node:zlib/iter');\n\nasync function run() {\n // Compress and decompress a string\n const compressed = pull(from('Hello, world!'), compressGzip());\n const result = await text(pull(compressed, decompressGzip()));\n console.log(result); // 'Hello, world!'\n}\n\nrun().catch(console.error);\nimport { open } from 'node:fs/promises';\nimport { text, pipeTo } from 'node:stream/iter';\nimport { compressGzip, decompressGzip } from 'node:zlib/iter';\n\n// Read a file, compress, write to another file\nconst src = await open('input.txt', 'r');\nconst dst = await open('output.gz', 'w');\nawait pipeTo(src.pull(), compressGzip(), dst.writer({ autoClose: true }));\nawait src.close();\n\n// Read it back\nconst gz = await open('output.gz', 'r');\nconsole.log(await text(gz.pull(decompressGzip(), { autoClose: true })));\nconst { open } = require('node:fs/promises');\nconst { text, pipeTo } = require('node:stream/iter');\nconst { compressGzip, decompressGzip } = require('node:zlib/iter');\n\nasync function run() {\n // Read a file, compress, write to another file\n const src = await open('input.txt', 'r');\n const dst = await open('output.gz', 'w');\n await pipeTo(src.pull(), compressGzip(), dst.writer({ autoClose: true }));\n await src.close();\n\n // Read it back\n const gz = await open('output.gz', 'r');\n console.log(await text(gz.pull(decompressGzip(), { autoClose: true })));\n}\n\nrun().catch(console.error);\nAll data in this API is represented as Uint8Array bytes. Strings\nare automatically UTF-8 encoded when passed to from(), push(), or\npipeTo(). This removes ambiguity around encodings and enables zero-copy\ntransfers between streams and native code.
Each iteration yields a batch -- an array of Uint8Array chunks\n(Uint8Array[]). Batching amortizes the cost of await and Promise creation\nacross multiple chunks. A consumer that processes one chunk at a time can\nsimply iterate the inner array:
for await (const batch of source) {\n for (const chunk of batch) {\n handle(chunk);\n }\n}\nasync function run() {\n for await (const batch of source) {\n for (const chunk of batch) {\n handle(chunk);\n }\n }\n}\nTransforms come in two forms:
\nStateless -- a function (chunks, options) => result called once per\nbatch. Receives Uint8Array[] (or null as the flush signal) and an\noptions object. Returns Uint8Array[], null, or an iterable of chunks.
Stateful -- an object { transform(source, options) } where transform\nis a generator (sync or async) that receives the entire upstream iterable\nand an options object, and yields output. This form is used for\ncompression, encryption, and any transform that needs to buffer across\nbatches.
Both forms receive an options parameter with the following property:
options.signal <AbortSignal> An AbortSignal that fires when the pipeline\nis cancelled, encounters an error, or the consumer stops reading. Transforms\ncan check signal.aborted or listen for the 'abort' event to perform\nearly cleanup.The flush signal (null) is sent after the source ends, giving transforms\na chance to emit trailing data (e.g., compression footers).
// Stateless: uppercase transform\nconst upper = (chunks) => {\n if (chunks === null) return null; // flush\n return chunks.map((c) => new TextEncoder().encode(\n new TextDecoder().decode(c).toUpperCase(),\n ));\n};\n\n// Stateful: line splitter\nconst lines = {\n transform: async function*(source) {\n let partial = '';\n for await (const chunks of source) {\n if (chunks === null) {\n if (partial) yield [new TextEncoder().encode(partial)];\n continue;\n }\n for (const chunk of chunks) {\n const str = partial + new TextDecoder().decode(chunk);\n const parts = str.split('\\n');\n partial = parts.pop();\n for (const line of parts) {\n yield [new TextEncoder().encode(`${line}\\n`)];\n }\n }\n }\n },\n};\nThe API supports two models:
\nPull -- data flows on demand. pull() and pullSync() create lazy\npipelines that only read from the source when the consumer iterates.
Push -- data is written explicitly. push() creates a writer/readable\npair with backpressure. The writer pushes data in; the readable is consumed\nas an async iterable.
Pull streams have natural backpressure -- the consumer drives the pace, so\nthe source is never read faster than the consumer can process. Push streams\nneed explicit backpressure because the producer and consumer run\nindependently. The highWaterMark and backpressure options on push(),\nbroadcast(), and share() control how this works.
Push streams use a two-part buffering system. Think of it like a bucket\n(slots) being filled through a hose (pending writes), with a float valve\nthat closes when the bucket is full:
\n highWaterMark (e.g., 3)\n |\n Producer v\n | +---------+\n v | |\n [ write() ] ----+ +--->| slots |---> Consumer pulls\n [ write() ] | | | (bucket)| for await (...)\n [ write() ] v | +---------+\n +--------+ ^\n | pending| |\n | writes | float valve\n | (hose) | (backpressure)\n +--------+\n ^\n |\n 'strict' mode limits this too!\nSlots (the bucket) -- data ready for the consumer, capped at\nhighWaterMark. When the consumer pulls, it drains all slots at once\ninto a single batch.
Pending writes (the hose) -- writes waiting for slot space. After\nthe consumer drains, pending writes are promoted into the now-empty\nslots and their promises resolve.
\nHow each policy uses these buffers:
\n| Policy | \nSlots limit | \nPending writes limit | \n
|---|---|---|
'strict' | \nhighWaterMark | \nhighWaterMark | \n
'block' | \nhighWaterMark | \nUnbounded | \n
'drop-oldest' | \nhighWaterMark | \nN/A (never waits) | \n
'drop-newest' | \nhighWaterMark | \nN/A (never waits) | \n
Strict mode catches \"fire-and-forget\" patterns where the producer calls\nwrite() without awaiting, which would cause unbounded memory growth.\nIt limits both the slots buffer and the pending writes queue to\nhighWaterMark.
If you properly await each write, you can only ever have one pending\nwrite at a time (yours), so you never hit the pending writes limit.\nUnawaited writes accumulate in the pending queue and throw once it\noverflows:
\nimport { push, text } from 'node:stream/iter';\n\nconst { writer, readable } = push({ highWaterMark: 16 });\n\n// Consumer must run concurrently -- without it, the first write\n// that fills the buffer blocks the producer forever.\nconst consuming = text(readable);\n\n// GOOD: awaited writes. The producer waits for the consumer to\n// make room when the buffer is full.\nfor (const item of dataset) {\n await writer.write(item);\n}\nawait writer.end();\nconsole.log(await consuming);\nconst { push, text } = require('node:stream/iter');\n\nasync function run() {\n const { writer, readable } = push({ highWaterMark: 16 });\n\n // Consumer must run concurrently -- without it, the first write\n // that fills the buffer blocks the producer forever.\n const consuming = text(readable);\n\n // GOOD: awaited writes. The producer waits for the consumer to\n // make room when the buffer is full.\n for (const item of dataset) {\n await writer.write(item);\n }\n await writer.end();\n console.log(await consuming);\n}\n\nrun().catch(console.error);\nForgetting to await will eventually throw:
// BAD: fire-and-forget. Strict mode throws once both buffers fill.\nfor (const item of dataset) {\n writer.write(item); // Not awaited -- queues without bound\n}\n// --> throws \"Backpressure violation: too many pending writes\"\nBlock mode caps slots at highWaterMark but places no limit on the\npending writes queue. Awaited writes block until the consumer makes room,\njust like strict mode. The difference is that unawaited writes silently\nqueue forever instead of throwing -- a potential memory leak if the\nproducer forgets to await.
This is the mode that existing Node.js classic streams and Web Streams\ndefault to. Use it when you control the producer and know it awaits\nproperly, or when migrating code from those APIs.
\nimport { push, text } from 'node:stream/iter';\n\nconst { writer, readable } = push({\n highWaterMark: 16,\n backpressure: 'block',\n});\n\nconst consuming = text(readable);\n\n// Safe -- awaited writes block until the consumer reads.\nfor (const item of dataset) {\n await writer.write(item);\n}\nawait writer.end();\nconsole.log(await consuming);\nconst { push, text } = require('node:stream/iter');\n\nasync function run() {\n const { writer, readable } = push({\n highWaterMark: 16,\n backpressure: 'block',\n });\n\n const consuming = text(readable);\n\n // Safe -- awaited writes block until the consumer reads.\n for (const item of dataset) {\n await writer.write(item);\n }\n await writer.end();\n console.log(await consuming);\n}\n\nrun().catch(console.error);\nWrites never wait. When the slots buffer is full, the oldest buffered\nchunk is evicted to make room for the incoming write. The consumer\nalways sees the most recent data. Useful for live feeds, telemetry, or\nany scenario where stale data is less valuable than current data.
\nimport { push } from 'node:stream/iter';\n\n// Keep only the 5 most recent readings\nconst { writer, readable } = push({\n highWaterMark: 5,\n backpressure: 'drop-oldest',\n});\nconst { push } = require('node:stream/iter');\n\n// Keep only the 5 most recent readings\nconst { writer, readable } = push({\n highWaterMark: 5,\n backpressure: 'drop-oldest',\n});\nWrites never wait. When the slots buffer is full, the incoming write is\nsilently discarded. The consumer processes what is already buffered\nwithout being overwhelmed by new data. Useful for rate-limiting or\nshedding load under pressure.
\nimport { push } from 'node:stream/iter';\n\n// Accept up to 10 buffered items; discard anything beyond that\nconst { writer, readable } = push({\n highWaterMark: 10,\n backpressure: 'drop-newest',\n});\nconst { push } = require('node:stream/iter');\n\n// Accept up to 10 buffered items; discard anything beyond that\nconst { writer, readable } = push({\n highWaterMark: 10,\n backpressure: 'drop-newest',\n});\nA writer is any object conforming to the Writer interface. Only write() is\nrequired; all other methods are optional.
Each async method has a synchronous *Sync counterpart designed for a\ntry-fallback pattern: attempt the fast synchronous path first, and fall back\nto the async version only when the synchronous call indicates it could not\ncomplete:
if (!writer.writeSync(chunk)) await writer.write(chunk);\nif (!writer.writevSync(chunks)) await writer.writev(chunks);\nif (writer.endSync() < 0) await writer.end();\nwriter.fail(err); // Always synchronous, no fallback needed\nThe number of buffer slots available before the high water mark is reached.\nReturns null if the writer is closed or the consumer has disconnected.
The value is always non-negative.
" } ], "methods": [ { "textRaw": "`writer.end([options])`", "name": "end", "type": "method", "signatures": [ { "params": [ { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`signal` {AbortSignal} Cancel just this operation. The signal cancels only the pending `end()` call; it does not fail the writer itself.", "name": "signal", "type": "AbortSignal", "desc": "Cancel just this operation. The signal cancels only the pending `end()` call; it does not fail the writer itself." } ], "optional": true } ], "return": { "textRaw": "Returns: {PromiseSignal that no more data will be written.
" }, { "textRaw": "`writer.endSync()`", "name": "endSync", "type": "method", "signatures": [ { "params": [], "return": { "textRaw": "Returns: {number} Total bytes written, or `-1` if the writer is not open.", "name": "return", "type": "number", "desc": "Total bytes written, or `-1` if the writer is not open." } } ], "desc": "Synchronous variant of writer.end(). Returns -1 if the writer is already\nclosed or errored. Can be used as a try-fallback pattern:
const result = writer.endSync();\nif (result < 0) {\n writer.end();\n}\nPut the writer into a terminal error state. If the writer is already closed\nor errored, this is a no-op. Unlike write() and end(), fail() is\nunconditionally synchronous because failing a writer is a pure state\ntransition with no async work to perform.
Write a chunk. The promise resolves when buffer space is available.
" }, { "textRaw": "`writer.writeSync(chunk)`", "name": "writeSync", "type": "method", "signatures": [ { "params": [ { "textRaw": "`chunk` {Uint8Array|string}", "name": "chunk", "type": "Uint8Array|string" } ], "return": { "textRaw": "Returns: {boolean} `true` if the write was accepted, `false` if the buffer is full.", "name": "return", "type": "boolean", "desc": "`true` if the write was accepted, `false` if the buffer is full." } } ], "desc": "Synchronous write. Does not block; returns false if backpressure is active.
Write multiple chunks as a single batch.
" }, { "textRaw": "`writer.writevSync(chunks)`", "name": "writevSync", "type": "method", "signatures": [ { "params": [ { "textRaw": "`chunks` {Uint8Array[]|string[]}", "name": "chunks", "type": "Uint8Array[]|string[]" } ], "return": { "textRaw": "Returns: {boolean} `true` if the write was accepted, `false` if the buffer is full.", "name": "return", "type": "boolean", "desc": "`true` if the write was accepted, `false` if the buffer is full." } } ], "desc": "Synchronous batch write.
" } ], "displayName": "Concepts" }, { "textRaw": "The `stream/iter` module", "name": "the_`stream/iter`_module", "type": "module", "desc": "All functions are available both as named exports and as properties of the\nStream namespace object:
// Named exports\nimport { from, pull, bytes, Stream } from 'node:stream/iter';\n\n// Namespace access\nStream.from('hello');\n// Named exports\nconst { from, pull, bytes, Stream } = require('node:stream/iter');\n\n// Namespace access\nStream.from('hello');\nIncluding the node: prefix on the module specifier is optional.
Create an async byte stream from the given input. Strings are UTF-8 encoded.\nArrayBuffer and ArrayBufferView values are wrapped as Uint8Array. Arrays\nand iterables are recursively flattened and normalized.
Objects implementing Symbol.for('Stream.toAsyncStreamable') or\nSymbol.for('Stream.toStreamable') are converted via those protocols. The\ntoAsyncStreamable protocol takes precedence over toStreamable, which takes\nprecedence over the iteration protocols (Symbol.asyncIterator,\nSymbol.iterator).
import { Buffer } from 'node:buffer';\nimport { from, text } from 'node:stream/iter';\n\nconsole.log(await text(from('hello'))); // 'hello'\nconsole.log(await text(from(Buffer.from('hello')))); // 'hello'\nconst { Buffer } = require('node:buffer');\nconst { from, text } = require('node:stream/iter');\n\nasync function run() {\n console.log(await text(from('hello'))); // 'hello'\n console.log(await text(from(Buffer.from('hello')))); // 'hello'\n}\n\nrun().catch(console.error);\nSynchronous version of from(). Returns a sync iterable. Cannot accept\nasync iterables or promises. Objects implementing\nSymbol.for('Stream.toStreamable') are converted via that protocol (takes\nprecedence over Symbol.iterator). The toAsyncStreamable protocol is\nignored entirely.
import { fromSync, textSync } from 'node:stream/iter';\n\nconsole.log(textSync(fromSync('hello'))); // 'hello'\nconst { fromSync, textSync } = require('node:stream/iter');\n\nconsole.log(textSync(fromSync('hello'))); // 'hello'\nPipe a source through transforms into a writer. If the writer has a\nwritev(chunks) method, entire batches are passed in a single call (enabling\nscatter/gather I/O).
If the writer implements the optional *Sync methods (writeSync, writevSync,\nendSync), pipeTo() will attempt to use the synchronous methods\nfirst as a fast path, and fall back to the async versions only when the sync\nmethods indicate they cannot complete (e.g., backpressure or waiting for the\nnext tick). fail() is always called synchronously.
import { from, pipeTo } from 'node:stream/iter';\nimport { compressGzip } from 'node:zlib/iter';\nimport { open } from 'node:fs/promises';\n\nconst fh = await open('output.gz', 'w');\nconst totalBytes = await pipeTo(\n from('Hello, world!'),\n compressGzip(),\n fh.writer({ autoClose: true }),\n);\nconst { from, pipeTo } = require('node:stream/iter');\nconst { compressGzip } = require('node:zlib/iter');\nconst { open } = require('node:fs/promises');\n\nasync function run() {\n const fh = await open('output.gz', 'w');\n const totalBytes = await pipeTo(\n from('Hello, world!'),\n compressGzip(),\n fh.writer({ autoClose: true }),\n );\n}\n\nrun().catch(console.error);\nsource {Iterable} The sync data source....transforms <Function> | <Object> Zero or more sync transforms.writer <Object> Destination with write(chunk) method.options <Object>\n\n<number> Total bytes written.Synchronous version of pipeTo(). The source, all transforms, and the\nwriter must be synchronous. Cannot accept async iterables or promises.
The writer must have the *Sync methods (writeSync, writevSync,\nendSync) and fail() for this to work.
Create a lazy async pipeline. Data is not read from source until the\nreturned iterable is consumed. Transforms are applied in order.
import { from, pull, text } from 'node:stream/iter';\n\nconst asciiUpper = (chunks) => {\n if (chunks === null) return null;\n return chunks.map((c) => {\n for (let i = 0; i < c.length; i++) {\n c[i] -= (c[i] >= 97 && c[i] <= 122) * 32;\n }\n return c;\n });\n};\n\nconst result = pull(from('hello'), asciiUpper);\nconsole.log(await text(result)); // 'HELLO'\nconst { from, pull, text } = require('node:stream/iter');\n\nconst asciiUpper = (chunks) => {\n if (chunks === null) return null;\n return chunks.map((c) => {\n for (let i = 0; i < c.length; i++) {\n c[i] -= (c[i] >= 97 && c[i] <= 122) * 32;\n }\n return c;\n });\n};\n\nasync function run() {\n const result = pull(from('hello'), asciiUpper);\n console.log(await text(result)); // 'HELLO'\n}\n\nrun().catch(console.error);\nUsing an AbortSignal:
import { pull } from 'node:stream/iter';\n\nconst ac = new AbortController();\nconst result = pull(source, transform, { signal: ac.signal });\nac.abort(); // Pipeline throws AbortError on next iteration\nconst { pull } = require('node:stream/iter');\n\nconst ac = new AbortController();\nconst result = pull(source, transform, { signal: ac.signal });\nac.abort(); // Pipeline throws AbortError on next iteration\nsource {Iterable} The sync data source....transforms <Function> | <Object> Zero or more sync transforms.Synchronous version of pull(). All transforms must be synchronous.
Create a push stream with backpressure. The writer pushes data in; the\nreadable side is consumed as an async iterable.
\nimport { push, text } from 'node:stream/iter';\n\nconst { writer, readable } = push();\n\n// Producer and consumer must run concurrently. With strict backpressure\n// (the default), awaited writes block until the consumer reads.\nconst producing = (async () => {\n await writer.write('hello');\n await writer.write(' world');\n await writer.end();\n})();\n\nconsole.log(await text(readable)); // 'hello world'\nawait producing;\nconst { push, text } = require('node:stream/iter');\n\nasync function run() {\n const { writer, readable } = push();\n\n // Producer and consumer must run concurrently. With strict backpressure\n // (the default), awaited writes block until the consumer reads.\n const producing = (async () => {\n await writer.write('hello');\n await writer.write(' world');\n await writer.end();\n })();\n\n console.log(await text(readable)); // 'hello world'\n await producing;\n}\n\nrun().catch(console.error);\nThe writer returned by push() conforms to the [Writer interface][].
Create a pair of connected duplex channels for bidirectional communication,\nsimilar to socketpair(). Data written to one channel's writer appears in\nthe other channel's readable.
Each channel has:
\nwriter — a [Writer interface][] object for sending data to the peer.readable — an AsyncIterable<Uint8Array[]> for reading data from\nthe peer.close() — close this end of the channel (idempotent).[Symbol.asyncDispose]() — async dispose support for await using.import { duplex, text } from 'node:stream/iter';\n\nconst [client, server] = duplex();\n\n// Server echoes back\nconst serving = (async () => {\n for await (const chunks of server.readable) {\n await server.writer.writev(chunks);\n }\n})();\n\nawait client.writer.write('hello');\nawait client.writer.end();\n\nconsole.log(await text(server.readable)); // handled by echo\nawait serving;\nconst { duplex, text } = require('node:stream/iter');\n\nasync function run() {\n const [client, server] = duplex();\n\n // Server echoes back\n const serving = (async () => {\n for await (const chunks of server.readable) {\n await server.writer.writev(chunks);\n }\n })();\n\n await client.writer.write('hello');\n await client.writer.end();\n\n console.log(await text(server.readable)); // handled by echo\n await serving;\n}\n\nrun().catch(console.error);\nsource {AsyncIterable<Uint8Array[]>|Iterable<Uint8Array[]>}options <Object>\nsignal <AbortSignal>limit <number> Maximum number of bytes to consume. If the total bytes\ncollected exceeds limit, an ERR_OUT_OF_RANGE error is thrownCollect all chunks as an array of Uint8Array values (without concatenating).
source {AsyncIterable<Uint8Array[]>|Iterable<Uint8Array[]>}options <Object>\nsignal <AbortSignal>limit <number> Maximum number of bytes to consume. If the total bytes\ncollected exceeds limit, an ERR_OUT_OF_RANGE error is thrownCollect all bytes into an ArrayBuffer.
source {Iterable<Uint8Array[]>}options <Object>\nlimit <number> Maximum number of bytes to consume. If the total bytes\ncollected exceeds limit, an ERR_OUT_OF_RANGE error is thrown<ArrayBuffer>Synchronous version of arrayBuffer().
source {Iterable<Uint8Array[]>}options <Object>\nlimit <number> Maximum number of bytes to consume. If the total bytes\ncollected exceeds limit, an ERR_OUT_OF_RANGE error is thrown<Uint8Array[]>Synchronous version of array().
source {AsyncIterable<Uint8Array[]>|Iterable<Uint8Array[]>}options <Object>\nsignal <AbortSignal>limit <number> Maximum number of bytes to consume. If the total bytes\ncollected exceeds limit, an ERR_OUT_OF_RANGE error is thrownCollect all bytes from a stream into a single Uint8Array.
import { from, bytes } from 'node:stream/iter';\n\nconst data = await bytes(from('hello'));\nconsole.log(data); // Uint8Array(5) [ 104, 101, 108, 108, 111 ]\nconst { from, bytes } = require('node:stream/iter');\n\nasync function run() {\n const data = await bytes(from('hello'));\n console.log(data); // Uint8Array(5) [ 104, 101, 108, 108, 111 ]\n}\n\nrun().catch(console.error);\nsource {Iterable<Uint8Array[]>}options <Object>\nlimit <number> Maximum number of bytes to consume. If the total bytes\ncollected exceeds limit, an ERR_OUT_OF_RANGE error is thrown<Uint8Array>Synchronous version of bytes().
source {AsyncIterable<Uint8Array[]>|Iterable<Uint8Array[]>}options <Object>\nencoding <string> Text encoding. Default: 'utf-8'.signal <AbortSignal>limit <number> Maximum number of bytes to consume. If the total bytes\ncollected exceeds limit, an ERR_OUT_OF_RANGE error is thrownCollect all bytes and decode as text.
\nimport { from, text } from 'node:stream/iter';\n\nconsole.log(await text(from('hello'))); // 'hello'\nconst { from, text } = require('node:stream/iter');\n\nasync function run() {\n console.log(await text(from('hello'))); // 'hello'\n}\n\nrun().catch(console.error);\nSynchronous version of text().
Wait for a drainable writer's backpressure to clear. Returns a promise that\nresolves to true when the writer can accept more data, or null if the\nobject does not implement the drainable protocol.
import { push, ondrain, text } from 'node:stream/iter';\n\nconst { writer, readable } = push({ highWaterMark: 2 });\nwriter.writeSync('a');\nwriter.writeSync('b');\n\n// Start consuming so the buffer can actually drain\nconst consuming = text(readable);\n\n// Buffer is full -- wait for drain\nconst canWrite = await ondrain(writer);\nif (canWrite) {\n await writer.write('c');\n}\nawait writer.end();\nawait consuming;\nconst { push, ondrain, text } = require('node:stream/iter');\n\nasync function run() {\n const { writer, readable } = push({ highWaterMark: 2 });\n writer.writeSync('a');\n writer.writeSync('b');\n\n // Start consuming so the buffer can actually drain\n const consuming = text(readable);\n\n // Buffer is full -- wait for drain\n const canWrite = await ondrain(writer);\n if (canWrite) {\n await writer.write('c');\n }\n await writer.end();\n await consuming;\n}\n\nrun().catch(console.error);\n...sources {AsyncIterable<Uint8Array[]>|Iterable<Uint8Array[]>} Two or more iterables.options <Object>\nsignal <AbortSignal>Merge multiple async iterables by yielding batches in temporal order\n(whichever source produces data first). All sources are consumed\nconcurrently.
\nimport { from, merge, text } from 'node:stream/iter';\n\nconst merged = merge(from('hello '), from('world'));\nconsole.log(await text(merged)); // Order depends on timing\nconst { from, merge, text } = require('node:stream/iter');\n\nasync function run() {\n const merged = merge(from('hello '), from('world'));\n console.log(await text(merged)); // Order depends on timing\n}\n\nrun().catch(console.error);\nCreate a pass-through transform that observes batches without modifying them.\nUseful for logging, metrics, or debugging.
\nimport { from, pull, text, tap } from 'node:stream/iter';\n\nconst result = pull(\n from('hello'),\n tap((chunks) => console.log('Batch size:', chunks.length)),\n);\nconsole.log(await text(result));\nconst { from, pull, text, tap } = require('node:stream/iter');\n\nasync function run() {\n const result = pull(\n from('hello'),\n tap((chunks) => console.log('Batch size:', chunks.length)),\n );\n console.log(await text(result));\n}\n\nrun().catch(console.error);\ntap() intentionally does not prevent in-place modification of the\nchunks by the tapping callback; but return values are ignored.
Synchronous version of tap().
Create a push-model multi-consumer broadcast channel. A single writer pushes\ndata to multiple consumers. Each consumer has an independent cursor into a\nshared buffer.
\nimport { broadcast, text } from 'node:stream/iter';\n\nconst { writer, broadcast: bc } = broadcast();\n\n// Create consumers before writing\nconst c1 = bc.push(); // Consumer 1\nconst c2 = bc.push(); // Consumer 2\n\n// Producer and consumers must run concurrently. Awaited writes\n// block when the buffer fills until consumers read.\nconst producing = (async () => {\n await writer.write('hello');\n await writer.end();\n})();\n\nconst [r1, r2] = await Promise.all([text(c1), text(c2)]);\nconsole.log(r1); // 'hello'\nconsole.log(r2); // 'hello'\nawait producing;\nconst { broadcast, text } = require('node:stream/iter');\n\nasync function run() {\n const { writer, broadcast: bc } = broadcast();\n\n // Create consumers before writing\n const c1 = bc.push(); // Consumer 1\n const c2 = bc.push(); // Consumer 2\n\n // Producer and consumers must run concurrently. Awaited writes\n // block when the buffer fills until consumers read.\n const producing = (async () => {\n await writer.write('hello');\n await writer.end();\n })();\n\n const [r1, r2] = await Promise.all([text(c1), text(c2)]);\n console.log(r1); // 'hello'\n console.log(r2); // 'hello'\n await producing;\n}\n\nrun().catch(console.error);\nThe number of chunks currently buffered.
" }, { "textRaw": "{number}", "name": "consumerCount", "type": "number", "desc": "The number of active consumers.
" } ], "methods": [ { "textRaw": "`broadcast.cancel([reason])`", "name": "cancel", "type": "method", "signatures": [ { "params": [ { "textRaw": "`reason` {Error}", "name": "reason", "type": "Error", "optional": true } ] } ], "desc": "Cancel the broadcast. All consumers receive an error.
" }, { "textRaw": "`broadcast.push([...transforms][, options])`", "name": "push", "type": "method", "signatures": [ { "params": [ { "textRaw": "`...transforms` {Function|Object}", "name": "...transforms", "type": "Function|Object", "optional": true }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`signal` {AbortSignal}", "name": "signal", "type": "AbortSignal" } ], "optional": true } ], "return": { "textRaw": "Returns: {AsyncIterableCreate a new consumer. Each consumer receives all data written to the\nbroadcast from the point of subscription onward. Optional transforms are\napplied to this consumer's view of the data.
" }, { "textRaw": "`broadcast[Symbol.dispose]()`", "name": "[Symbol.dispose]", "type": "method", "signatures": [ { "params": [] } ], "desc": "Alias for broadcast.cancel().
Create a {Broadcast} from an existing source. The source is consumed\nautomatically and pushed to all subscribers.
" }, { "textRaw": "`share(source[, options])`", "name": "share", "type": "method", "meta": { "added": [ "v25.9.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`source` {AsyncIterable} The source to share.", "name": "source", "type": "AsyncIterable", "desc": "The source to share." }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`highWaterMark` {number} Buffer size. Must be >= 1; values below 1 are clamped to 1. **Default:** `16`.", "name": "highWaterMark", "type": "number", "default": "`16`", "desc": "Buffer size. Must be >= 1; values below 1 are clamped to 1." }, { "textRaw": "`backpressure` {string} `'strict'`, `'block'`, `'drop-oldest'`, or `'drop-newest'`. **Default:** `'strict'`.", "name": "backpressure", "type": "string", "default": "`'strict'`", "desc": "`'strict'`, `'block'`, `'drop-oldest'`, or `'drop-newest'`." } ], "optional": true } ], "return": { "textRaw": "Returns: {Share}", "name": "return", "type": "Share" } } ], "desc": "Create a pull-model multi-consumer shared stream. Unlike broadcast(), the\nsource is only read when a consumer pulls. Multiple consumers share a single\nbuffer.
import { from, share, text } from 'node:stream/iter';\n\nconst shared = share(from('hello'));\n\nconst c1 = shared.pull();\nconst c2 = shared.pull();\n\n// Consume concurrently to avoid deadlock with small buffers.\nconst [r1, r2] = await Promise.all([text(c1), text(c2)]);\nconsole.log(r1); // 'hello'\nconsole.log(r2); // 'hello'\nconst { from, share, text } = require('node:stream/iter');\n\nasync function run() {\n const shared = share(from('hello'));\n\n const c1 = shared.pull();\n const c2 = shared.pull();\n\n // Consume concurrently to avoid deadlock with small buffers.\n const [r1, r2] = await Promise.all([text(c1), text(c2)]);\n console.log(r1); // 'hello'\n console.log(r2); // 'hello'\n}\n\nrun().catch(console.error);\nThe number of chunks currently buffered.
" }, { "textRaw": "{number}", "name": "consumerCount", "type": "number", "desc": "The number of active consumers.
" } ], "methods": [ { "textRaw": "`share.cancel([reason])`", "name": "cancel", "type": "method", "signatures": [ { "params": [ { "textRaw": "`reason` {Error}", "name": "reason", "type": "Error", "optional": true } ] } ], "desc": "Cancel the share. All consumers receive an error.
" }, { "textRaw": "`share.pull([...transforms][, options])`", "name": "pull", "type": "method", "signatures": [ { "params": [ { "textRaw": "`...transforms` {Function|Object}", "name": "...transforms", "type": "Function|Object", "optional": true }, { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`signal` {AbortSignal}", "name": "signal", "type": "AbortSignal" } ], "optional": true } ], "return": { "textRaw": "Returns: {AsyncIterableCreate a new consumer of the shared source.
" }, { "textRaw": "`share[Symbol.dispose]()`", "name": "[Symbol.dispose]", "type": "method", "signatures": [ { "params": [] } ], "desc": "Alias for share.cancel().
Create a {Share} from an existing source.
" }, { "textRaw": "`shareSync(source[, options])`", "name": "shareSync", "type": "method", "meta": { "added": [ "v25.9.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "source" }, { "name": "options", "optional": true } ] } ], "desc": "source {Iterable} The sync source to share.options <Object>\n\nSynchronous version of share().
input {Iterable|SyncShareable}options <Object>Compression and decompression transforms for use with pull(), pullSync(),\npipeTo(), and pipeToSync() are available via the node:zlib/iter\nmodule. See the node:zlib/iter documentation for details.
These well-known symbols allow third-party objects to participate in the\nstreaming protocol without importing from node:stream/iter directly.
Symbol.for('Stream.broadcastProtocol')The value must be a function. When called by Broadcast.from(), it receives\nthe options passed to Broadcast.from() and must return an object conforming\nto the {Broadcast} interface. The implementation is fully custom -- it can\nmanage consumers, buffering, and backpressure however it wants.
import { Broadcast, text } from 'node:stream/iter';\n\n// This example defers to the built-in Broadcast, but a custom\n// implementation could use any mechanism.\nclass MessageBus {\n #broadcast;\n #writer;\n\n constructor() {\n const { writer, broadcast } = Broadcast();\n this.#writer = writer;\n this.#broadcast = broadcast;\n }\n\n [Symbol.for('Stream.broadcastProtocol')](options) {\n return this.#broadcast;\n }\n\n send(data) {\n this.#writer.write(new TextEncoder().encode(data));\n }\n\n close() {\n this.#writer.end();\n }\n}\n\nconst bus = new MessageBus();\nconst { broadcast } = Broadcast.from(bus);\nconst consumer = broadcast.push();\nbus.send('hello');\nbus.close();\nconsole.log(await text(consumer)); // 'hello'\nconst { Broadcast, text } = require('node:stream/iter');\n\n// This example defers to the built-in Broadcast, but a custom\n// implementation could use any mechanism.\nclass MessageBus {\n #broadcast;\n #writer;\n\n constructor() {\n const { writer, broadcast } = Broadcast();\n this.#writer = writer;\n this.#broadcast = broadcast;\n }\n\n [Symbol.for('Stream.broadcastProtocol')](options) {\n return this.#broadcast;\n }\n\n send(data) {\n this.#writer.write(new TextEncoder().encode(data));\n }\n\n close() {\n this.#writer.end();\n }\n}\n\nconst bus = new MessageBus();\nconst { broadcast } = Broadcast.from(bus);\nconst consumer = broadcast.push();\nbus.send('hello');\nbus.close();\ntext(consumer).then(console.log); // 'hello'\nSymbol.for('Stream.drainableProtocol')Implement to make a writer compatible with ondrain(). The method should\nreturn a promise that resolves when backpressure clears, or null if no\nbackpressure.
import { ondrain } from 'node:stream/iter';\n\nclass CustomWriter {\n #queue = [];\n #drain = null;\n #closed = false;\n [Symbol.for('Stream.drainableProtocol')]() {\n if (this.#closed) return null;\n if (this.#queue.length < 3) return Promise.resolve(true);\n this.#drain ??= Promise.withResolvers();\n return this.#drain.promise;\n }\n write(chunk) {\n this.#queue.push(chunk);\n }\n flush() {\n this.#queue.length = 0;\n this.#drain?.resolve(true);\n this.#drain = null;\n }\n close() {\n this.#closed = true;\n }\n}\nconst writer = new CustomWriter();\nconst ready = ondrain(writer);\nconsole.log(ready); // Promise { true } -- no backpressure\nconst { ondrain } = require('node:stream/iter');\n\nclass CustomWriter {\n #queue = [];\n #drain = null;\n #closed = false;\n\n [Symbol.for('Stream.drainableProtocol')]() {\n if (this.#closed) return null;\n if (this.#queue.length < 3) return Promise.resolve(true);\n this.#drain ??= Promise.withResolvers();\n return this.#drain.promise;\n }\n\n write(chunk) {\n this.#queue.push(chunk);\n }\n\n flush() {\n this.#queue.length = 0;\n this.#drain?.resolve(true);\n this.#drain = null;\n }\n\n close() {\n this.#closed = true;\n }\n}\n\nconst writer = new CustomWriter();\nconst ready = ondrain(writer);\nconsole.log(ready); // Promise { true } -- no backpressure\nSymbol.for('Stream.shareProtocol')The value must be a function. When called by Share.from(), it receives the\noptions passed to Share.from() and must return an object conforming the the\n{Share} interface. The implementation is fully custom -- it can manage the shared\nsource, consumers, buffering, and backpressure however it wants.
import { share, Share, text } from 'node:stream/iter';\n\n// This example defers to the built-in share(), but a custom\n// implementation could use any mechanism.\nclass DataPool {\n #share;\n\n constructor(source) {\n this.#share = share(source);\n }\n\n [Symbol.for('Stream.shareProtocol')](options) {\n return this.#share;\n }\n}\n\nconst pool = new DataPool(\n (async function* () {\n yield 'hello';\n })(),\n);\n\nconst shared = Share.from(pool);\nconst consumer = shared.pull();\nconsole.log(await text(consumer)); // 'hello'\nconst { share, Share, text } = require('node:stream/iter');\n\n// This example defers to the built-in share(), but a custom\n// implementation could use any mechanism.\nclass DataPool {\n #share;\n\n constructor(source) {\n this.#share = share(source);\n }\n\n [Symbol.for('Stream.shareProtocol')](options) {\n return this.#share;\n }\n}\n\nconst pool = new DataPool(\n (async function* () {\n yield 'hello';\n })(),\n);\n\nconst shared = Share.from(pool);\nconst consumer = shared.pull();\ntext(consumer).then(console.log); // 'hello'\nSymbol.for('Stream.shareSyncProtocol')The value must be a function. When called by SyncShare.fromSync(), it receives\nthe options passed to SyncShare.fromSync() and must return an object conforming\nto the {SyncShare} interface. The implementation is fully custom -- it can manage\nthe shared source, consumers, and buffering however it wants.
import { shareSync, SyncShare, textSync } from 'node:stream/iter';\n\n// This example defers to the built-in shareSync(), but a custom\n// implementation could use any mechanism.\nclass SyncDataPool {\n #share;\n\n constructor(source) {\n this.#share = shareSync(source);\n }\n\n [Symbol.for('Stream.shareSyncProtocol')](options) {\n return this.#share;\n }\n}\n\nconst encoder = new TextEncoder();\nconst pool = new SyncDataPool(\n function* () {\n yield [encoder.encode('hello')];\n }(),\n);\n\nconst shared = SyncShare.fromSync(pool);\nconst consumer = shared.pull();\nconsole.log(textSync(consumer)); // 'hello'\nconst { shareSync, SyncShare, textSync } = require('node:stream/iter');\n\n// This example defers to the built-in shareSync(), but a custom\n// implementation could use any mechanism.\nclass SyncDataPool {\n #share;\n\n constructor(source) {\n this.#share = shareSync(source);\n }\n\n [Symbol.for('Stream.shareSyncProtocol')](options) {\n return this.#share;\n }\n}\n\nconst encoder = new TextEncoder();\nconst pool = new SyncDataPool(\n function* () {\n yield [encoder.encode('hello')];\n }(),\n);\n\nconst shared = SyncShare.fromSync(pool);\nconst consumer = shared.pull();\nconsole.log(textSync(consumer)); // 'hello'\nSymbol.for('Stream.toAsyncStreamable')The value must be a function that converts the object into a streamable value.\nWhen the object is encountered anywhere in the streaming pipeline (as a source\npassed to from(), or as a value returned from a transform), this method is\ncalled to produce the actual data. It may return (or resolve to) any streamable\nvalue: a string, Uint8Array, AsyncIterable, Iterable, or another streamable\nobject.
import { from, text } from 'node:stream/iter';\n\nclass Greeting {\n #name;\n\n constructor(name) {\n this.#name = name;\n }\n\n [Symbol.for('Stream.toAsyncStreamable')]() {\n return `hello ${this.#name}`;\n }\n}\n\nconst stream = from(new Greeting('world'));\nconsole.log(await text(stream)); // 'hello world'\nconst { from, text } = require('node:stream/iter');\n\nclass Greeting {\n #name;\n\n constructor(name) {\n this.#name = name;\n }\n\n [Symbol.for('Stream.toAsyncStreamable')]() {\n return `hello ${this.#name}`;\n }\n}\n\nconst stream = from(new Greeting('world'));\ntext(stream).then(console.log); // 'hello world'\nSymbol.for('Stream.toStreamable')The value must be a function that synchronously converts the object into a\nstreamable value. When the object is encountered anywhere in the streaming\npipeline (as a source passed to fromSync(), or as a value returned from a\nsync transform), this method is called to produce the actual data. It must\nsynchronously return a streamable value: a string, Uint8Array, or Iterable.
import { fromSync, textSync } from 'node:stream/iter';\n\nclass Greeting {\n #name;\n\n constructor(name) {\n this.#name = name;\n }\n\n [Symbol.for('Stream.toStreamable')]() {\n return `hello ${this.#name}`;\n }\n}\n\nconst stream = fromSync(new Greeting('world'));\nconsole.log(textSync(stream)); // 'hello world'\nconst { fromSync, textSync } = require('node:stream/iter');\n\nclass Greeting {\n #name;\n\n constructor(name) {\n this.#name = name;\n }\n\n [Symbol.for('Stream.toStreamable')]() {\n return `hello ${this.#name}`;\n }\n}\n\nconst stream = fromSync(new Greeting('world'));\nconsole.log(textSync(stream)); // 'hello world'\n