@types/node/stream/promises.d.ts

TypeScript definitions for node

declare module "node:stream/promises" {
    import { Abortable } from "node:events";
    import {
        FinishedOptions as _FinishedOptions,
        PipelineDestination,
        PipelineSource,
        PipelineTransform,
    } from "node:stream";
    import { ReadableStream, WritableStream } from "node:stream/web";
    interface FinishedOptions extends _FinishedOptions {
        /**
         * If true, removes the listeners registered by this function before the promise is fulfilled.
         * @default false
         */
        cleanup?: boolean | undefined;
    }
    /**
     * ```js
     * import { finished } from 'node:stream/promises';
     * import { createReadStream } from 'node:fs';
     *
     * const rs = createReadStream('archive.tar');
     *
     * async function run() {
     *   await finished(rs);
     *   console.log('Stream is done reading.');
     * }
     *
     * run().catch(console.error);
     * rs.resume(); // Drain the stream.
     * ```
     *
     * The `finished` API also provides a [callback version](https://nodejs.org/docs/latest-v25.x/api/stream.html#streamfinishedstream-options-callback).
     *
     * `stream.finished()` leaves dangling event listeners (in particular
     * `'error'`, `'end'`, `'finish'` and `'close'`) after the returned promise is
     * resolved or rejected. The reason for this is so that unexpected `'error'`
     * events (due to incorrect stream implementations) do not cause unexpected
     * crashes. If this is unwanted behavior then `options.cleanup` should be set to
     * `true`:
     *
     * ```js
     * await finished(rs, { cleanup: true });
     * ```
     * @since v15.0.0
     * @returns Fulfills when the stream is no longer readable or writable.
     */
    function finished(
        stream: NodeJS.ReadableStream | NodeJS.WritableStream | ReadableStream | WritableStream,
        options?: FinishedOptions,
    ): Promise<void>;
    interface PipelineOptions extends Abortable {
        end?: boolean | undefined;
    }
    type PipelineResult<S extends PipelineDestination<any, any>> = S extends (...args: any[]) => PromiseLike<infer R>
        ? Promise<R>
        : Promise<void>;
    /**
     * ```js
     * import { pipeline } from 'node:stream/promises';
     * import { createReadStream, createWriteStream } from 'node:fs';
     * import { createGzip } from 'node:zlib';
     *
     * await pipeline(
     *   createReadStream('archive.tar'),
     *   createGzip(),
     *   createWriteStream('archive.tar.gz'),
     * );
     * console.log('Pipeline succeeded.');
     * ```
     *
     * To use an `AbortSignal`, pass it inside an options object, as the last argument.
     * When the signal is aborted, `destroy` will be called on the underlying pipeline,
     * with an `AbortError`.
     *
     * ```js
     * import { pipeline } from 'node:stream/promises';
     * import { createReadStream, createWriteStream } from 'node:fs';
     * import { createGzip } from 'node:zlib';
     *
     * const ac = new AbortController();
     * const { signal } = ac;
     * setImmediate(() => ac.abort());
     * try {
     *   await pipeline(
     *     createReadStream('archive.tar'),
     *     createGzip(),
     *     createWriteStream('archive.tar.gz'),
     *     { signal },
     *   );
     * } catch (err) {
     *   console.error(err); // AbortError
     * }
     * ```
     *
     * The `pipeline` API also supports async generators:
     *
     * ```js
     * import { pipeline } from 'node:stream/promises';
     * import { createReadStream, createWriteStream } from 'node:fs';
     *
     * await pipeline(
     *   createReadStream('lowercase.txt'),
     *   async function* (source, { signal }) {
     *     source.setEncoding('utf8');  // Work with strings rather than `Buffer`s.
     *     for await (const chunk of source) {
     *       yield await processChunk(chunk, { signal });
     *     }
     *   },
     *   createWriteStream('uppercase.txt'),
     * );
     * console.log('Pipeline succeeded.');
     * ```
     *
     * Remember to handle the `signal` argument passed into the async generator.
     * Especially in the case where the async generator is the source for the
     * pipeline (i.e. first argument) or the pipeline will never complete.
     *
     * ```js
     * import { pipeline } from 'node:stream/promises';
     * import fs from 'node:fs';
     * await pipeline(
     *   async function* ({ signal }) {
     *     await someLongRunningfn({ signal });
     *     yield 'asd';
     *   },
     *   fs.createWriteStream('uppercase.txt'),
     * );
     * console.log('Pipeline succeeded.');
     * ```
     *
     * The `pipeline` API provides [callback version](https://nodejs.org/docs/latest-v25.x/api/stream.html#streampipelinesource-transforms-destination-callback):
     * @since v15.0.0
     * @returns Fulfills when the pipeline is complete.
     */
    function pipeline<A extends PipelineSource<any>, B extends PipelineDestination<A, any>>(
        source: A,
        destination: B,
        options?: PipelineOptions,
    ): PipelineResult<B>;
    function pipeline<
        A extends PipelineSource<any>,
        T1 extends PipelineTransform<A, any>,
        B extends PipelineDestination<T1, any>,
    >(
        source: A,
        transform1: T1,
        destination: B,
        options?: PipelineOptions,
    ): PipelineResult<B>;
    function pipeline<
        A extends PipelineSource<any>,
        T1 extends PipelineTransform<A, any>,
        T2 extends PipelineTransform<T1, any>,
        B extends PipelineDestination<T2, any>,
    >(
        source: A,
        transform1: T1,
        transform2: T2,
        destination: B,
        options?: PipelineOptions,
    ): PipelineResult<B>;
    function pipeline<
        A extends PipelineSource<any>,
        T1 extends PipelineTransform<A, any>,
        T2 extends PipelineTransform<T1, any>,
        T3 extends PipelineTransform<T2, any>,
        B extends PipelineDestination<T3, any>,
    >(
        source: A,
        transform1: T1,
        transform2: T2,
        transform3: T3,
        destination: B,
        options?: PipelineOptions,
    ): PipelineResult<B>;
    function pipeline<
        A extends PipelineSource<any>,
        T1 extends PipelineTransform<A, any>,
        T2 extends PipelineTransform<T1, any>,
        T3 extends PipelineTransform<T2, any>,
        T4 extends PipelineTransform<T3, any>,
        B extends PipelineDestination<T4, any>,
    >(
        source: A,
        transform1: T1,
        transform2: T2,
        transform3: T3,
        transform4: T4,
        destination: B,
        options?: PipelineOptions,
    ): PipelineResult<B>;
    function pipeline(
        streams: readonly [PipelineSource<any>, ...PipelineTransform<any, any>[], PipelineDestination<any, any>],
        options?: PipelineOptions,
    ): Promise<void>;
    function pipeline(
        ...streams: [PipelineSource<any>, ...PipelineTransform<any, any>[], PipelineDestination<any, any>]
    ): Promise<void>;
    function pipeline(
        ...streams: [
            PipelineSource<any>,
            ...PipelineTransform<any, any>[],
            PipelineDestination<any, any>,
            options: PipelineOptions,
        ]
    ): Promise<void>;
}
declare module "stream/promises" {
    export * from "node:stream/promises";
}