@types/node 24.10.2 → 25.0.0

node/stream/consumers.d.ts

@@ -3,36 +3,36 @@
  * streams.
  * @since v16.7.0
  */
-declare module "stream/consumers" {
-    import { Blob as NodeBlob, NonSharedBuffer } from "node:buffer";
-    import { ReadableStream as WebReadableStream } from "node:stream/web";
+declare module "node:stream/consumers" {
+    import { Blob, NonSharedBuffer } from "node:buffer";
+    import { ReadableStream } from "node:stream/web";
     /**
      * @since v16.7.0
      * @returns Fulfills with an `ArrayBuffer` containing the full contents of the stream.
      */
-    function arrayBuffer(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<ArrayBuffer>;
+    function arrayBuffer(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<ArrayBuffer>;
     /**
      * @since v16.7.0
      * @returns Fulfills with a `Blob` containing the full contents of the stream.
      */
-    function blob(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<NodeBlob>;
+    function blob(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<Blob>;
     /**
      * @since v16.7.0
      * @returns Fulfills with a `Buffer` containing the full contents of the stream.
      */
-    function buffer(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<NonSharedBuffer>;
+    function buffer(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<NonSharedBuffer>;
     /**
      * @since v16.7.0
      * @returns Fulfills with the contents of the stream parsed as a
      * UTF-8 encoded string that is then passed through `JSON.parse()`.
      */
-    function json(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<unknown>;
+    function json(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<unknown>;
     /**
      * @since v16.7.0
      * @returns Fulfills with the contents of the stream parsed as a UTF-8 encoded string.
      */
-    function text(stream: WebReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<string>;
+    function text(stream: ReadableStream | NodeJS.ReadableStream | AsyncIterable<any>): Promise<string>;
 }
-declare module "node:stream/consumers" {
-    export * from "stream/consumers";
+declare module "stream/consumers" {
+    export * from "node:stream/consumers";
 }

node/stream/promises.d.ts

@@ -1,12 +1,12 @@
-declare module "stream/promises" {
+declare module "node:stream/promises" {
+    import { Abortable } from "node:events";
     import {
         FinishedOptions as _FinishedOptions,
         PipelineDestination,
-        PipelineOptions,
-        PipelinePromise,
         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.
@@ -14,15 +14,130 @@ declare module "stream/promises" {
          */
         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 | NodeJS.ReadWriteStream,
+        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,
-    ): PipelinePromise<B>;
+    ): PipelineResult<B>;
     function pipeline<
         A extends PipelineSource<any>,
         T1 extends PipelineTransform<A, any>,
@@ -32,7 +147,7 @@ declare module "stream/promises" {
         transform1: T1,
         destination: B,
         options?: PipelineOptions,
-    ): PipelinePromise<B>;
+    ): PipelineResult<B>;
     function pipeline<
         A extends PipelineSource<any>,
         T1 extends PipelineTransform<A, any>,
@@ -44,7 +159,7 @@ declare module "stream/promises" {
         transform2: T2,
         destination: B,
         options?: PipelineOptions,
-    ): PipelinePromise<B>;
+    ): PipelineResult<B>;
     function pipeline<
         A extends PipelineSource<any>,
         T1 extends PipelineTransform<A, any>,
@@ -58,7 +173,7 @@ declare module "stream/promises" {
         transform3: T3,
         destination: B,
         options?: PipelineOptions,
-    ): PipelinePromise<B>;
+    ): PipelineResult<B>;
     function pipeline<
         A extends PipelineSource<any>,
         T1 extends PipelineTransform<A, any>,
@@ -74,17 +189,23 @@ declare module "stream/promises" {
         transform4: T4,
         destination: B,
         options?: PipelineOptions,
-    ): PipelinePromise<B>;
+    ): PipelineResult<B>;
     function pipeline(
-        streams: ReadonlyArray<NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream>,
+        streams: readonly [PipelineSource<any>, ...PipelineTransform<any, any>[], PipelineDestination<any, any>],
         options?: PipelineOptions,
     ): Promise<void>;
     function pipeline(
-        stream1: NodeJS.ReadableStream,
-        stream2: NodeJS.ReadWriteStream | NodeJS.WritableStream,
-        ...streams: Array<NodeJS.ReadWriteStream | NodeJS.WritableStream | PipelineOptions>
+        ...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 "node:stream/promises" {
-    export * from "stream/promises";
+declare module "stream/promises" {
+    export * from "node:stream/promises";
 }