= (source: AsyncIterable) => Promise;
type PipelineDestination, P> = S extends
PipelineTransformSource ?
| NodeJS.WritableStream
| PipelineDestinationIterableFunction
| PipelineDestinationPromiseFunction
: never;
type PipelineCallback> = S extends
PipelineDestinationPromiseFunction ? (err: NodeJS.ErrnoException | null, value: P) => void
: (err: NodeJS.ErrnoException | null) => void;
type PipelinePromise> = S extends
PipelineDestinationPromiseFunction ? Promise : Promise;
interface PipelineOptions {
signal?: AbortSignal | undefined;
end?: boolean | undefined;
}
/**
* A module method to pipe between streams and generators forwarding errors and
* properly cleaning up and provide a callback when the pipeline is complete.
*
* ```js
* const { pipeline } = require('node:stream');
* const fs = require('node:fs');
* const zlib = require('node:zlib');
*
* // Use the pipeline API to easily pipe a series of streams
* // together and get notified when the pipeline is fully done.
*
* // A pipeline to gzip a potentially huge tar file efficiently:
*
* pipeline(
* fs.createReadStream('archive.tar'),
* zlib.createGzip(),
* fs.createWriteStream('archive.tar.gz'),
* (err) => {
* if (err) {
* console.error('Pipeline failed.', err);
* } else {
* console.log('Pipeline succeeded.');
* }
* },
* );
* ```
*
* The `pipeline` API provides a [`promise version`](https://nodejs.org/docs/latest-v20.x/api/stream.html#streampipelinesource-transforms-destination-options).
*
* `stream.pipeline()` will call `stream.destroy(err)` on all streams except:
*
* * `Readable` streams which have emitted `'end'` or `'close'`.
* * `Writable` streams which have emitted `'finish'` or `'close'`.
*
* `stream.pipeline()` leaves dangling event listeners on the streams
* after the `callback` has been invoked. In the case of reuse of streams after
* failure, this can cause event listener leaks and swallowed errors. If the last
* stream is readable, dangling event listeners will be removed so that the last
* stream can be consumed later.
*
* `stream.pipeline()` closes all the streams when an error is raised.
* The `IncomingRequest` usage with `pipeline` could lead to an unexpected behavior
* once it would destroy the socket without sending the expected response.
* See the example below:
*
* ```js
* const fs = require('node:fs');
* const http = require('node:http');
* const { pipeline } = require('node:stream');
*
* const server = http.createServer((req, res) => {
* const fileStream = fs.createReadStream('./fileNotExist.txt');
* pipeline(fileStream, res, (err) => {
* if (err) {
* console.log(err); // No such file
* // this message can't be sent once `pipeline` already destroyed the socket
* return res.end('error!!!');
* }
* });
* });
* ```
* @since v10.0.0
* @param callback Called when the pipeline is fully done.
*/
function pipeline, B extends PipelineDestination>(
source: A,
destination: B,
callback: PipelineCallback,
): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
function pipeline<
A extends PipelineSource,
T1 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
destination: B,
callback: PipelineCallback,
): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
function pipeline<
A extends PipelineSource,
T1 extends PipelineTransform,
T2 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
transform2: T2,
destination: B,
callback: PipelineCallback,
): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
function pipeline<
A extends PipelineSource,
T1 extends PipelineTransform,
T2 extends PipelineTransform,
T3 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
transform2: T2,
transform3: T3,
destination: B,
callback: PipelineCallback,
): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
function pipeline<
A extends PipelineSource,
T1 extends PipelineTransform,
T2 extends PipelineTransform,
T3 extends PipelineTransform,
T4 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
transform2: T2,
transform3: T3,
transform4: T4,
destination: B,
callback: PipelineCallback,
): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
function pipeline(
streams: ReadonlyArray,
callback: (err: NodeJS.ErrnoException | null) => void,
): NodeJS.WritableStream;
function pipeline(
stream1: NodeJS.ReadableStream,
stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream,
...streams: Array<
NodeJS.ReadWriteStream | NodeJS.WritableStream | ((err: NodeJS.ErrnoException | null) => void)
>
): NodeJS.WritableStream;
namespace pipeline {
function __promisify__, B extends PipelineDestination>(
source: A,
destination: B,
options?: PipelineOptions,
): PipelinePromise;
function __promisify__<
A extends PipelineSource,
T1 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
destination: B,
options?: PipelineOptions,
): PipelinePromise;
function __promisify__<
A extends PipelineSource,
T1 extends PipelineTransform,
T2 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
transform2: T2,
destination: B,
options?: PipelineOptions,
): PipelinePromise;
function __promisify__<
A extends PipelineSource,
T1 extends PipelineTransform,
T2 extends PipelineTransform,
T3 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
transform2: T2,
transform3: T3,
destination: B,
options?: PipelineOptions,
): PipelinePromise;
function __promisify__<
A extends PipelineSource,
T1 extends PipelineTransform,
T2 extends PipelineTransform,
T3 extends PipelineTransform,
T4 extends PipelineTransform,
B extends PipelineDestination,
>(
source: A,
transform1: T1,
transform2: T2,
transform3: T3,
transform4: T4,
destination: B,
options?: PipelineOptions,
): PipelinePromise;
function __promisify__(
streams: ReadonlyArray,
options?: PipelineOptions,
): Promise;
function __promisify__(
stream1: NodeJS.ReadableStream,
stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream,
...streams: Array
): Promise;
}
interface Pipe {
close(): void;
hasRef(): boolean;
ref(): void;
unref(): void;
}
/**
* Returns whether the stream has encountered an error.
* @since v17.3.0, v16.14.0
* @experimental
*/
function isErrored(stream: Readable | Writable | NodeJS.ReadableStream | NodeJS.WritableStream): boolean;
/**
* Returns whether the stream is readable.
* @since v17.4.0, v16.14.0
* @experimental
*/
function isReadable(stream: Readable | NodeJS.ReadableStream): boolean;
const promises: typeof streamPromises;
const consumers: typeof streamConsumers;
}
export = internal;
}
declare module "node:stream" {
import stream = require("stream");
export = stream;
}