Node.js · Module

node:stream/promises

node:stream/promises provides promise-returning utilities for working with streams. Use it with async/await to compose pipelines and await stream completion instead of supplying callbacks.

Since: v15.0.0

How it works

The module exposes promise-based stream utilities, including pipeline and finished. Import them from node:stream/promises and await their returned promises; pipeline connects streams, propagates errors, and resolves after completion, while finished resolves when a stream ends or closes according to its options.

Syntax

import { pipeline, finished } from 'node:stream/promises';

Returns

Exports promise-based stream utility functions, including pipeline and finished; pipeline returns a Promise that fulfills when the pipeline is complete.

Key points

This module is the promise-based counterpart to callback-oriented stream utilities.
Its utilities signal completion and failure through promises, enabling async/await.
CommonJS code can load the module with the node:stream/promises specifier.
The same promise utilities are also available through the promises property of node:stream.
The Streams Promises API was introduced in Node.js v15.0.0.

Common mistakes

If the destination must remain open after the source finishes, pass end: false; otherwise the destination is closed automatically.
Web Streams support is available only in versions that include this documented addition; verify the runtime version when accepting web-stream inputs.

Example: Compress a file with pipeline

import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';

try {
  await pipeline(
    createReadStream('input.txt'),
    createGzip(),
    createWriteStream('input.txt.gz')
  );
  console.log('Pipeline complete');
} catch (error) {
  console.error('Pipeline failed', error);
}

Compresses a file with a promise-returning stream pipeline; the process waits for completion and handles rejection.

When to use it

Async stream pipelines

Connect readable, transform, and writable streams while awaiting completion and catching failures.

Completion monitoring

Wait for a stream lifecycle event before releasing resources or continuing dependent work.

Web-stream integration

Process compatible Web Streams with promise-based stream utilities on supported Node.js versions.

Interview questions

QWhy use node:stream/promises?

Import the utilities from node:stream/promises. Unlike callback-oriented stream helpers, these functions return promises, so async/await and try/catch can handle completion and failures.

Follow-up: What happens when a pipeline stage fails? The returned promise rejects, allowing surrounding error handling to catch the failure while the pipeline performs its stream cleanup behavior.

QWhat does pipeline return?

pipeline accepts a source, optional transforms, and a destination, then returns a promise that fulfills when the pipeline completes. It is useful when completion must be coordinated with subsequent asynchronous work.

Follow-up: How would you keep the destination open? Supply the options object with end: false, which disables automatic destination closure when the source ends.

QHow can this API be imported?

The module is available through require('node:stream/promises') and also through require('node:stream').promises. The dedicated subpath makes the promise-based API explicit.

Follow-up: Can pipeline consume web streams? Yes, the documentation records web-stream support as added in v18.16.0 and v19.7.0, so runtime compatibility matters.

stream.pipeline
stream.finished
node:stream
node:fs
node:zlib

Source: Stream | Node.js v26.11.1 Documentation. Checked 2026-10-15.