aws-delivlib 14.15.34 → 14.15.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,12 +21,11 @@ declare module "stream" {
21
21
  import { Abortable, EventEmitter } from "node:events";
22
22
  import { Blob as NodeBlob } from "node:buffer";
23
23
  import * as streamPromises from "node:stream/promises";
24
- import * as streamConsumers from "node:stream/consumers";
25
24
  import * as streamWeb from "node:stream/web";
26
25
 
27
26
  type ComposeFnParam = (source: any) => void;
28
27
 
29
- class internal extends EventEmitter {
28
+ class Stream extends EventEmitter {
30
29
  pipe<T extends NodeJS.WritableStream>(
31
30
  destination: T,
32
31
  options?: {
@@ -38,919 +37,10 @@ declare module "stream" {
38
37
  options?: { signal: AbortSignal },
39
38
  ): T;
40
39
  }
41
- import Stream = internal.Stream;
42
- import Readable = internal.Readable;
43
- import ReadableOptions = internal.ReadableOptions;
44
- interface ArrayOptions {
45
- /**
46
- * The maximum concurrent invocations of `fn` to call on the stream at once.
47
- * @default 1
48
- */
49
- concurrency?: number;
50
- /** Allows destroying the stream if the signal is aborted. */
51
- signal?: AbortSignal;
52
- }
53
- class ReadableBase extends Stream implements NodeJS.ReadableStream {
54
- /**
55
- * A utility method for creating Readable Streams out of iterators.
56
- * @since v12.3.0, v10.17.0
57
- * @param iterable Object implementing the `Symbol.asyncIterator` or `Symbol.iterator` iterable protocol. Emits an 'error' event if a null value is passed.
58
- * @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`.
59
- */
60
- static from(iterable: Iterable<any> | AsyncIterable<any>, options?: ReadableOptions): Readable;
61
- /**
62
- * Returns whether the stream has been read from or cancelled.
63
- * @since v16.8.0
64
- */
65
- static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean;
66
- /**
67
- * Returns whether the stream was destroyed or errored before emitting `'end'`.
68
- * @since v16.8.0
69
- * @experimental
70
- */
71
- readonly readableAborted: boolean;
72
- /**
73
- * Is `true` if it is safe to call {@link read}, which means
74
- * the stream has not been destroyed or emitted `'error'` or `'end'`.
75
- * @since v11.4.0
76
- */
77
- readable: boolean;
78
- /**
79
- * Returns whether `'data'` has been emitted.
80
- * @since v16.7.0, v14.18.0
81
- * @experimental
82
- */
83
- readonly readableDidRead: boolean;
84
- /**
85
- * Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the {@link setEncoding} method.
86
- * @since v12.7.0
87
- */
88
- readonly readableEncoding: BufferEncoding | null;
89
- /**
90
- * Becomes `true` when [`'end'`](https://nodejs.org/docs/latest-v22.x/api/stream.html#event-end) event is emitted.
91
- * @since v12.9.0
92
- */
93
- readonly readableEnded: boolean;
94
- /**
95
- * This property reflects the current state of a `Readable` stream as described
96
- * in the [Three states](https://nodejs.org/docs/latest-v22.x/api/stream.html#three-states) section.
97
- * @since v9.4.0
98
- */
99
- readonly readableFlowing: boolean | null;
100
- /**
101
- * Returns the value of `highWaterMark` passed when creating this `Readable`.
102
- * @since v9.3.0
103
- */
104
- readonly readableHighWaterMark: number;
105
- /**
106
- * This property contains the number of bytes (or objects) in the queue
107
- * ready to be read. The value provides introspection data regarding
108
- * the status of the `highWaterMark`.
109
- * @since v9.4.0
110
- */
111
- readonly readableLength: number;
112
- /**
113
- * Getter for the property `objectMode` of a given `Readable` stream.
114
- * @since v12.3.0
115
- */
116
- readonly readableObjectMode: boolean;
117
- /**
118
- * Is `true` after `readable.destroy()` has been called.
119
- * @since v8.0.0
120
- */
121
- destroyed: boolean;
122
- /**
123
- * Is `true` after `'close'` has been emitted.
124
- * @since v18.0.0
125
- */
126
- readonly closed: boolean;
127
- /**
128
- * Returns error if the stream has been destroyed with an error.
129
- * @since v18.0.0
130
- */
131
- readonly errored: Error | null;
132
- constructor(opts?: ReadableOptions);
133
- _construct?(callback: (error?: Error | null) => void): void;
134
- _read(size: number): void;
135
- /**
136
- * The `readable.read()` method reads data out of the internal buffer and
137
- * returns it. If no data is available to be read, `null` is returned. By default,
138
- * the data is returned as a `Buffer` object unless an encoding has been
139
- * specified using the `readable.setEncoding()` method or the stream is operating
140
- * in object mode.
141
- *
142
- * The optional `size` argument specifies a specific number of bytes to read. If
143
- * `size` bytes are not available to be read, `null` will be returned _unless_ the
144
- * stream has ended, in which case all of the data remaining in the internal buffer
145
- * will be returned.
146
- *
147
- * If the `size` argument is not specified, all of the data contained in the
148
- * internal buffer will be returned.
149
- *
150
- * The `size` argument must be less than or equal to 1 GiB.
151
- *
152
- * The `readable.read()` method should only be called on `Readable` streams
153
- * operating in paused mode. In flowing mode, `readable.read()` is called
154
- * automatically until the internal buffer is fully drained.
155
- *
156
- * ```js
157
- * const readable = getReadableStreamSomehow();
158
- *
159
- * // 'readable' may be triggered multiple times as data is buffered in
160
- * readable.on('readable', () => {
161
- * let chunk;
162
- * console.log('Stream is readable (new data received in buffer)');
163
- * // Use a loop to make sure we read all currently available data
164
- * while (null !== (chunk = readable.read())) {
165
- * console.log(`Read ${chunk.length} bytes of data...`);
166
- * }
167
- * });
168
- *
169
- * // 'end' will be triggered once when there is no more data available
170
- * readable.on('end', () => {
171
- * console.log('Reached end of stream.');
172
- * });
173
- * ```
174
- *
175
- * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks
176
- * are not concatenated. A `while` loop is necessary to consume all data
177
- * currently in the buffer. When reading a large file `.read()` may return `null`,
178
- * having consumed all buffered content so far, but there is still more data to
179
- * come not yet buffered. In this case a new `'readable'` event will be emitted
180
- * when there is more data in the buffer. Finally the `'end'` event will be
181
- * emitted when there is no more data to come.
182
- *
183
- * Therefore to read a file's whole contents from a `readable`, it is necessary
184
- * to collect chunks across multiple `'readable'` events:
185
- *
186
- * ```js
187
- * const chunks = [];
188
- *
189
- * readable.on('readable', () => {
190
- * let chunk;
191
- * while (null !== (chunk = readable.read())) {
192
- * chunks.push(chunk);
193
- * }
194
- * });
195
- *
196
- * readable.on('end', () => {
197
- * const content = chunks.join('');
198
- * });
199
- * ```
200
- *
201
- * A `Readable` stream in object mode will always return a single item from
202
- * a call to `readable.read(size)`, regardless of the value of the `size` argument.
203
- *
204
- * If the `readable.read()` method returns a chunk of data, a `'data'` event will
205
- * also be emitted.
206
- *
207
- * Calling {@link read} after the `'end'` event has
208
- * been emitted will return `null`. No runtime error will be raised.
209
- * @since v0.9.4
210
- * @param size Optional argument to specify how much data to read.
211
- */
212
- read(size?: number): any;
213
- /**
214
- * The `readable.setEncoding()` method sets the character encoding for
215
- * data read from the `Readable` stream.
216
- *
217
- * By default, no encoding is assigned and stream data will be returned as `Buffer` objects. Setting an encoding causes the stream data
218
- * to be returned as strings of the specified encoding rather than as `Buffer` objects. For instance, calling `readable.setEncoding('utf8')` will cause the
219
- * 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
220
- * string format.
221
- *
222
- * The `Readable` stream will properly handle multi-byte characters delivered
223
- * through the stream that would otherwise become improperly decoded if simply
224
- * pulled from the stream as `Buffer` objects.
225
- *
226
- * ```js
227
- * const readable = getReadableStreamSomehow();
228
- * readable.setEncoding('utf8');
229
- * readable.on('data', (chunk) => {
230
- * assert.equal(typeof chunk, 'string');
231
- * console.log('Got %d characters of string data:', chunk.length);
232
- * });
233
- * ```
234
- * @since v0.9.4
235
- * @param encoding The encoding to use.
236
- */
237
- setEncoding(encoding: BufferEncoding): this;
238
- /**
239
- * The `readable.pause()` method will cause a stream in flowing mode to stop
240
- * emitting `'data'` events, switching out of flowing mode. Any data that
241
- * becomes available will remain in the internal buffer.
242
- *
243
- * ```js
244
- * const readable = getReadableStreamSomehow();
245
- * readable.on('data', (chunk) => {
246
- * console.log(`Received ${chunk.length} bytes of data.`);
247
- * readable.pause();
248
- * console.log('There will be no additional data for 1 second.');
249
- * setTimeout(() => {
250
- * console.log('Now data will start flowing again.');
251
- * readable.resume();
252
- * }, 1000);
253
- * });
254
- * ```
255
- *
256
- * The `readable.pause()` method has no effect if there is a `'readable'` event listener.
257
- * @since v0.9.4
258
- */
259
- pause(): this;
260
- /**
261
- * The `readable.resume()` method causes an explicitly paused `Readable` stream to
262
- * resume emitting `'data'` events, switching the stream into flowing mode.
263
- *
264
- * The `readable.resume()` method can be used to fully consume the data from a
265
- * stream without actually processing any of that data:
266
- *
267
- * ```js
268
- * getReadableStreamSomehow()
269
- * .resume()
270
- * .on('end', () => {
271
- * console.log('Reached the end, but did not read anything.');
272
- * });
273
- * ```
274
- *
275
- * The `readable.resume()` method has no effect if there is a `'readable'` event listener.
276
- * @since v0.9.4
277
- */
278
- resume(): this;
279
- /**
280
- * The `readable.isPaused()` method returns the current operating state of the `Readable`.
281
- * This is used primarily by the mechanism that underlies the `readable.pipe()` method.
282
- * In most typical cases, there will be no reason to use this method directly.
283
- *
284
- * ```js
285
- * const readable = new stream.Readable();
286
- *
287
- * readable.isPaused(); // === false
288
- * readable.pause();
289
- * readable.isPaused(); // === true
290
- * readable.resume();
291
- * readable.isPaused(); // === false
292
- * ```
293
- * @since v0.11.14
294
- */
295
- isPaused(): boolean;
296
- /**
297
- * The `readable.unpipe()` method detaches a `Writable` stream previously attached
298
- * using the {@link pipe} method.
299
- *
300
- * If the `destination` is not specified, then _all_ pipes are detached.
301
- *
302
- * If the `destination` is specified, but no pipe is set up for it, then
303
- * the method does nothing.
304
- *
305
- * ```js
306
- * import fs from 'node:fs';
307
- * const readable = getReadableStreamSomehow();
308
- * const writable = fs.createWriteStream('file.txt');
309
- * // All the data from readable goes into 'file.txt',
310
- * // but only for the first second.
311
- * readable.pipe(writable);
312
- * setTimeout(() => {
313
- * console.log('Stop writing to file.txt.');
314
- * readable.unpipe(writable);
315
- * console.log('Manually close the file stream.');
316
- * writable.end();
317
- * }, 1000);
318
- * ```
319
- * @since v0.9.4
320
- * @param destination Optional specific stream to unpipe
321
- */
322
- unpipe(destination?: NodeJS.WritableStream): this;
323
- /**
324
- * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the
325
- * same as `readable.push(null)`, after which no more data can be written. The EOF
326
- * signal is put at the end of the buffer and any buffered data will still be
327
- * flushed.
328
- *
329
- * The `readable.unshift()` method pushes a chunk of data back into the internal
330
- * buffer. This is useful in certain situations where a stream is being consumed by
331
- * code that needs to "un-consume" some amount of data that it has optimistically
332
- * pulled out of the source, so that the data can be passed on to some other party.
333
- *
334
- * The `stream.unshift(chunk)` method cannot be called after the `'end'` event
335
- * has been emitted or a runtime error will be thrown.
336
- *
337
- * Developers using `stream.unshift()` often should consider switching to
338
- * use of a `Transform` stream instead. See the `API for stream implementers` section for more information.
339
- *
340
- * ```js
341
- * // Pull off a header delimited by \n\n.
342
- * // Use unshift() if we get too much.
343
- * // Call the callback with (error, header, stream).
344
- * import { StringDecoder } from 'node:string_decoder';
345
- * function parseHeader(stream, callback) {
346
- * stream.on('error', callback);
347
- * stream.on('readable', onReadable);
348
- * const decoder = new StringDecoder('utf8');
349
- * let header = '';
350
- * function onReadable() {
351
- * let chunk;
352
- * while (null !== (chunk = stream.read())) {
353
- * const str = decoder.write(chunk);
354
- * if (str.includes('\n\n')) {
355
- * // Found the header boundary.
356
- * const split = str.split(/\n\n/);
357
- * header += split.shift();
358
- * const remaining = split.join('\n\n');
359
- * const buf = Buffer.from(remaining, 'utf8');
360
- * stream.removeListener('error', callback);
361
- * // Remove the 'readable' listener before unshifting.
362
- * stream.removeListener('readable', onReadable);
363
- * if (buf.length)
364
- * stream.unshift(buf);
365
- * // Now the body of the message can be read from the stream.
366
- * callback(null, header, stream);
367
- * return;
368
- * }
369
- * // Still reading the header.
370
- * header += str;
371
- * }
372
- * }
373
- * }
374
- * ```
375
- *
376
- * Unlike {@link push}, `stream.unshift(chunk)` will not
377
- * end the reading process by resetting the internal reading state of the stream.
378
- * This can cause unexpected results if `readable.unshift()` is called during a
379
- * read (i.e. from within a {@link _read} implementation on a
380
- * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately,
381
- * however it is best to simply avoid calling `readable.unshift()` while in the
382
- * process of performing a read.
383
- * @since v0.9.11
384
- * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must
385
- * be a {string}, {Buffer}, {TypedArray}, {DataView} or `null`. For object mode streams, `chunk` may be any JavaScript value.
386
- * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`.
387
- */
388
- unshift(chunk: any, encoding?: BufferEncoding): void;
389
- /**
390
- * 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
391
- * information.)
392
- *
393
- * 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`
394
- * stream that uses
395
- * the old stream as its data source.
396
- *
397
- * It will rarely be necessary to use `readable.wrap()` but the method has been
398
- * provided as a convenience for interacting with older Node.js applications and
399
- * libraries.
400
- *
401
- * ```js
402
- * import { OldReader } from './old-api-module.js';
403
- * import { Readable } from 'node:stream';
404
- * const oreader = new OldReader();
405
- * const myReader = new Readable().wrap(oreader);
406
- *
407
- * myReader.on('readable', () => {
408
- * myReader.read(); // etc.
409
- * });
410
- * ```
411
- * @since v0.9.4
412
- * @param stream An "old style" readable stream
413
- */
414
- wrap(stream: NodeJS.ReadableStream): this;
415
- push(chunk: any, encoding?: BufferEncoding): boolean;
416
- /**
417
- * The iterator created by this method gives users the option to cancel the destruction
418
- * of the stream if the `for await...of` loop is exited by `return`, `break`, or `throw`,
419
- * or if the iterator should destroy the stream if the stream emitted an error during iteration.
420
- * @since v16.3.0
421
- * @param options.destroyOnReturn When set to `false`, calling `return` on the async iterator,
422
- * or exiting a `for await...of` iteration using a `break`, `return`, or `throw` will not destroy the stream.
423
- * **Default: `true`**.
424
- */
425
- iterator(options?: { destroyOnReturn?: boolean }): NodeJS.AsyncIterator<any>;
426
- /**
427
- * This method allows mapping over the stream. The *fn* function will be called for every chunk in the stream.
428
- * If the *fn* function returns a promise - that promise will be `await`ed before being passed to the result stream.
429
- * @since v17.4.0, v16.14.0
430
- * @param fn a function to map over every chunk in the stream. Async or not.
431
- * @returns a stream mapped with the function *fn*.
432
- */
433
- map(fn: (data: any, options?: Pick<ArrayOptions, "signal">) => any, options?: ArrayOptions): Readable;
434
- /**
435
- * This method allows filtering the stream. For each chunk in the stream the *fn* function will be called
436
- * and if it returns a truthy value, the chunk will be passed to the result stream.
437
- * If the *fn* function returns a promise - that promise will be `await`ed.
438
- * @since v17.4.0, v16.14.0
439
- * @param fn a function to filter chunks from the stream. Async or not.
440
- * @returns a stream filtered with the predicate *fn*.
441
- */
442
- filter(
443
- fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
444
- options?: ArrayOptions,
445
- ): Readable;
446
- /**
447
- * This method allows iterating a stream. For each chunk in the stream the *fn* function will be called.
448
- * If the *fn* function returns a promise - that promise will be `await`ed.
449
- *
450
- * This method is different from `for await...of` loops in that it can optionally process chunks concurrently.
451
- * In addition, a `forEach` iteration can only be stopped by having passed a `signal` option
452
- * and aborting the related AbortController while `for await...of` can be stopped with `break` or `return`.
453
- * In either case the stream will be destroyed.
454
- *
455
- * This method is different from listening to the `'data'` event in that it uses the `readable` event
456
- * in the underlying machinary and can limit the number of concurrent *fn* calls.
457
- * @since v17.5.0
458
- * @param fn a function to call on each chunk of the stream. Async or not.
459
- * @returns a promise for when the stream has finished.
460
- */
461
- forEach(
462
- fn: (data: any, options?: Pick<ArrayOptions, "signal">) => void | Promise<void>,
463
- options?: ArrayOptions,
464
- ): Promise<void>;
465
- /**
466
- * This method allows easily obtaining the contents of a stream.
467
- *
468
- * As this method reads the entire stream into memory, it negates the benefits of streams. It's intended
469
- * for interoperability and convenience, not as the primary way to consume streams.
470
- * @since v17.5.0
471
- * @returns a promise containing an array with the contents of the stream.
472
- */
473
- toArray(options?: Pick<ArrayOptions, "signal">): Promise<any[]>;
474
- /**
475
- * This method is similar to `Array.prototype.some` and calls *fn* on each chunk in the stream
476
- * until the awaited return value is `true` (or any truthy value). Once an *fn* call on a chunk
477
- * `await`ed return value is truthy, the stream is destroyed and the promise is fulfilled with `true`.
478
- * If none of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `false`.
479
- * @since v17.5.0
480
- * @param fn a function to call on each chunk of the stream. Async or not.
481
- * @returns a promise evaluating to `true` if *fn* returned a truthy value for at least one of the chunks.
482
- */
483
- some(
484
- fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
485
- options?: ArrayOptions,
486
- ): Promise<boolean>;
487
- /**
488
- * This method is similar to `Array.prototype.find` and calls *fn* on each chunk in the stream
489
- * to find a chunk with a truthy value for *fn*. Once an *fn* call's awaited return value is truthy,
490
- * the stream is destroyed and the promise is fulfilled with value for which *fn* returned a truthy value.
491
- * If all of the *fn* calls on the chunks return a falsy value, the promise is fulfilled with `undefined`.
492
- * @since v17.5.0
493
- * @param fn a function to call on each chunk of the stream. Async or not.
494
- * @returns a promise evaluating to the first chunk for which *fn* evaluated with a truthy value,
495
- * or `undefined` if no element was found.
496
- */
497
- find<T>(
498
- fn: (data: any, options?: Pick<ArrayOptions, "signal">) => data is T,
499
- options?: ArrayOptions,
500
- ): Promise<T | undefined>;
501
- find(
502
- fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
503
- options?: ArrayOptions,
504
- ): Promise<any>;
505
- /**
506
- * This method is similar to `Array.prototype.every` and calls *fn* on each chunk in the stream
507
- * to check if all awaited return values are truthy value for *fn*. Once an *fn* call on a chunk
508
- * `await`ed return value is falsy, the stream is destroyed and the promise is fulfilled with `false`.
509
- * If all of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `true`.
510
- * @since v17.5.0
511
- * @param fn a function to call on each chunk of the stream. Async or not.
512
- * @returns a promise evaluating to `true` if *fn* returned a truthy value for every one of the chunks.
513
- */
514
- every(
515
- fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
516
- options?: ArrayOptions,
517
- ): Promise<boolean>;
518
- /**
519
- * This method returns a new stream by applying the given callback to each chunk of the stream
520
- * and then flattening the result.
521
- *
522
- * It is possible to return a stream or another iterable or async iterable from *fn* and the result streams
523
- * will be merged (flattened) into the returned stream.
524
- * @since v17.5.0
525
- * @param fn a function to map over every chunk in the stream. May be async. May be a stream or generator.
526
- * @returns a stream flat-mapped with the function *fn*.
527
- */
528
- flatMap(fn: (data: any, options?: Pick<ArrayOptions, "signal">) => any, options?: ArrayOptions): Readable;
529
- /**
530
- * This method returns a new stream with the first *limit* chunks dropped from the start.
531
- * @since v17.5.0
532
- * @param limit the number of chunks to drop from the readable.
533
- * @returns a stream with *limit* chunks dropped from the start.
534
- */
535
- drop(limit: number, options?: Pick<ArrayOptions, "signal">): Readable;
536
- /**
537
- * This method returns a new stream with the first *limit* chunks.
538
- * @since v17.5.0
539
- * @param limit the number of chunks to take from the readable.
540
- * @returns a stream with *limit* chunks taken.
541
- */
542
- take(limit: number, options?: Pick<ArrayOptions, "signal">): Readable;
543
- /**
544
- * This method returns a new stream with chunks of the underlying stream paired with a counter
545
- * in the form `[index, chunk]`. The first index value is `0` and it increases by 1 for each chunk produced.
546
- * @since v17.5.0
547
- * @returns a stream of indexed pairs.
548
- */
549
- asIndexedPairs(options?: Pick<ArrayOptions, "signal">): Readable;
550
- /**
551
- * This method calls *fn* on each chunk of the stream in order, passing it the result from the calculation
552
- * on the previous element. It returns a promise for the final value of the reduction.
553
- *
554
- * If no *initial* value is supplied the first chunk of the stream is used as the initial value.
555
- * If the stream is empty, the promise is rejected with a `TypeError` with the `ERR_INVALID_ARGS` code property.
556
- *
557
- * The reducer function iterates the stream element-by-element which means that there is no *concurrency* parameter
558
- * or parallelism. To perform a reduce concurrently, you can extract the async function to `readable.map` method.
559
- * @since v17.5.0
560
- * @param fn a reducer function to call over every chunk in the stream. Async or not.
561
- * @param initial the initial value to use in the reduction.
562
- * @returns a promise for the final value of the reduction.
563
- */
564
- reduce<T = any>(
565
- fn: (previous: any, data: any, options?: Pick<ArrayOptions, "signal">) => T,
566
- initial?: undefined,
567
- options?: Pick<ArrayOptions, "signal">,
568
- ): Promise<T>;
569
- reduce<T = any>(
570
- fn: (previous: T, data: any, options?: Pick<ArrayOptions, "signal">) => T,
571
- initial: T,
572
- options?: Pick<ArrayOptions, "signal">,
573
- ): Promise<T>;
574
- _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
575
- /**
576
- * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the readable
577
- * stream will release any internal resources and subsequent calls to `push()` will be ignored.
578
- *
579
- * Once `destroy()` has been called any further calls will be a no-op and no
580
- * further errors except from `_destroy()` may be emitted as `'error'`.
581
- *
582
- * Implementors should not override this method, but instead implement `readable._destroy()`.
583
- * @since v8.0.0
584
- * @param error Error which will be passed as payload in `'error'` event
585
- */
586
- destroy(error?: Error): this;
587
- /**
588
- * Event emitter
589
- * The defined events on documents including:
590
- * 1. close
591
- * 2. data
592
- * 3. end
593
- * 4. error
594
- * 5. pause
595
- * 6. readable
596
- * 7. resume
597
- */
598
- addListener(event: "close", listener: () => void): this;
599
- addListener(event: "data", listener: (chunk: any) => void): this;
600
- addListener(event: "end", listener: () => void): this;
601
- addListener(event: "error", listener: (err: Error) => void): this;
602
- addListener(event: "pause", listener: () => void): this;
603
- addListener(event: "readable", listener: () => void): this;
604
- addListener(event: "resume", listener: () => void): this;
605
- addListener(event: string | symbol, listener: (...args: any[]) => void): this;
606
- emit(event: "close"): boolean;
607
- emit(event: "data", chunk: any): boolean;
608
- emit(event: "end"): boolean;
609
- emit(event: "error", err: Error): boolean;
610
- emit(event: "pause"): boolean;
611
- emit(event: "readable"): boolean;
612
- emit(event: "resume"): boolean;
613
- emit(event: string | symbol, ...args: any[]): boolean;
614
- on(event: "close", listener: () => void): this;
615
- on(event: "data", listener: (chunk: any) => void): this;
616
- on(event: "end", listener: () => void): this;
617
- on(event: "error", listener: (err: Error) => void): this;
618
- on(event: "pause", listener: () => void): this;
619
- on(event: "readable", listener: () => void): this;
620
- on(event: "resume", listener: () => void): this;
621
- on(event: string | symbol, listener: (...args: any[]) => void): this;
622
- once(event: "close", listener: () => void): this;
623
- once(event: "data", listener: (chunk: any) => void): this;
624
- once(event: "end", listener: () => void): this;
625
- once(event: "error", listener: (err: Error) => void): this;
626
- once(event: "pause", listener: () => void): this;
627
- once(event: "readable", listener: () => void): this;
628
- once(event: "resume", listener: () => void): this;
629
- once(event: string | symbol, listener: (...args: any[]) => void): this;
630
- prependListener(event: "close", listener: () => void): this;
631
- prependListener(event: "data", listener: (chunk: any) => void): this;
632
- prependListener(event: "end", listener: () => void): this;
633
- prependListener(event: "error", listener: (err: Error) => void): this;
634
- prependListener(event: "pause", listener: () => void): this;
635
- prependListener(event: "readable", listener: () => void): this;
636
- prependListener(event: "resume", listener: () => void): this;
637
- prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
638
- prependOnceListener(event: "close", listener: () => void): this;
639
- prependOnceListener(event: "data", listener: (chunk: any) => void): this;
640
- prependOnceListener(event: "end", listener: () => void): this;
641
- prependOnceListener(event: "error", listener: (err: Error) => void): this;
642
- prependOnceListener(event: "pause", listener: () => void): this;
643
- prependOnceListener(event: "readable", listener: () => void): this;
644
- prependOnceListener(event: "resume", listener: () => void): this;
645
- prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
646
- removeListener(event: "close", listener: () => void): this;
647
- removeListener(event: "data", listener: (chunk: any) => void): this;
648
- removeListener(event: "end", listener: () => void): this;
649
- removeListener(event: "error", listener: (err: Error) => void): this;
650
- removeListener(event: "pause", listener: () => void): this;
651
- removeListener(event: "readable", listener: () => void): this;
652
- removeListener(event: "resume", listener: () => void): this;
653
- removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
654
- [Symbol.asyncIterator](): NodeJS.AsyncIterator<any>;
655
- /**
656
- * Calls `readable.destroy()` with an `AbortError` and returns a promise that fulfills when the stream is finished.
657
- * @since v20.4.0
658
- */
659
- [Symbol.asyncDispose](): Promise<void>;
40
+ namespace Stream {
41
+ export { Stream, streamPromises as promises };
660
42
  }
661
- import WritableOptions = internal.WritableOptions;
662
- class WritableBase extends Stream implements NodeJS.WritableStream {
663
- /**
664
- * Is `true` if it is safe to call `writable.write()`, which means
665
- * the stream has not been destroyed, errored, or ended.
666
- * @since v11.4.0
667
- */
668
- readonly writable: boolean;
669
- /**
670
- * Is `true` after `writable.end()` has been called. This property
671
- * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead.
672
- * @since v12.9.0
673
- */
674
- readonly writableEnded: boolean;
675
- /**
676
- * Is set to `true` immediately before the `'finish'` event is emitted.
677
- * @since v12.6.0
678
- */
679
- readonly writableFinished: boolean;
680
- /**
681
- * Return the value of `highWaterMark` passed when creating this `Writable`.
682
- * @since v9.3.0
683
- */
684
- readonly writableHighWaterMark: number;
685
- /**
686
- * This property contains the number of bytes (or objects) in the queue
687
- * ready to be written. The value provides introspection data regarding
688
- * the status of the `highWaterMark`.
689
- * @since v9.4.0
690
- */
691
- readonly writableLength: number;
692
- /**
693
- * Getter for the property `objectMode` of a given `Writable` stream.
694
- * @since v12.3.0
695
- */
696
- readonly writableObjectMode: boolean;
697
- /**
698
- * Number of times `writable.uncork()` needs to be
699
- * called in order to fully uncork the stream.
700
- * @since v13.2.0, v12.16.0
701
- */
702
- readonly writableCorked: number;
703
- /**
704
- * Is `true` after `writable.destroy()` has been called.
705
- * @since v8.0.0
706
- */
707
- destroyed: boolean;
708
- /**
709
- * Is `true` after `'close'` has been emitted.
710
- * @since v18.0.0
711
- */
712
- readonly closed: boolean;
713
- /**
714
- * Returns error if the stream has been destroyed with an error.
715
- * @since v18.0.0
716
- */
717
- readonly errored: Error | null;
718
- /**
719
- * Is `true` if the stream's buffer has been full and stream will emit `'drain'`.
720
- * @since v15.2.0, v14.17.0
721
- */
722
- readonly writableNeedDrain: boolean;
723
- constructor(opts?: WritableOptions);
724
- _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
725
- _writev?(
726
- chunks: Array<{
727
- chunk: any;
728
- encoding: BufferEncoding;
729
- }>,
730
- callback: (error?: Error | null) => void,
731
- ): void;
732
- _construct?(callback: (error?: Error | null) => void): void;
733
- _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
734
- _final(callback: (error?: Error | null) => void): void;
735
- /**
736
- * The `writable.write()` method writes some data to the stream, and calls the
737
- * supplied `callback` once the data has been fully handled. If an error
738
- * occurs, the `callback` will be called with the error as its
739
- * first argument. The `callback` is called asynchronously and before `'error'` is
740
- * emitted.
741
- *
742
- * The return value is `true` if the internal buffer is less than the `highWaterMark` configured when the stream was created after admitting `chunk`.
743
- * If `false` is returned, further attempts to write data to the stream should
744
- * stop until the `'drain'` event is emitted.
745
- *
746
- * While a stream is not draining, calls to `write()` will buffer `chunk`, and
747
- * return false. Once all currently buffered chunks are drained (accepted for
748
- * delivery by the operating system), the `'drain'` event will be emitted.
749
- * Once `write()` returns false, do not write more chunks
750
- * until the `'drain'` event is emitted. While calling `write()` on a stream that
751
- * is not draining is allowed, Node.js will buffer all written chunks until
752
- * maximum memory usage occurs, at which point it will abort unconditionally.
753
- * Even before it aborts, high memory usage will cause poor garbage collector
754
- * performance and high RSS (which is not typically released back to the system,
755
- * even after the memory is no longer required). Since TCP sockets may never
756
- * drain if the remote peer does not read the data, writing a socket that is
757
- * not draining may lead to a remotely exploitable vulnerability.
758
- *
759
- * Writing data while the stream is not draining is particularly
760
- * problematic for a `Transform`, because the `Transform` streams are paused
761
- * by default until they are piped or a `'data'` or `'readable'` event handler
762
- * is added.
763
- *
764
- * If the data to be written can be generated or fetched on demand, it is
765
- * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is
766
- * possible to respect backpressure and avoid memory issues using the `'drain'` event:
767
- *
768
- * ```js
769
- * function write(data, cb) {
770
- * if (!stream.write(data)) {
771
- * stream.once('drain', cb);
772
- * } else {
773
- * process.nextTick(cb);
774
- * }
775
- * }
776
- *
777
- * // Wait for cb to be called before doing any other write.
778
- * write('hello', () => {
779
- * console.log('Write completed, do more writes now.');
780
- * });
781
- * ```
782
- *
783
- * A `Writable` stream in object mode will always ignore the `encoding` argument.
784
- * @since v0.9.4
785
- * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
786
- * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
787
- * @param [encoding='utf8'] The encoding, if `chunk` is a string.
788
- * @param callback Callback for when this chunk of data is flushed.
789
- * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
790
- */
791
- write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean;
792
- write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean;
793
- /**
794
- * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream.
795
- * @since v0.11.15
796
- * @param encoding The new default encoding
797
- */
798
- setDefaultEncoding(encoding: BufferEncoding): this;
799
- /**
800
- * Calling the `writable.end()` method signals that no more data will be written
801
- * to the `Writable`. The optional `chunk` and `encoding` arguments allow one
802
- * final additional chunk of data to be written immediately before closing the
803
- * stream.
804
- *
805
- * Calling the {@link write} method after calling {@link end} will raise an error.
806
- *
807
- * ```js
808
- * // Write 'hello, ' and then end with 'world!'.
809
- * import fs from 'node:fs';
810
- * const file = fs.createWriteStream('example.txt');
811
- * file.write('hello, ');
812
- * file.end('world!');
813
- * // Writing more now is not allowed!
814
- * ```
815
- * @since v0.9.4
816
- * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
817
- * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
818
- * @param encoding The encoding if `chunk` is a string
819
- * @param callback Callback for when the stream is finished.
820
- */
821
- end(cb?: () => void): this;
822
- end(chunk: any, cb?: () => void): this;
823
- end(chunk: any, encoding: BufferEncoding, cb?: () => void): this;
824
- /**
825
- * The `writable.cork()` method forces all written data to be buffered in memory.
826
- * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called.
827
- *
828
- * The primary intent of `writable.cork()` is to accommodate a situation in which
829
- * several small chunks are written to the stream in rapid succession. Instead of
830
- * immediately forwarding them to the underlying destination, `writable.cork()` buffers all the chunks until `writable.uncork()` is called, which will pass them
831
- * all to `writable._writev()`, if present. This prevents a head-of-line blocking
832
- * situation where data is being buffered while waiting for the first small chunk
833
- * to be processed. However, use of `writable.cork()` without implementing `writable._writev()` may have an adverse effect on throughput.
834
- *
835
- * See also: `writable.uncork()`, `writable._writev()`.
836
- * @since v0.11.2
837
- */
838
- cork(): void;
839
- /**
840
- * The `writable.uncork()` method flushes all data buffered since {@link cork} was called.
841
- *
842
- * When using `writable.cork()` and `writable.uncork()` to manage the buffering
843
- * 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
844
- * loop phase.
845
- *
846
- * ```js
847
- * stream.cork();
848
- * stream.write('some ');
849
- * stream.write('data ');
850
- * process.nextTick(() => stream.uncork());
851
- * ```
852
- *
853
- * If the `writable.cork()` method is called multiple times on a stream, the
854
- * same number of calls to `writable.uncork()` must be called to flush the buffered
855
- * data.
856
- *
857
- * ```js
858
- * stream.cork();
859
- * stream.write('some ');
860
- * stream.cork();
861
- * stream.write('data ');
862
- * process.nextTick(() => {
863
- * stream.uncork();
864
- * // The data will not be flushed until uncork() is called a second time.
865
- * stream.uncork();
866
- * });
867
- * ```
868
- *
869
- * See also: `writable.cork()`.
870
- * @since v0.11.2
871
- */
872
- uncork(): void;
873
- /**
874
- * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the writable
875
- * stream has ended and subsequent calls to `write()` or `end()` will result in
876
- * an `ERR_STREAM_DESTROYED` error.
877
- * 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.
878
- * Use `end()` instead of destroy if data should flush before close, or wait for
879
- * the `'drain'` event before destroying the stream.
880
- *
881
- * Once `destroy()` has been called any further calls will be a no-op and no
882
- * further errors except from `_destroy()` may be emitted as `'error'`.
883
- *
884
- * Implementors should not override this method,
885
- * but instead implement `writable._destroy()`.
886
- * @since v8.0.0
887
- * @param error Optional, an error to emit with `'error'` event.
888
- */
889
- destroy(error?: Error): this;
890
- /**
891
- * Event emitter
892
- * The defined events on documents including:
893
- * 1. close
894
- * 2. drain
895
- * 3. error
896
- * 4. finish
897
- * 5. pipe
898
- * 6. unpipe
899
- */
900
- addListener(event: "close", listener: () => void): this;
901
- addListener(event: "drain", listener: () => void): this;
902
- addListener(event: "error", listener: (err: Error) => void): this;
903
- addListener(event: "finish", listener: () => void): this;
904
- addListener(event: "pipe", listener: (src: Readable) => void): this;
905
- addListener(event: "unpipe", listener: (src: Readable) => void): this;
906
- addListener(event: string | symbol, listener: (...args: any[]) => void): this;
907
- emit(event: "close"): boolean;
908
- emit(event: "drain"): boolean;
909
- emit(event: "error", err: Error): boolean;
910
- emit(event: "finish"): boolean;
911
- emit(event: "pipe", src: Readable): boolean;
912
- emit(event: "unpipe", src: Readable): boolean;
913
- emit(event: string | symbol, ...args: any[]): boolean;
914
- on(event: "close", listener: () => void): this;
915
- on(event: "drain", listener: () => void): this;
916
- on(event: "error", listener: (err: Error) => void): this;
917
- on(event: "finish", listener: () => void): this;
918
- on(event: "pipe", listener: (src: Readable) => void): this;
919
- on(event: "unpipe", listener: (src: Readable) => void): this;
920
- on(event: string | symbol, listener: (...args: any[]) => void): this;
921
- once(event: "close", listener: () => void): this;
922
- once(event: "drain", listener: () => void): this;
923
- once(event: "error", listener: (err: Error) => void): this;
924
- once(event: "finish", listener: () => void): this;
925
- once(event: "pipe", listener: (src: Readable) => void): this;
926
- once(event: "unpipe", listener: (src: Readable) => void): this;
927
- once(event: string | symbol, listener: (...args: any[]) => void): this;
928
- prependListener(event: "close", listener: () => void): this;
929
- prependListener(event: "drain", listener: () => void): this;
930
- prependListener(event: "error", listener: (err: Error) => void): this;
931
- prependListener(event: "finish", listener: () => void): this;
932
- prependListener(event: "pipe", listener: (src: Readable) => void): this;
933
- prependListener(event: "unpipe", listener: (src: Readable) => void): this;
934
- prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
935
- prependOnceListener(event: "close", listener: () => void): this;
936
- prependOnceListener(event: "drain", listener: () => void): this;
937
- prependOnceListener(event: "error", listener: (err: Error) => void): this;
938
- prependOnceListener(event: "finish", listener: () => void): this;
939
- prependOnceListener(event: "pipe", listener: (src: Readable) => void): this;
940
- prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this;
941
- prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
942
- removeListener(event: "close", listener: () => void): this;
943
- removeListener(event: "drain", listener: () => void): this;
944
- removeListener(event: "error", listener: (err: Error) => void): this;
945
- removeListener(event: "finish", listener: () => void): this;
946
- removeListener(event: "pipe", listener: (src: Readable) => void): this;
947
- removeListener(event: "unpipe", listener: (src: Readable) => void): this;
948
- removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
949
- }
950
- namespace internal {
951
- class Stream extends internal {
952
- constructor(opts?: ReadableOptions);
953
- }
43
+ namespace Stream {
954
44
  interface StreamOptions<T extends Stream> extends Abortable {
955
45
  emitClose?: boolean | undefined;
956
46
  highWaterMark?: number | undefined;
@@ -959,58 +49,673 @@ declare module "stream" {
959
49
  destroy?(this: T, error: Error | null, callback: (error?: Error | null) => void): void;
960
50
  autoDestroy?: boolean | undefined;
961
51
  }
962
- interface ReadableOptions extends StreamOptions<Readable> {
52
+ interface ReadableOptions<T extends Readable = Readable> extends StreamOptions<T> {
963
53
  encoding?: BufferEncoding | undefined;
964
- read?(this: Readable, size: number): void;
54
+ read?(this: T, size: number): void;
55
+ }
56
+ interface ArrayOptions {
57
+ /**
58
+ * The maximum concurrent invocations of `fn` to call on the stream at once.
59
+ * @default 1
60
+ */
61
+ concurrency?: number;
62
+ /** Allows destroying the stream if the signal is aborted. */
63
+ signal?: AbortSignal;
965
64
  }
966
65
  /**
967
66
  * @since v0.9.4
968
67
  */
969
- class Readable extends ReadableBase {
68
+ class Readable extends Stream implements NodeJS.ReadableStream {
69
+ /**
70
+ * A utility method for creating Readable Streams out of iterators.
71
+ * @since v12.3.0, v10.17.0
72
+ * @param iterable Object implementing the `Symbol.asyncIterator` or `Symbol.iterator` iterable protocol. Emits an 'error' event if a null value is passed.
73
+ * @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`.
74
+ */
75
+ static from(iterable: Iterable<any> | AsyncIterable<any>, options?: ReadableOptions): Readable;
76
+ /**
77
+ * A utility method for creating a `Readable` from a web `ReadableStream`.
78
+ * @since v17.0.0
79
+ * @experimental
80
+ */
81
+ static fromWeb(
82
+ readableStream: streamWeb.ReadableStream,
83
+ options?: Pick<ReadableOptions, "encoding" | "highWaterMark" | "objectMode" | "signal">,
84
+ ): Readable;
85
+ /**
86
+ * A utility method for creating a web `ReadableStream` from a `Readable`.
87
+ * @since v17.0.0
88
+ * @experimental
89
+ */
90
+ static toWeb(
91
+ streamReadable: Readable,
92
+ options?: {
93
+ strategy?: streamWeb.QueuingStrategy | undefined;
94
+ },
95
+ ): streamWeb.ReadableStream;
96
+ /**
97
+ * Returns whether the stream has been read from or cancelled.
98
+ * @since v16.8.0
99
+ */
100
+ static isDisturbed(stream: Readable | NodeJS.ReadableStream): boolean;
101
+ /**
102
+ * Returns whether the stream was destroyed or errored before emitting `'end'`.
103
+ * @since v16.8.0
104
+ * @experimental
105
+ */
106
+ readonly readableAborted: boolean;
107
+ /**
108
+ * Is `true` if it is safe to call {@link read}, which means
109
+ * the stream has not been destroyed or emitted `'error'` or `'end'`.
110
+ * @since v11.4.0
111
+ */
112
+ readable: boolean;
113
+ /**
114
+ * Returns whether `'data'` has been emitted.
115
+ * @since v16.7.0, v14.18.0
116
+ * @experimental
117
+ */
118
+ readonly readableDidRead: boolean;
119
+ /**
120
+ * Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the {@link setEncoding} method.
121
+ * @since v12.7.0
122
+ */
123
+ readonly readableEncoding: BufferEncoding | null;
124
+ /**
125
+ * Becomes `true` when [`'end'`](https://nodejs.org/docs/latest-v22.x/api/stream.html#event-end) event is emitted.
126
+ * @since v12.9.0
127
+ */
128
+ readonly readableEnded: boolean;
129
+ /**
130
+ * This property reflects the current state of a `Readable` stream as described
131
+ * in the [Three states](https://nodejs.org/docs/latest-v22.x/api/stream.html#three-states) section.
132
+ * @since v9.4.0
133
+ */
134
+ readonly readableFlowing: boolean | null;
135
+ /**
136
+ * Returns the value of `highWaterMark` passed when creating this `Readable`.
137
+ * @since v9.3.0
138
+ */
139
+ readonly readableHighWaterMark: number;
140
+ /**
141
+ * This property contains the number of bytes (or objects) in the queue
142
+ * ready to be read. The value provides introspection data regarding
143
+ * the status of the `highWaterMark`.
144
+ * @since v9.4.0
145
+ */
146
+ readonly readableLength: number;
147
+ /**
148
+ * Getter for the property `objectMode` of a given `Readable` stream.
149
+ * @since v12.3.0
150
+ */
151
+ readonly readableObjectMode: boolean;
152
+ /**
153
+ * Is `true` after `readable.destroy()` has been called.
154
+ * @since v8.0.0
155
+ */
156
+ destroyed: boolean;
157
+ /**
158
+ * Is `true` after `'close'` has been emitted.
159
+ * @since v18.0.0
160
+ */
161
+ readonly closed: boolean;
162
+ /**
163
+ * Returns error if the stream has been destroyed with an error.
164
+ * @since v18.0.0
165
+ */
166
+ readonly errored: Error | null;
167
+ constructor(opts?: ReadableOptions);
168
+ _construct?(callback: (error?: Error | null) => void): void;
169
+ _read(size: number): void;
170
+ /**
171
+ * The `readable.read()` method reads data out of the internal buffer and
172
+ * returns it. If no data is available to be read, `null` is returned. By default,
173
+ * the data is returned as a `Buffer` object unless an encoding has been
174
+ * specified using the `readable.setEncoding()` method or the stream is operating
175
+ * in object mode.
176
+ *
177
+ * The optional `size` argument specifies a specific number of bytes to read. If
178
+ * `size` bytes are not available to be read, `null` will be returned _unless_ the
179
+ * stream has ended, in which case all of the data remaining in the internal buffer
180
+ * will be returned.
181
+ *
182
+ * If the `size` argument is not specified, all of the data contained in the
183
+ * internal buffer will be returned.
184
+ *
185
+ * The `size` argument must be less than or equal to 1 GiB.
186
+ *
187
+ * The `readable.read()` method should only be called on `Readable` streams
188
+ * operating in paused mode. In flowing mode, `readable.read()` is called
189
+ * automatically until the internal buffer is fully drained.
190
+ *
191
+ * ```js
192
+ * const readable = getReadableStreamSomehow();
193
+ *
194
+ * // 'readable' may be triggered multiple times as data is buffered in
195
+ * readable.on('readable', () => {
196
+ * let chunk;
197
+ * console.log('Stream is readable (new data received in buffer)');
198
+ * // Use a loop to make sure we read all currently available data
199
+ * while (null !== (chunk = readable.read())) {
200
+ * console.log(`Read ${chunk.length} bytes of data...`);
201
+ * }
202
+ * });
203
+ *
204
+ * // 'end' will be triggered once when there is no more data available
205
+ * readable.on('end', () => {
206
+ * console.log('Reached end of stream.');
207
+ * });
208
+ * ```
209
+ *
210
+ * Each call to `readable.read()` returns a chunk of data, or `null`. The chunks
211
+ * are not concatenated. A `while` loop is necessary to consume all data
212
+ * currently in the buffer. When reading a large file `.read()` may return `null`,
213
+ * having consumed all buffered content so far, but there is still more data to
214
+ * come not yet buffered. In this case a new `'readable'` event will be emitted
215
+ * when there is more data in the buffer. Finally the `'end'` event will be
216
+ * emitted when there is no more data to come.
217
+ *
218
+ * Therefore to read a file's whole contents from a `readable`, it is necessary
219
+ * to collect chunks across multiple `'readable'` events:
220
+ *
221
+ * ```js
222
+ * const chunks = [];
223
+ *
224
+ * readable.on('readable', () => {
225
+ * let chunk;
226
+ * while (null !== (chunk = readable.read())) {
227
+ * chunks.push(chunk);
228
+ * }
229
+ * });
230
+ *
231
+ * readable.on('end', () => {
232
+ * const content = chunks.join('');
233
+ * });
234
+ * ```
235
+ *
236
+ * A `Readable` stream in object mode will always return a single item from
237
+ * a call to `readable.read(size)`, regardless of the value of the `size` argument.
238
+ *
239
+ * If the `readable.read()` method returns a chunk of data, a `'data'` event will
240
+ * also be emitted.
241
+ *
242
+ * Calling {@link read} after the `'end'` event has
243
+ * been emitted will return `null`. No runtime error will be raised.
244
+ * @since v0.9.4
245
+ * @param size Optional argument to specify how much data to read.
246
+ */
247
+ read(size?: number): any;
248
+ /**
249
+ * The `readable.setEncoding()` method sets the character encoding for
250
+ * data read from the `Readable` stream.
251
+ *
252
+ * By default, no encoding is assigned and stream data will be returned as `Buffer` objects. Setting an encoding causes the stream data
253
+ * to be returned as strings of the specified encoding rather than as `Buffer` objects. For instance, calling `readable.setEncoding('utf8')` will cause the
254
+ * 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
255
+ * string format.
256
+ *
257
+ * The `Readable` stream will properly handle multi-byte characters delivered
258
+ * through the stream that would otherwise become improperly decoded if simply
259
+ * pulled from the stream as `Buffer` objects.
260
+ *
261
+ * ```js
262
+ * const readable = getReadableStreamSomehow();
263
+ * readable.setEncoding('utf8');
264
+ * readable.on('data', (chunk) => {
265
+ * assert.equal(typeof chunk, 'string');
266
+ * console.log('Got %d characters of string data:', chunk.length);
267
+ * });
268
+ * ```
269
+ * @since v0.9.4
270
+ * @param encoding The encoding to use.
271
+ */
272
+ setEncoding(encoding: BufferEncoding): this;
273
+ /**
274
+ * The `readable.pause()` method will cause a stream in flowing mode to stop
275
+ * emitting `'data'` events, switching out of flowing mode. Any data that
276
+ * becomes available will remain in the internal buffer.
277
+ *
278
+ * ```js
279
+ * const readable = getReadableStreamSomehow();
280
+ * readable.on('data', (chunk) => {
281
+ * console.log(`Received ${chunk.length} bytes of data.`);
282
+ * readable.pause();
283
+ * console.log('There will be no additional data for 1 second.');
284
+ * setTimeout(() => {
285
+ * console.log('Now data will start flowing again.');
286
+ * readable.resume();
287
+ * }, 1000);
288
+ * });
289
+ * ```
290
+ *
291
+ * The `readable.pause()` method has no effect if there is a `'readable'` event listener.
292
+ * @since v0.9.4
293
+ */
294
+ pause(): this;
295
+ /**
296
+ * The `readable.resume()` method causes an explicitly paused `Readable` stream to
297
+ * resume emitting `'data'` events, switching the stream into flowing mode.
298
+ *
299
+ * The `readable.resume()` method can be used to fully consume the data from a
300
+ * stream without actually processing any of that data:
301
+ *
302
+ * ```js
303
+ * getReadableStreamSomehow()
304
+ * .resume()
305
+ * .on('end', () => {
306
+ * console.log('Reached the end, but did not read anything.');
307
+ * });
308
+ * ```
309
+ *
310
+ * The `readable.resume()` method has no effect if there is a `'readable'` event listener.
311
+ * @since v0.9.4
312
+ */
313
+ resume(): this;
314
+ /**
315
+ * The `readable.isPaused()` method returns the current operating state of the `Readable`.
316
+ * This is used primarily by the mechanism that underlies the `readable.pipe()` method.
317
+ * In most typical cases, there will be no reason to use this method directly.
318
+ *
319
+ * ```js
320
+ * const readable = new stream.Readable();
321
+ *
322
+ * readable.isPaused(); // === false
323
+ * readable.pause();
324
+ * readable.isPaused(); // === true
325
+ * readable.resume();
326
+ * readable.isPaused(); // === false
327
+ * ```
328
+ * @since v0.11.14
329
+ */
330
+ isPaused(): boolean;
331
+ /**
332
+ * The `readable.unpipe()` method detaches a `Writable` stream previously attached
333
+ * using the {@link pipe} method.
334
+ *
335
+ * If the `destination` is not specified, then _all_ pipes are detached.
336
+ *
337
+ * If the `destination` is specified, but no pipe is set up for it, then
338
+ * the method does nothing.
339
+ *
340
+ * ```js
341
+ * import fs from 'node:fs';
342
+ * const readable = getReadableStreamSomehow();
343
+ * const writable = fs.createWriteStream('file.txt');
344
+ * // All the data from readable goes into 'file.txt',
345
+ * // but only for the first second.
346
+ * readable.pipe(writable);
347
+ * setTimeout(() => {
348
+ * console.log('Stop writing to file.txt.');
349
+ * readable.unpipe(writable);
350
+ * console.log('Manually close the file stream.');
351
+ * writable.end();
352
+ * }, 1000);
353
+ * ```
354
+ * @since v0.9.4
355
+ * @param destination Optional specific stream to unpipe
356
+ */
357
+ unpipe(destination?: NodeJS.WritableStream): this;
358
+ /**
359
+ * Passing `chunk` as `null` signals the end of the stream (EOF) and behaves the
360
+ * same as `readable.push(null)`, after which no more data can be written. The EOF
361
+ * signal is put at the end of the buffer and any buffered data will still be
362
+ * flushed.
363
+ *
364
+ * The `readable.unshift()` method pushes a chunk of data back into the internal
365
+ * buffer. This is useful in certain situations where a stream is being consumed by
366
+ * code that needs to "un-consume" some amount of data that it has optimistically
367
+ * pulled out of the source, so that the data can be passed on to some other party.
368
+ *
369
+ * The `stream.unshift(chunk)` method cannot be called after the `'end'` event
370
+ * has been emitted or a runtime error will be thrown.
371
+ *
372
+ * Developers using `stream.unshift()` often should consider switching to
373
+ * use of a `Transform` stream instead. See the `API for stream implementers` section for more information.
374
+ *
375
+ * ```js
376
+ * // Pull off a header delimited by \n\n.
377
+ * // Use unshift() if we get too much.
378
+ * // Call the callback with (error, header, stream).
379
+ * import { StringDecoder } from 'node:string_decoder';
380
+ * function parseHeader(stream, callback) {
381
+ * stream.on('error', callback);
382
+ * stream.on('readable', onReadable);
383
+ * const decoder = new StringDecoder('utf8');
384
+ * let header = '';
385
+ * function onReadable() {
386
+ * let chunk;
387
+ * while (null !== (chunk = stream.read())) {
388
+ * const str = decoder.write(chunk);
389
+ * if (str.includes('\n\n')) {
390
+ * // Found the header boundary.
391
+ * const split = str.split(/\n\n/);
392
+ * header += split.shift();
393
+ * const remaining = split.join('\n\n');
394
+ * const buf = Buffer.from(remaining, 'utf8');
395
+ * stream.removeListener('error', callback);
396
+ * // Remove the 'readable' listener before unshifting.
397
+ * stream.removeListener('readable', onReadable);
398
+ * if (buf.length)
399
+ * stream.unshift(buf);
400
+ * // Now the body of the message can be read from the stream.
401
+ * callback(null, header, stream);
402
+ * return;
403
+ * }
404
+ * // Still reading the header.
405
+ * header += str;
406
+ * }
407
+ * }
408
+ * }
409
+ * ```
410
+ *
411
+ * Unlike {@link push}, `stream.unshift(chunk)` will not
412
+ * end the reading process by resetting the internal reading state of the stream.
413
+ * This can cause unexpected results if `readable.unshift()` is called during a
414
+ * read (i.e. from within a {@link _read} implementation on a
415
+ * custom stream). Following the call to `readable.unshift()` with an immediate {@link push} will reset the reading state appropriately,
416
+ * however it is best to simply avoid calling `readable.unshift()` while in the
417
+ * process of performing a read.
418
+ * @since v0.9.11
419
+ * @param chunk Chunk of data to unshift onto the read queue. For streams not operating in object mode, `chunk` must
420
+ * be a {string}, {Buffer}, {TypedArray}, {DataView} or `null`. For object mode streams, `chunk` may be any JavaScript value.
421
+ * @param encoding Encoding of string chunks. Must be a valid `Buffer` encoding, such as `'utf8'` or `'ascii'`.
422
+ */
423
+ unshift(chunk: any, encoding?: BufferEncoding): void;
424
+ /**
425
+ * 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
426
+ * information.)
427
+ *
428
+ * 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`
429
+ * stream that uses
430
+ * the old stream as its data source.
431
+ *
432
+ * It will rarely be necessary to use `readable.wrap()` but the method has been
433
+ * provided as a convenience for interacting with older Node.js applications and
434
+ * libraries.
435
+ *
436
+ * ```js
437
+ * import { OldReader } from './old-api-module.js';
438
+ * import { Readable } from 'node:stream';
439
+ * const oreader = new OldReader();
440
+ * const myReader = new Readable().wrap(oreader);
441
+ *
442
+ * myReader.on('readable', () => {
443
+ * myReader.read(); // etc.
444
+ * });
445
+ * ```
446
+ * @since v0.9.4
447
+ * @param stream An "old style" readable stream
448
+ */
449
+ wrap(stream: NodeJS.ReadableStream): this;
450
+ push(chunk: any, encoding?: BufferEncoding): boolean;
451
+ /**
452
+ * The iterator created by this method gives users the option to cancel the destruction
453
+ * of the stream if the `for await...of` loop is exited by `return`, `break`, or `throw`,
454
+ * or if the iterator should destroy the stream if the stream emitted an error during iteration.
455
+ * @since v16.3.0
456
+ * @param options.destroyOnReturn When set to `false`, calling `return` on the async iterator,
457
+ * or exiting a `for await...of` iteration using a `break`, `return`, or `throw` will not destroy the stream.
458
+ * **Default: `true`**.
459
+ */
460
+ iterator(options?: { destroyOnReturn?: boolean }): NodeJS.AsyncIterator<any>;
461
+ /**
462
+ * This method allows mapping over the stream. The *fn* function will be called for every chunk in the stream.
463
+ * If the *fn* function returns a promise - that promise will be `await`ed before being passed to the result stream.
464
+ * @since v17.4.0, v16.14.0
465
+ * @param fn a function to map over every chunk in the stream. Async or not.
466
+ * @returns a stream mapped with the function *fn*.
467
+ */
468
+ map(fn: (data: any, options?: Pick<ArrayOptions, "signal">) => any, options?: ArrayOptions): Readable;
469
+ /**
470
+ * This method allows filtering the stream. For each chunk in the stream the *fn* function will be called
471
+ * and if it returns a truthy value, the chunk will be passed to the result stream.
472
+ * If the *fn* function returns a promise - that promise will be `await`ed.
473
+ * @since v17.4.0, v16.14.0
474
+ * @param fn a function to filter chunks from the stream. Async or not.
475
+ * @returns a stream filtered with the predicate *fn*.
476
+ */
477
+ filter(
478
+ fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
479
+ options?: ArrayOptions,
480
+ ): Readable;
481
+ /**
482
+ * This method allows iterating a stream. For each chunk in the stream the *fn* function will be called.
483
+ * If the *fn* function returns a promise - that promise will be `await`ed.
484
+ *
485
+ * This method is different from `for await...of` loops in that it can optionally process chunks concurrently.
486
+ * In addition, a `forEach` iteration can only be stopped by having passed a `signal` option
487
+ * and aborting the related AbortController while `for await...of` can be stopped with `break` or `return`.
488
+ * In either case the stream will be destroyed.
489
+ *
490
+ * This method is different from listening to the `'data'` event in that it uses the `readable` event
491
+ * in the underlying machinary and can limit the number of concurrent *fn* calls.
492
+ * @since v17.5.0
493
+ * @param fn a function to call on each chunk of the stream. Async or not.
494
+ * @returns a promise for when the stream has finished.
495
+ */
496
+ forEach(
497
+ fn: (data: any, options?: Pick<ArrayOptions, "signal">) => void | Promise<void>,
498
+ options?: ArrayOptions,
499
+ ): Promise<void>;
500
+ /**
501
+ * This method allows easily obtaining the contents of a stream.
502
+ *
503
+ * As this method reads the entire stream into memory, it negates the benefits of streams. It's intended
504
+ * for interoperability and convenience, not as the primary way to consume streams.
505
+ * @since v17.5.0
506
+ * @returns a promise containing an array with the contents of the stream.
507
+ */
508
+ toArray(options?: Pick<ArrayOptions, "signal">): Promise<any[]>;
509
+ /**
510
+ * This method is similar to `Array.prototype.some` and calls *fn* on each chunk in the stream
511
+ * until the awaited return value is `true` (or any truthy value). Once an *fn* call on a chunk
512
+ * `await`ed return value is truthy, the stream is destroyed and the promise is fulfilled with `true`.
513
+ * If none of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `false`.
514
+ * @since v17.5.0
515
+ * @param fn a function to call on each chunk of the stream. Async or not.
516
+ * @returns a promise evaluating to `true` if *fn* returned a truthy value for at least one of the chunks.
517
+ */
518
+ some(
519
+ fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
520
+ options?: ArrayOptions,
521
+ ): Promise<boolean>;
522
+ /**
523
+ * This method is similar to `Array.prototype.find` and calls *fn* on each chunk in the stream
524
+ * to find a chunk with a truthy value for *fn*. Once an *fn* call's awaited return value is truthy,
525
+ * the stream is destroyed and the promise is fulfilled with value for which *fn* returned a truthy value.
526
+ * If all of the *fn* calls on the chunks return a falsy value, the promise is fulfilled with `undefined`.
527
+ * @since v17.5.0
528
+ * @param fn a function to call on each chunk of the stream. Async or not.
529
+ * @returns a promise evaluating to the first chunk for which *fn* evaluated with a truthy value,
530
+ * or `undefined` if no element was found.
531
+ */
532
+ find<T>(
533
+ fn: (data: any, options?: Pick<ArrayOptions, "signal">) => data is T,
534
+ options?: ArrayOptions,
535
+ ): Promise<T | undefined>;
536
+ find(
537
+ fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
538
+ options?: ArrayOptions,
539
+ ): Promise<any>;
540
+ /**
541
+ * This method is similar to `Array.prototype.every` and calls *fn* on each chunk in the stream
542
+ * to check if all awaited return values are truthy value for *fn*. Once an *fn* call on a chunk
543
+ * `await`ed return value is falsy, the stream is destroyed and the promise is fulfilled with `false`.
544
+ * If all of the *fn* calls on the chunks return a truthy value, the promise is fulfilled with `true`.
545
+ * @since v17.5.0
546
+ * @param fn a function to call on each chunk of the stream. Async or not.
547
+ * @returns a promise evaluating to `true` if *fn* returned a truthy value for every one of the chunks.
548
+ */
549
+ every(
550
+ fn: (data: any, options?: Pick<ArrayOptions, "signal">) => boolean | Promise<boolean>,
551
+ options?: ArrayOptions,
552
+ ): Promise<boolean>;
553
+ /**
554
+ * This method returns a new stream by applying the given callback to each chunk of the stream
555
+ * and then flattening the result.
556
+ *
557
+ * It is possible to return a stream or another iterable or async iterable from *fn* and the result streams
558
+ * will be merged (flattened) into the returned stream.
559
+ * @since v17.5.0
560
+ * @param fn a function to map over every chunk in the stream. May be async. May be a stream or generator.
561
+ * @returns a stream flat-mapped with the function *fn*.
562
+ */
563
+ flatMap(fn: (data: any, options?: Pick<ArrayOptions, "signal">) => any, options?: ArrayOptions): Readable;
564
+ /**
565
+ * This method returns a new stream with the first *limit* chunks dropped from the start.
566
+ * @since v17.5.0
567
+ * @param limit the number of chunks to drop from the readable.
568
+ * @returns a stream with *limit* chunks dropped from the start.
569
+ */
570
+ drop(limit: number, options?: Pick<ArrayOptions, "signal">): Readable;
571
+ /**
572
+ * This method returns a new stream with the first *limit* chunks.
573
+ * @since v17.5.0
574
+ * @param limit the number of chunks to take from the readable.
575
+ * @returns a stream with *limit* chunks taken.
576
+ */
577
+ take(limit: number, options?: Pick<ArrayOptions, "signal">): Readable;
578
+ /**
579
+ * This method returns a new stream with chunks of the underlying stream paired with a counter
580
+ * in the form `[index, chunk]`. The first index value is `0` and it increases by 1 for each chunk produced.
581
+ * @since v17.5.0
582
+ * @returns a stream of indexed pairs.
583
+ */
584
+ asIndexedPairs(options?: Pick<ArrayOptions, "signal">): Readable;
585
+ /**
586
+ * This method calls *fn* on each chunk of the stream in order, passing it the result from the calculation
587
+ * on the previous element. It returns a promise for the final value of the reduction.
588
+ *
589
+ * If no *initial* value is supplied the first chunk of the stream is used as the initial value.
590
+ * If the stream is empty, the promise is rejected with a `TypeError` with the `ERR_INVALID_ARGS` code property.
591
+ *
592
+ * The reducer function iterates the stream element-by-element which means that there is no *concurrency* parameter
593
+ * or parallelism. To perform a reduce concurrently, you can extract the async function to `readable.map` method.
594
+ * @since v17.5.0
595
+ * @param fn a reducer function to call over every chunk in the stream. Async or not.
596
+ * @param initial the initial value to use in the reduction.
597
+ * @returns a promise for the final value of the reduction.
598
+ */
599
+ reduce<T = any>(
600
+ fn: (previous: any, data: any, options?: Pick<ArrayOptions, "signal">) => T,
601
+ initial?: undefined,
602
+ options?: Pick<ArrayOptions, "signal">,
603
+ ): Promise<T>;
604
+ reduce<T = any>(
605
+ fn: (previous: T, data: any, options?: Pick<ArrayOptions, "signal">) => T,
606
+ initial: T,
607
+ options?: Pick<ArrayOptions, "signal">,
608
+ ): Promise<T>;
609
+ _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
970
610
  /**
971
- * A utility method for creating a `Readable` from a web `ReadableStream`.
972
- * @since v17.0.0
973
- * @experimental
611
+ * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the readable
612
+ * stream will release any internal resources and subsequent calls to `push()` will be ignored.
613
+ *
614
+ * Once `destroy()` has been called any further calls will be a no-op and no
615
+ * further errors except from `_destroy()` may be emitted as `'error'`.
616
+ *
617
+ * Implementors should not override this method, but instead implement `readable._destroy()`.
618
+ * @since v8.0.0
619
+ * @param error Error which will be passed as payload in `'error'` event
974
620
  */
975
- static fromWeb(
976
- readableStream: streamWeb.ReadableStream,
977
- options?: Pick<ReadableOptions, "encoding" | "highWaterMark" | "objectMode" | "signal">,
978
- ): Readable;
621
+ destroy(error?: Error): this;
979
622
  /**
980
- * A utility method for creating a web `ReadableStream` from a `Readable`.
981
- * @since v17.0.0
982
- * @experimental
623
+ * Event emitter
624
+ * The defined events on documents including:
625
+ * 1. close
626
+ * 2. data
627
+ * 3. end
628
+ * 4. error
629
+ * 5. pause
630
+ * 6. readable
631
+ * 7. resume
983
632
  */
984
- static toWeb(
985
- streamReadable: Readable,
986
- options?: {
987
- strategy?: streamWeb.QueuingStrategy | undefined;
988
- },
989
- ): streamWeb.ReadableStream;
633
+ addListener(event: "close", listener: () => void): this;
634
+ addListener(event: "data", listener: (chunk: any) => void): this;
635
+ addListener(event: "end", listener: () => void): this;
636
+ addListener(event: "error", listener: (err: Error) => void): this;
637
+ addListener(event: "pause", listener: () => void): this;
638
+ addListener(event: "readable", listener: () => void): this;
639
+ addListener(event: "resume", listener: () => void): this;
640
+ addListener(event: string | symbol, listener: (...args: any[]) => void): this;
641
+ emit(event: "close"): boolean;
642
+ emit(event: "data", chunk: any): boolean;
643
+ emit(event: "end"): boolean;
644
+ emit(event: "error", err: Error): boolean;
645
+ emit(event: "pause"): boolean;
646
+ emit(event: "readable"): boolean;
647
+ emit(event: "resume"): boolean;
648
+ emit(event: string | symbol, ...args: any[]): boolean;
649
+ on(event: "close", listener: () => void): this;
650
+ on(event: "data", listener: (chunk: any) => void): this;
651
+ on(event: "end", listener: () => void): this;
652
+ on(event: "error", listener: (err: Error) => void): this;
653
+ on(event: "pause", listener: () => void): this;
654
+ on(event: "readable", listener: () => void): this;
655
+ on(event: "resume", listener: () => void): this;
656
+ on(event: string | symbol, listener: (...args: any[]) => void): this;
657
+ once(event: "close", listener: () => void): this;
658
+ once(event: "data", listener: (chunk: any) => void): this;
659
+ once(event: "end", listener: () => void): this;
660
+ once(event: "error", listener: (err: Error) => void): this;
661
+ once(event: "pause", listener: () => void): this;
662
+ once(event: "readable", listener: () => void): this;
663
+ once(event: "resume", listener: () => void): this;
664
+ once(event: string | symbol, listener: (...args: any[]) => void): this;
665
+ prependListener(event: "close", listener: () => void): this;
666
+ prependListener(event: "data", listener: (chunk: any) => void): this;
667
+ prependListener(event: "end", listener: () => void): this;
668
+ prependListener(event: "error", listener: (err: Error) => void): this;
669
+ prependListener(event: "pause", listener: () => void): this;
670
+ prependListener(event: "readable", listener: () => void): this;
671
+ prependListener(event: "resume", listener: () => void): this;
672
+ prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
673
+ prependOnceListener(event: "close", listener: () => void): this;
674
+ prependOnceListener(event: "data", listener: (chunk: any) => void): this;
675
+ prependOnceListener(event: "end", listener: () => void): this;
676
+ prependOnceListener(event: "error", listener: (err: Error) => void): this;
677
+ prependOnceListener(event: "pause", listener: () => void): this;
678
+ prependOnceListener(event: "readable", listener: () => void): this;
679
+ prependOnceListener(event: "resume", listener: () => void): this;
680
+ prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
681
+ removeListener(event: "close", listener: () => void): this;
682
+ removeListener(event: "data", listener: (chunk: any) => void): this;
683
+ removeListener(event: "end", listener: () => void): this;
684
+ removeListener(event: "error", listener: (err: Error) => void): this;
685
+ removeListener(event: "pause", listener: () => void): this;
686
+ removeListener(event: "readable", listener: () => void): this;
687
+ removeListener(event: "resume", listener: () => void): this;
688
+ removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
689
+ [Symbol.asyncIterator](): NodeJS.AsyncIterator<any>;
690
+ /**
691
+ * Calls `readable.destroy()` with an `AbortError` and returns a promise that fulfills when the stream is finished.
692
+ * @since v20.4.0
693
+ */
694
+ [Symbol.asyncDispose](): Promise<void>;
990
695
  }
991
- interface WritableOptions extends StreamOptions<Writable> {
696
+ interface WritableOptions<T extends Writable = Writable> extends StreamOptions<T> {
992
697
  decodeStrings?: boolean | undefined;
993
698
  defaultEncoding?: BufferEncoding | undefined;
994
699
  write?(
995
- this: Writable,
700
+ this: T,
996
701
  chunk: any,
997
702
  encoding: BufferEncoding,
998
703
  callback: (error?: Error | null) => void,
999
704
  ): void;
1000
705
  writev?(
1001
- this: Writable,
706
+ this: T,
1002
707
  chunks: Array<{
1003
708
  chunk: any;
1004
709
  encoding: BufferEncoding;
1005
710
  }>,
1006
711
  callback: (error?: Error | null) => void,
1007
712
  ): void;
1008
- final?(this: Writable, callback: (error?: Error | null) => void): void;
713
+ final?(this: T, callback: (error?: Error | null) => void): void;
1009
714
  }
1010
715
  /**
1011
716
  * @since v0.9.4
1012
717
  */
1013
- class Writable extends WritableBase {
718
+ class Writable extends Stream implements NodeJS.WritableStream {
1014
719
  /**
1015
720
  * A utility method for creating a `Writable` from a web `WritableStream`.
1016
721
  * @since v17.0.0
@@ -1026,27 +731,300 @@ declare module "stream" {
1026
731
  * @experimental
1027
732
  */
1028
733
  static toWeb(streamWritable: Writable): streamWeb.WritableStream;
734
+ /**
735
+ * Is `true` if it is safe to call `writable.write()`, which means
736
+ * the stream has not been destroyed, errored, or ended.
737
+ * @since v11.4.0
738
+ */
739
+ readonly writable: boolean;
740
+ /**
741
+ * Is `true` after `writable.end()` has been called. This property
742
+ * does not indicate whether the data has been flushed, for this use `writable.writableFinished` instead.
743
+ * @since v12.9.0
744
+ */
745
+ readonly writableEnded: boolean;
746
+ /**
747
+ * Is set to `true` immediately before the `'finish'` event is emitted.
748
+ * @since v12.6.0
749
+ */
750
+ readonly writableFinished: boolean;
751
+ /**
752
+ * Return the value of `highWaterMark` passed when creating this `Writable`.
753
+ * @since v9.3.0
754
+ */
755
+ readonly writableHighWaterMark: number;
756
+ /**
757
+ * This property contains the number of bytes (or objects) in the queue
758
+ * ready to be written. The value provides introspection data regarding
759
+ * the status of the `highWaterMark`.
760
+ * @since v9.4.0
761
+ */
762
+ readonly writableLength: number;
763
+ /**
764
+ * Getter for the property `objectMode` of a given `Writable` stream.
765
+ * @since v12.3.0
766
+ */
767
+ readonly writableObjectMode: boolean;
768
+ /**
769
+ * Number of times `writable.uncork()` needs to be
770
+ * called in order to fully uncork the stream.
771
+ * @since v13.2.0, v12.16.0
772
+ */
773
+ readonly writableCorked: number;
774
+ /**
775
+ * Is `true` after `writable.destroy()` has been called.
776
+ * @since v8.0.0
777
+ */
778
+ destroyed: boolean;
779
+ /**
780
+ * Is `true` after `'close'` has been emitted.
781
+ * @since v18.0.0
782
+ */
783
+ readonly closed: boolean;
784
+ /**
785
+ * Returns error if the stream has been destroyed with an error.
786
+ * @since v18.0.0
787
+ */
788
+ readonly errored: Error | null;
789
+ /**
790
+ * Is `true` if the stream's buffer has been full and stream will emit `'drain'`.
791
+ * @since v15.2.0, v14.17.0
792
+ */
793
+ readonly writableNeedDrain: boolean;
794
+ constructor(opts?: WritableOptions);
795
+ _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
796
+ _writev?(
797
+ chunks: Array<{
798
+ chunk: any;
799
+ encoding: BufferEncoding;
800
+ }>,
801
+ callback: (error?: Error | null) => void,
802
+ ): void;
803
+ _construct?(callback: (error?: Error | null) => void): void;
804
+ _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
805
+ _final(callback: (error?: Error | null) => void): void;
806
+ /**
807
+ * The `writable.write()` method writes some data to the stream, and calls the
808
+ * supplied `callback` once the data has been fully handled. If an error
809
+ * occurs, the `callback` will be called with the error as its
810
+ * first argument. The `callback` is called asynchronously and before `'error'` is
811
+ * emitted.
812
+ *
813
+ * The return value is `true` if the internal buffer is less than the `highWaterMark` configured when the stream was created after admitting `chunk`.
814
+ * If `false` is returned, further attempts to write data to the stream should
815
+ * stop until the `'drain'` event is emitted.
816
+ *
817
+ * While a stream is not draining, calls to `write()` will buffer `chunk`, and
818
+ * return false. Once all currently buffered chunks are drained (accepted for
819
+ * delivery by the operating system), the `'drain'` event will be emitted.
820
+ * Once `write()` returns false, do not write more chunks
821
+ * until the `'drain'` event is emitted. While calling `write()` on a stream that
822
+ * is not draining is allowed, Node.js will buffer all written chunks until
823
+ * maximum memory usage occurs, at which point it will abort unconditionally.
824
+ * Even before it aborts, high memory usage will cause poor garbage collector
825
+ * performance and high RSS (which is not typically released back to the system,
826
+ * even after the memory is no longer required). Since TCP sockets may never
827
+ * drain if the remote peer does not read the data, writing a socket that is
828
+ * not draining may lead to a remotely exploitable vulnerability.
829
+ *
830
+ * Writing data while the stream is not draining is particularly
831
+ * problematic for a `Transform`, because the `Transform` streams are paused
832
+ * by default until they are piped or a `'data'` or `'readable'` event handler
833
+ * is added.
834
+ *
835
+ * If the data to be written can be generated or fetched on demand, it is
836
+ * recommended to encapsulate the logic into a `Readable` and use {@link pipe}. However, if calling `write()` is preferred, it is
837
+ * possible to respect backpressure and avoid memory issues using the `'drain'` event:
838
+ *
839
+ * ```js
840
+ * function write(data, cb) {
841
+ * if (!stream.write(data)) {
842
+ * stream.once('drain', cb);
843
+ * } else {
844
+ * process.nextTick(cb);
845
+ * }
846
+ * }
847
+ *
848
+ * // Wait for cb to be called before doing any other write.
849
+ * write('hello', () => {
850
+ * console.log('Write completed, do more writes now.');
851
+ * });
852
+ * ```
853
+ *
854
+ * A `Writable` stream in object mode will always ignore the `encoding` argument.
855
+ * @since v0.9.4
856
+ * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
857
+ * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
858
+ * @param [encoding='utf8'] The encoding, if `chunk` is a string.
859
+ * @param callback Callback for when this chunk of data is flushed.
860
+ * @return `false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.
861
+ */
862
+ write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean;
863
+ write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean;
864
+ /**
865
+ * The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream.
866
+ * @since v0.11.15
867
+ * @param encoding The new default encoding
868
+ */
869
+ setDefaultEncoding(encoding: BufferEncoding): this;
870
+ /**
871
+ * Calling the `writable.end()` method signals that no more data will be written
872
+ * to the `Writable`. The optional `chunk` and `encoding` arguments allow one
873
+ * final additional chunk of data to be written immediately before closing the
874
+ * stream.
875
+ *
876
+ * Calling the {@link write} method after calling {@link end} will raise an error.
877
+ *
878
+ * ```js
879
+ * // Write 'hello, ' and then end with 'world!'.
880
+ * import fs from 'node:fs';
881
+ * const file = fs.createWriteStream('example.txt');
882
+ * file.write('hello, ');
883
+ * file.end('world!');
884
+ * // Writing more now is not allowed!
885
+ * ```
886
+ * @since v0.9.4
887
+ * @param chunk Optional data to write. For streams not operating in object mode, `chunk` must be a {string}, {Buffer},
888
+ * {TypedArray} or {DataView}. For object mode streams, `chunk` may be any JavaScript value other than `null`.
889
+ * @param encoding The encoding if `chunk` is a string
890
+ * @param callback Callback for when the stream is finished.
891
+ */
892
+ end(cb?: () => void): this;
893
+ end(chunk: any, cb?: () => void): this;
894
+ end(chunk: any, encoding: BufferEncoding, cb?: () => void): this;
895
+ /**
896
+ * The `writable.cork()` method forces all written data to be buffered in memory.
897
+ * The buffered data will be flushed when either the {@link uncork} or {@link end} methods are called.
898
+ *
899
+ * The primary intent of `writable.cork()` is to accommodate a situation in which
900
+ * several small chunks are written to the stream in rapid succession. Instead of
901
+ * immediately forwarding them to the underlying destination, `writable.cork()` buffers all the chunks until `writable.uncork()` is called, which will pass them
902
+ * all to `writable._writev()`, if present. This prevents a head-of-line blocking
903
+ * situation where data is being buffered while waiting for the first small chunk
904
+ * to be processed. However, use of `writable.cork()` without implementing `writable._writev()` may have an adverse effect on throughput.
905
+ *
906
+ * See also: `writable.uncork()`, `writable._writev()`.
907
+ * @since v0.11.2
908
+ */
909
+ cork(): void;
910
+ /**
911
+ * The `writable.uncork()` method flushes all data buffered since {@link cork} was called.
912
+ *
913
+ * When using `writable.cork()` and `writable.uncork()` to manage the buffering
914
+ * 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
915
+ * loop phase.
916
+ *
917
+ * ```js
918
+ * stream.cork();
919
+ * stream.write('some ');
920
+ * stream.write('data ');
921
+ * process.nextTick(() => stream.uncork());
922
+ * ```
923
+ *
924
+ * If the `writable.cork()` method is called multiple times on a stream, the
925
+ * same number of calls to `writable.uncork()` must be called to flush the buffered
926
+ * data.
927
+ *
928
+ * ```js
929
+ * stream.cork();
930
+ * stream.write('some ');
931
+ * stream.cork();
932
+ * stream.write('data ');
933
+ * process.nextTick(() => {
934
+ * stream.uncork();
935
+ * // The data will not be flushed until uncork() is called a second time.
936
+ * stream.uncork();
937
+ * });
938
+ * ```
939
+ *
940
+ * See also: `writable.cork()`.
941
+ * @since v0.11.2
942
+ */
943
+ uncork(): void;
944
+ /**
945
+ * Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event (unless `emitClose` is set to `false`). After this call, the writable
946
+ * stream has ended and subsequent calls to `write()` or `end()` will result in
947
+ * an `ERR_STREAM_DESTROYED` error.
948
+ * 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.
949
+ * Use `end()` instead of destroy if data should flush before close, or wait for
950
+ * the `'drain'` event before destroying the stream.
951
+ *
952
+ * Once `destroy()` has been called any further calls will be a no-op and no
953
+ * further errors except from `_destroy()` may be emitted as `'error'`.
954
+ *
955
+ * Implementors should not override this method,
956
+ * but instead implement `writable._destroy()`.
957
+ * @since v8.0.0
958
+ * @param error Optional, an error to emit with `'error'` event.
959
+ */
960
+ destroy(error?: Error): this;
961
+ /**
962
+ * Event emitter
963
+ * The defined events on documents including:
964
+ * 1. close
965
+ * 2. drain
966
+ * 3. error
967
+ * 4. finish
968
+ * 5. pipe
969
+ * 6. unpipe
970
+ */
971
+ addListener(event: "close", listener: () => void): this;
972
+ addListener(event: "drain", listener: () => void): this;
973
+ addListener(event: "error", listener: (err: Error) => void): this;
974
+ addListener(event: "finish", listener: () => void): this;
975
+ addListener(event: "pipe", listener: (src: Readable) => void): this;
976
+ addListener(event: "unpipe", listener: (src: Readable) => void): this;
977
+ addListener(event: string | symbol, listener: (...args: any[]) => void): this;
978
+ emit(event: "close"): boolean;
979
+ emit(event: "drain"): boolean;
980
+ emit(event: "error", err: Error): boolean;
981
+ emit(event: "finish"): boolean;
982
+ emit(event: "pipe", src: Readable): boolean;
983
+ emit(event: "unpipe", src: Readable): boolean;
984
+ emit(event: string | symbol, ...args: any[]): boolean;
985
+ on(event: "close", listener: () => void): this;
986
+ on(event: "drain", listener: () => void): this;
987
+ on(event: "error", listener: (err: Error) => void): this;
988
+ on(event: "finish", listener: () => void): this;
989
+ on(event: "pipe", listener: (src: Readable) => void): this;
990
+ on(event: "unpipe", listener: (src: Readable) => void): this;
991
+ on(event: string | symbol, listener: (...args: any[]) => void): this;
992
+ once(event: "close", listener: () => void): this;
993
+ once(event: "drain", listener: () => void): this;
994
+ once(event: "error", listener: (err: Error) => void): this;
995
+ once(event: "finish", listener: () => void): this;
996
+ once(event: "pipe", listener: (src: Readable) => void): this;
997
+ once(event: "unpipe", listener: (src: Readable) => void): this;
998
+ once(event: string | symbol, listener: (...args: any[]) => void): this;
999
+ prependListener(event: "close", listener: () => void): this;
1000
+ prependListener(event: "drain", listener: () => void): this;
1001
+ prependListener(event: "error", listener: (err: Error) => void): this;
1002
+ prependListener(event: "finish", listener: () => void): this;
1003
+ prependListener(event: "pipe", listener: (src: Readable) => void): this;
1004
+ prependListener(event: "unpipe", listener: (src: Readable) => void): this;
1005
+ prependListener(event: string | symbol, listener: (...args: any[]) => void): this;
1006
+ prependOnceListener(event: "close", listener: () => void): this;
1007
+ prependOnceListener(event: "drain", listener: () => void): this;
1008
+ prependOnceListener(event: "error", listener: (err: Error) => void): this;
1009
+ prependOnceListener(event: "finish", listener: () => void): this;
1010
+ prependOnceListener(event: "pipe", listener: (src: Readable) => void): this;
1011
+ prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this;
1012
+ prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this;
1013
+ removeListener(event: "close", listener: () => void): this;
1014
+ removeListener(event: "drain", listener: () => void): this;
1015
+ removeListener(event: "error", listener: (err: Error) => void): this;
1016
+ removeListener(event: "finish", listener: () => void): this;
1017
+ removeListener(event: "pipe", listener: (src: Readable) => void): this;
1018
+ removeListener(event: "unpipe", listener: (src: Readable) => void): this;
1019
+ removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
1029
1020
  }
1030
- interface DuplexOptions extends ReadableOptions, WritableOptions {
1021
+ interface DuplexOptions<T extends Duplex = Duplex> extends ReadableOptions<T>, WritableOptions<T> {
1031
1022
  allowHalfOpen?: boolean | undefined;
1032
1023
  readableObjectMode?: boolean | undefined;
1033
1024
  writableObjectMode?: boolean | undefined;
1034
1025
  readableHighWaterMark?: number | undefined;
1035
1026
  writableHighWaterMark?: number | undefined;
1036
1027
  writableCorked?: number | undefined;
1037
- construct?(this: Duplex, callback: (error?: Error | null) => void): void;
1038
- read?(this: Duplex, size: number): void;
1039
- write?(this: Duplex, chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
1040
- writev?(
1041
- this: Duplex,
1042
- chunks: Array<{
1043
- chunk: any;
1044
- encoding: BufferEncoding;
1045
- }>,
1046
- callback: (error?: Error | null) => void,
1047
- ): void;
1048
- final?(this: Duplex, callback: (error?: Error | null) => void): void;
1049
- destroy?(this: Duplex, error: Error | null, callback: (error?: Error | null) => void): void;
1050
1028
  }
1051
1029
  /**
1052
1030
  * Duplex streams are streams that implement both the `Readable` and `Writable` interfaces.
@@ -1058,17 +1036,7 @@ declare module "stream" {
1058
1036
  * * `crypto streams`
1059
1037
  * @since v0.9.4
1060
1038
  */
1061
- class Duplex extends ReadableBase implements WritableBase {
1062
- readonly writable: boolean;
1063
- readonly writableEnded: boolean;
1064
- readonly writableFinished: boolean;
1065
- readonly writableHighWaterMark: number;
1066
- readonly writableLength: number;
1067
- readonly writableObjectMode: boolean;
1068
- readonly writableCorked: number;
1069
- readonly writableNeedDrain: boolean;
1070
- readonly closed: boolean;
1071
- readonly errored: Error | null;
1039
+ class Duplex extends Stream implements NodeJS.ReadWriteStream {
1072
1040
  /**
1073
1041
  * If `false` then the stream will automatically end the writable side when the
1074
1042
  * readable side ends. Set initially by the `allowHalfOpen` constructor option,
@@ -1113,24 +1081,6 @@ declare module "stream" {
1113
1081
  | Promise<any>
1114
1082
  | Object,
1115
1083
  ): Duplex;
1116
- _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
1117
- _writev?(
1118
- chunks: Array<{
1119
- chunk: any;
1120
- encoding: BufferEncoding;
1121
- }>,
1122
- callback: (error?: Error | null) => void,
1123
- ): void;
1124
- _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
1125
- _final(callback: (error?: Error | null) => void): void;
1126
- write(chunk: any, encoding?: BufferEncoding, cb?: (error: Error | null | undefined) => void): boolean;
1127
- write(chunk: any, cb?: (error: Error | null | undefined) => void): boolean;
1128
- setDefaultEncoding(encoding: BufferEncoding): this;
1129
- end(cb?: () => void): this;
1130
- end(chunk: any, cb?: () => void): this;
1131
- end(chunk: any, encoding?: BufferEncoding, cb?: () => void): this;
1132
- cork(): void;
1133
- uncork(): void;
1134
1084
  /**
1135
1085
  * A utility method for creating a web `ReadableStream` and `WritableStream` from a `Duplex`.
1136
1086
  * @since v17.0.0
@@ -1255,6 +1205,7 @@ declare module "stream" {
1255
1205
  removeListener(event: "unpipe", listener: (src: Readable) => void): this;
1256
1206
  removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
1257
1207
  }
1208
+ interface Duplex extends Readable, Writable {}
1258
1209
  /**
1259
1210
  * The utility function `duplexPair` returns an Array with two items,
1260
1211
  * each being a `Duplex` stream connected to the other side:
@@ -1275,27 +1226,9 @@ declare module "stream" {
1275
1226
  */
1276
1227
  function duplexPair(options?: DuplexOptions): [Duplex, Duplex];
1277
1228
  type TransformCallback = (error?: Error | null, data?: any) => void;
1278
- interface TransformOptions extends DuplexOptions {
1279
- construct?(this: Transform, callback: (error?: Error | null) => void): void;
1280
- read?(this: Transform, size: number): void;
1281
- write?(
1282
- this: Transform,
1283
- chunk: any,
1284
- encoding: BufferEncoding,
1285
- callback: (error?: Error | null) => void,
1286
- ): void;
1287
- writev?(
1288
- this: Transform,
1289
- chunks: Array<{
1290
- chunk: any;
1291
- encoding: BufferEncoding;
1292
- }>,
1293
- callback: (error?: Error | null) => void,
1294
- ): void;
1295
- final?(this: Transform, callback: (error?: Error | null) => void): void;
1296
- destroy?(this: Transform, error: Error | null, callback: (error?: Error | null) => void): void;
1297
- transform?(this: Transform, chunk: any, encoding: BufferEncoding, callback: TransformCallback): void;
1298
- flush?(this: Transform, callback: TransformCallback): void;
1229
+ interface TransformOptions<T extends Transform = Transform> extends DuplexOptions<T> {
1230
+ transform?(this: T, chunk: any, encoding: BufferEncoding, callback: TransformCallback): void;
1231
+ flush?(this: T, callback: TransformCallback): void;
1299
1232
  }
1300
1233
  /**
1301
1234
  * Transform streams are `Duplex` streams where the output is in some way
@@ -1720,10 +1653,8 @@ declare module "stream" {
1720
1653
  * @experimental
1721
1654
  */
1722
1655
  function isReadable(stream: Readable | NodeJS.ReadableStream): boolean;
1723
- const promises: typeof streamPromises;
1724
- const consumers: typeof streamConsumers;
1725
1656
  }
1726
- export = internal;
1657
+ export = Stream;
1727
1658
  }
1728
1659
  declare module "node:stream" {
1729
1660
  import stream = require("stream");