Update types for node:stream

types/node/stream.d.ts

@@ -2,9 +2,10 @@
  * A stream is an abstract interface for working with streaming data in Node.js.
  * The `node:stream` module provides an API for implementing the stream interface.
  *
- * There are many stream objects provided by Node.js. For instance, a `request to an HTTP server` and `process.stdout` are both stream instances.
+ * There are many stream objects provided by Node.js. For instance, a [request to an HTTP server](https://nodejs.org/docs/latest-v20.x/api/http.html#class-httpincomingmessage)
+ * and [`process.stdout`](https://nodejs.org/docs/latest-v20.x/api/process.html#processstdout) are both stream instances.
  *
- * Streams can be readable, writable, or both. All streams are instances of `EventEmitter`.
+ * Streams can be readable, writable, or both. All streams are instances of [`EventEmitter`](https://nodejs.org/docs/latest-v20.x/api/events.html#class-eventemitter).
  *
  * To access the `node:stream` module:
  *
@@ -41,16 +42,20 @@ declare module "stream" {
  import Readable = internal.Readable;
  import ReadableOptions = internal.ReadableOptions;
  interface ArrayOptions {
- /** the maximum concurrent invocations of `fn` to call on the stream at once.
+ /**
+ * The maximum concurrent invocations of `fn` to call on the stream at once.
  * @default 1
  */
  concurrency?: number;
- /** allows destroying the stream if the signal is aborted. */
+ /** Allows destroying the stream if the signal is aborted. */
  signal?: AbortSignal;
  }
  class ReadableBase extends Stream implements NodeJS.ReadableStream {
  /**
  * A utility method for creating Readable Streams out of iterators.
+ * @since v12.3.0, v10.17.0
+ * @param iterable Object implementing the `Symbol.asyncIterator` or `Symbol.iterator` iterable protocol. Emits an 'error' event if a null value is passed.
+ * @param options Options provided to `new stream.Readable([options])`. By default, `Readable.from()` will set `options.objectMode` to `true`, unless this is explicitly opted out by setting `options.objectMode` to `false`.
  */
  static from(iterable: Iterable<any> | AsyncIterable<any>, options?: ReadableOptions): Readable;
  /**
@@ -65,7 +70,7 @@ declare module "stream" {
  */
  readonly readableAborted: boolean;
  /**
- * Is `true` if it is safe to call `readable.read()`, which means
+ * Is `true` if it is safe to call {@link read}, which means
  * the stream has not been destroyed or emitted `'error'` or `'end'`.
  * @since v11.4.0
  */
@@ -77,18 +82,18 @@ declare module "stream" {
  */
  readonly readableDidRead: boolean;
  /**
- * Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the `readable.setEncoding()` method.
+ * Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the {@link setEncoding} method.
  * @since v12.7.0
  */
  readonly readableEncoding: BufferEncoding | null;
  /**
- * Becomes `true` when `'end'` event is emitted.
+ * Becomes `true` when [`'end'`](https://nodejs.org/docs/latest-v20.x/api/stream.html#event-end) event is emitted.
  * @since v12.9.0
  */
  readonly readableEnded: boolean;
  /**
  * This property reflects the current state of a `Readable` stream as described
- * in the `Three states` section.
+ * in the [Three states](https://nodejs.org/docs/latest-v20.x/api/stream.html#three-states) section.
  * @since v9.4.0
  */
  readonly readableFlowing: boolean | null;
@@ -134,9 +139,10 @@ declare module "stream" {
  * specified using the `readable.setEncoding()` method or the stream is operating
  * in object mode.
  *
- * The optional `size` argument specifies a specific number of bytes to read. If `size` bytes are not available to be read, `null` will be returned _unless_ the stream has ended, in which
- * case all of the data remaining in the internal
- * buffer will be returned.
+ * The optional `size` argument specifies a specific number of bytes to read. If
+ * `size` bytes are not available to be read, `null` will be returned _unless_ the
+ * stream has ended, in which case all of the data remaining in the internal buffer
+ * will be returned.
  *
  * If the `size` argument is not specified, all of the data contained in the
  * internal buffer will be returned.
@@ -193,7 +199,7 @@ declare module "stream" {
  * ```
  *
  * A `Readable` stream in object mode will always return a single item from
- * a call to `readable.read(size)`, regardless of the value of the`size` argument.
+ * a call to `readable.read(size)`, regardless of the value of the `size` argument.
  *
  * If the `readable.read()` method returns a chunk of data, a `'data'` event will
  * also be emitted.
@@ -208,9 +214,9 @@ declare module "stream" {
  * The `readable.setEncoding()` method sets the character encoding for
  * data read from the `Readable` stream.
  *
- * By default, no encoding is assigned and stream data will be returned as`Buffer` objects. Setting an encoding causes the stream data
+ * By default, no encoding is assigned and stream data will be returned as `Buffer` objects. Setting an encoding causes the stream data
  * to be returned as strings of the specified encoding rather than as `Buffer` objects. For instance, calling `readable.setEncoding('utf8')` will cause the
- * output data to be interpreted as UTF-8 data, and passed as strings. Calling`readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal
+ * output data to be interpreted as UTF-8 data, and passed as strings. Calling `readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal
  * string format.
  *
  * The `Readable` stream will properly handle multi-byte characters delivered
@@ -247,7 +253,7 @@ declare module "stream" {
  * });
  * ```
  *
- * The `readable.pause()` method has no effect if there is a `'readable'`event listener.
+ * The `readable.pause()` method has no effect if there is a `'readable'` event listener.
  * @since v0.9.4
  */
  pause(): this;
@@ -271,9 +277,9 @@ declare module "stream" {
  */
  resume(): this;
  /**
- * The `readable.isPaused()` method returns the current operating state of the`Readable`. This is used primarily by the mechanism that underlies the`readable.pipe()` method. In most
- * typical cases, there will be no reason to
- * use this method directly.
+ * The `readable.isPaused()` method returns the current operating state of the `Readable`. This is
+ * used primarily by the mechanism that underlies the `readable.pipe()` method. In most typical cases,
+ * there will be no reason to use this method directly.
  *
  * ```js
  * const readable = new stream.Readable();
@@ -384,7 +390,7 @@ declare module "stream" {
  * Prior to Node.js 0.10, streams did not implement the entire `node:stream` module API as it is currently defined. (See `Compatibility` for more
  * information.)
  *
- * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the`readable.wrap()` method can be used to create a `Readable`
+ * When using an older Node.js library that emits `'data'` events and has a {@link pause} method that is advisory only, the `readable.wrap()` method can be used to create a `Readable`
  * stream that uses
  * the old stream as its data source.
  *
@@ -567,8 +573,8 @@ declare module "stream" {
  ): Promise<T>;
  _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
  /**
- * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the readable
- * stream will release any internal resources and subsequent calls to `push()`will be ignored.
+ * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the readable
+ * stream will release any internal resources and subsequent calls to `push()` will be ignored.
  *
  * Once `destroy()` has been called any further calls will be a no-op and no
  * further errors except from `_destroy()` may be emitted as `'error'`.
@@ -733,7 +739,7 @@ declare module "stream" {
  * first argument. The `callback` is called asynchronously and before `'error'` is
  * emitted.
  *
- * The return value is `true` if the internal buffer is less than the`highWaterMark` configured when the stream was created after admitting `chunk`.
+ * The return value is `true` if the internal buffer is less than the `highWaterMark` configured when the stream was created after admitting `chunk`.
  * If `false` is returned, further attempts to write data to the stream should
  * stop until the `'drain'` event is emitted.
  *
@@ -821,10 +827,10 @@ declare module "stream" {
  *
  * The primary intent of `writable.cork()` is to accommodate a situation in which
  * several small chunks are written to the stream in rapid succession. Instead of
- * immediately forwarding them to the underlying destination, `writable.cork()`buffers all the chunks until `writable.uncork()` is called, which will pass them
+ * immediately forwarding them to the underlying destination, `writable.cork()` buffers all the chunks until `writable.uncork()` is called, which will pass them
  * all to `writable._writev()`, if present. This prevents a head-of-line blocking
  * situation where data is being buffered while waiting for the first small chunk
- * to be processed. However, use of `writable.cork()` without implementing`writable._writev()` may have an adverse effect on throughput.
+ * to be processed. However, use of `writable.cork()` without implementing `writable._writev()` may have an adverse effect on throughput.
  *
  * See also: `writable.uncork()`, `writable._writev()`.
  * @since v0.11.2
@@ -834,7 +840,7 @@ declare module "stream" {
  * The `writable.uncork()` method flushes all data buffered since {@link cork} was called.
  *
  * When using `writable.cork()` and `writable.uncork()` to manage the buffering
- * of writes to a stream, defer calls to `writable.uncork()` using`process.nextTick()`. Doing so allows batching of all`writable.write()` calls that occur within a given Node.js event
+ * of writes to a stream, defer calls to `writable.uncork()` using `process.nextTick()`. Doing so allows batching of all `writable.write()` calls that occur within a given Node.js event
  * loop phase.
  *
  * ```js
@@ -865,10 +871,10 @@ declare module "stream" {
  */
  uncork(): void;
  /**
- * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'`event (unless `emitClose` is set to `false`). After this call, the writable
+ * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the writable
  * stream has ended and subsequent calls to `write()` or `end()` will result in
  * an `ERR_STREAM_DESTROYED` error.
- * This is a destructive and immediate way to destroy a stream. Previous calls to`write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error.
+ * This is a destructive and immediate way to destroy a stream. Previous calls to `write()` may not have drained, and may trigger an `ERR_STREAM_DESTROYED` error.
  * Use `end()` instead of destroy if data should flush before close, or wait for
  * the `'drain'` event before destroying the stream.
  *
@@ -1063,8 +1069,8 @@ declare module "stream" {
  * readable side ends. Set initially by the `allowHalfOpen` constructor option,
  * which defaults to `true`.
  *
- * This can be changed manually to change the half-open behavior of an existing`Duplex` stream instance, but must be changed before the `'end'` event is
- * emitted.
+ * This can be changed manually to change the half-open behavior of an existing
+ * `Duplex` stream instance, but must be changed before the `'end'` event is emitted.
  * @since v0.9.4
  */
  allowHalfOpen: boolean;
@@ -1285,7 +1291,7 @@ declare module "stream" {
  }
  /**
  * The `stream.PassThrough` class is a trivial implementation of a `Transform` stream that simply passes the input bytes across to the output. Its purpose is
- * primarily for examples and testing, but there are some use cases where`stream.PassThrough` is useful as a building block for novel sorts of streams.
+ * primarily for examples and testing, but there are some use cases where `stream.PassThrough` is useful as a building block for novel sorts of streams.
  */
  class PassThrough extends Transform {}
  /**
@@ -1294,8 +1300,8 @@ declare module "stream" {
  * Attaches an AbortSignal to a readable or writeable stream. This lets code
  * control stream destruction using an `AbortController`.
  *
- * Calling `abort` on the `AbortController` corresponding to the passed`AbortSignal` will behave the same way as calling `.destroy(new AbortError())`on the stream, and `controller.error(new
- * AbortError())` for webstreams.
+ * Calling `abort` on the `AbortController` corresponding to the passed `AbortSignal` will behave the same way as
+ * calling `.destroy(new AbortError())` on the stream, and `controller.error(new AbortError())` for webstreams.
  *
  * ```js
  * const fs = require('node:fs');
@@ -1365,20 +1371,18 @@ declare module "stream" {
  * ```
  * @since v15.4.0
  * @param signal A signal representing possible cancellation
- * @param stream a stream to attach a signal to
+ * @param stream A stream to attach a signal to.
  */
  function addAbortSignal<T extends Stream>(signal: AbortSignal, stream: T): T;
  /**
  * Returns the default highWaterMark used by streams.
  * Defaults to `16384` (16 KiB), or `16` for `objectMode`.
  * @since v19.9.0
- * @param objectMode
  */
  function getDefaultHighWaterMark(objectMode: boolean): number;
  /**
  * Sets the default highWaterMark used by streams.
  * @since v19.9.0
- * @param objectMode
  * @param value highWaterMark value
  */
  function setDefaultHighWaterMark(objectMode: boolean, value: number): void;
@@ -1411,11 +1415,11 @@ declare module "stream" {
  * ```
  *
  * Especially useful in error handling scenarios where a stream is destroyed
- * prematurely (like an aborted HTTP request), and will not emit `'end'`or `'finish'`.
+ * prematurely (like an aborted HTTP request), and will not emit `'end'` or `'finish'`.
  *
- * The `finished` API provides `promise version`.
+ * The `finished` API provides [promise version](https://nodejs.org/docs/latest-v20.x/api/stream.html#streamfinishedstream-options).
  *
- * `stream.finished()` leaves dangling event listeners (in particular`'error'`, `'end'`, `'finish'` and `'close'`) after `callback` has been
+ * `stream.finished()` leaves dangling event listeners (in particular `'error'`, `'end'`, `'finish'` and `'close'`) after `callback` has been
  * invoked. 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 the returned cleanup function needs to be
@@ -1430,7 +1434,7 @@ declare module "stream" {
  * @since v10.0.0
  * @param stream A readable and/or writable stream.
  * @param callback A callback function that takes an optional error argument.
- * @return A cleanup function which removes all registered listeners.
+ * @returns A cleanup function which removes all registered listeners.
  */
  function finished(
  stream: NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream,
@@ -1501,7 +1505,7 @@ declare module "stream" {
  * );
  * ```
  *
- * The `pipeline` API provides a `promise version`.
+ * 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:
  *
@@ -1541,7 +1545,7 @@ declare module "stream" {
  function pipeline<A extends PipelineSource<any>, B extends PipelineDestination<A, any>>(
  source: A,
  destination: B,
- callback?: PipelineCallback<B>,
+ callback: PipelineCallback<B>,
  ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
  function pipeline<
  A extends PipelineSource<any>,
@@ -1551,7 +1555,7 @@ declare module "stream" {
  source: A,
  transform1: T1,
  destination: B,
- callback?: PipelineCallback<B>,
+ callback: PipelineCallback<B>,
  ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
  function pipeline<
  A extends PipelineSource<any>,
@@ -1563,7 +1567,7 @@ declare module "stream" {
  transform1: T1,
  transform2: T2,
  destination: B,
- callback?: PipelineCallback<B>,
+ callback: PipelineCallback<B>,
  ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
  function pipeline<
  A extends PipelineSource<any>,
@@ -1577,7 +1581,7 @@ declare module "stream" {
  transform2: T2,
  transform3: T3,
  destination: B,
- callback?: PipelineCallback<B>,
+ callback: PipelineCallback<B>,
  ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
  function pipeline<
  A extends PipelineSource<any>,
@@ -1593,11 +1597,11 @@ declare module "stream" {
  transform3: T3,
  transform4: T4,
  destination: B,
- callback?: PipelineCallback<B>,
+ callback: PipelineCallback<B>,
  ): B extends NodeJS.WritableStream ? B : NodeJS.WritableStream;
  function pipeline(
  streams: ReadonlyArray<NodeJS.ReadableStream | NodeJS.WritableStream | NodeJS.ReadWriteStream>,
- callback?: (err: NodeJS.ErrnoException | null) => void,
+ callback: (err: NodeJS.ErrnoException | null) => void,
  ): NodeJS.WritableStream;
  function pipeline(
  stream1: NodeJS.ReadableStream,

types/node/test/stream.ts

@@ -315,7 +315,11 @@ function streamPipelineAsyncTransform() {
  );
 
  // Accepts buffer as source
- pipeline(Buffer.from("test"), stdout);
+ pipeline(
+ Buffer.from("test"),
+ stdout,
+ err => console.error(err),
+ );
 }
 
 async function streamPipelineAsyncPromiseTransform() {