diff options
author | Rich Trott <rtrott@gmail.com> | 2021-10-11 07:55:04 +0300 |
---|---|---|
committer | Antoine du Hamel <duhamelantoine1995@gmail.com> | 2021-10-20 12:59:11 +0300 |
commit | d0b58c0287e67a139137aa906819d95f8314b093 (patch) | |
tree | e9a92870138d89b608b1c6e6568611744c32c4f2 /doc/api/stream.md | |
parent | a7c17e08de658cbc0beefd8e9583803b5a62ac7e (diff) |
doc: format doc/api/*.md with markdown formatter
PR-URL: https://github.com/nodejs/node/pull/40403
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Diffstat (limited to 'doc/api/stream.md')
-rw-r--r-- | doc/api/stream.md | 168 |
1 files changed, 130 insertions, 38 deletions
diff --git a/doc/api/stream.md b/doc/api/stream.md index ca183d14314..91fe70555d0 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -49,6 +49,7 @@ Additionally, this module includes the utility functions and [`stream.addAbortSignal()`][]. ### Streams Promises API + <!-- YAML added: v15.0.0 --> @@ -110,12 +111,12 @@ enforce a strict memory limitation in general. Specific stream implementations may choose to enforce stricter limits but doing so is optional. Because [`Duplex`][] and [`Transform`][] streams are both `Readable` and -`Writable`, each maintains *two* separate internal buffers used for reading and +`Writable`, each maintains _two_ separate internal buffers used for reading and writing, allowing each side to operate independently of the other while maintaining an appropriate and efficient flow of data. For example, [`net.Socket`][] instances are [`Duplex`][] streams whose `Readable` side allows -consumption of data received *from* the socket and whose `Writable` side allows -writing data *to* the socket. Because data may be written to the socket at a +consumption of data received _from_ the socket and whose `Writable` side allows +writing data _to_ the socket. Because data may be written to the socket at a faster or slower rate than data is received, each side should operate (and buffer) independently of the other. @@ -196,7 +197,7 @@ section [API for stream implementers][]. ### Writable streams -Writable streams are an abstraction for a *destination* to which data is +Writable streams are an abstraction for a _destination_ to which data is written. Examples of [`Writable`][] streams include: @@ -228,6 +229,7 @@ myStream.end('done writing data'); ``` #### Class: `stream.Writable` + <!-- YAML added: v0.9.4 --> @@ -235,6 +237,7 @@ added: v0.9.4 <!--type=class--> ##### Event: `'close'` + <!-- YAML added: v0.9.4 changes: @@ -252,6 +255,7 @@ A [`Writable`][] stream will always emit the `'close'` event if it is created with the `emitClose` option. ##### Event: `'drain'` + <!-- YAML added: v0.9.4 --> @@ -289,6 +293,7 @@ function writeOneMillionTimes(writer, data, encoding, callback) { ``` ##### Event: `'error'` + <!-- YAML added: v0.9.4 --> @@ -302,10 +307,11 @@ The stream is closed when the `'error'` event is emitted unless the [`autoDestroy`][writable-new] option was set to `false` when creating the stream. -After `'error'`, no further events other than `'close'` *should* be emitted +After `'error'`, no further events other than `'close'` _should_ be emitted (including `'error'` events). ##### Event: `'finish'` + <!-- YAML added: v0.9.4 --> @@ -325,6 +331,7 @@ writer.end('This is the end\n'); ``` ##### Event: `'pipe'` + <!-- YAML added: v0.9.4 --> @@ -345,6 +352,7 @@ reader.pipe(writer); ``` ##### Event: `'unpipe'` + <!-- YAML added: v0.9.4 --> @@ -371,6 +379,7 @@ reader.unpipe(writer); ``` ##### `writable.cork()` + <!-- YAML added: v0.11.2 --> @@ -391,6 +400,7 @@ to be processed. However, use of `writable.cork()` without implementing See also: [`writable.uncork()`][], [`writable._writev()`][stream-_writev]. ##### `writable.destroy([error])` + <!-- YAML added: v8.0.0 changes: @@ -447,6 +457,7 @@ Implementors should not override this method, but instead implement [`writable._destroy()`][writable-_destroy]. ##### `writable.destroyed` + <!-- YAML added: v8.0.0 --> @@ -466,6 +477,7 @@ console.log(myStream.destroyed); // true ``` ##### `writable.end([chunk[, encoding]][, callback])` + <!-- YAML added: v0.9.4 changes: @@ -509,6 +521,7 @@ file.end('world!'); ``` ##### `writable.setDefaultEncoding(encoding)` + <!-- YAML added: v0.11.15 changes: @@ -524,6 +537,7 @@ The `writable.setDefaultEncoding()` method sets the default `encoding` for a [`Writable`][] stream. ##### `writable.uncork()` + <!-- YAML added: v0.11.2 --> @@ -562,6 +576,7 @@ process.nextTick(() => { See also: [`writable.cork()`][]. ##### `writable.writable` + <!-- YAML added: v11.4.0 --> @@ -572,6 +587,7 @@ Is `true` if it is safe to call [`writable.write()`][stream-write], which means the stream has not been destroyed, errored or ended. ##### `writable.writableEnded` + <!-- YAML added: v12.9.0 --> @@ -583,6 +599,7 @@ does not indicate whether the data has been flushed, for this use [`writable.writableFinished`][] instead. ##### `writable.writableCorked` + <!-- YAML added: - v13.2.0 @@ -595,6 +612,7 @@ Number of times [`writable.uncork()`][stream-uncork] needs to be called in order to fully uncork the stream. ##### `writable.writableFinished` + <!-- YAML added: v12.6.0 --> @@ -604,6 +622,7 @@ added: v12.6.0 Is set to `true` immediately before the [`'finish'`][] event is emitted. ##### `writable.writableHighWaterMark` + <!-- YAML added: v9.3.0 --> @@ -613,6 +632,7 @@ added: v9.3.0 Return the value of `highWaterMark` passed when creating this `Writable`. ##### `writable.writableLength` + <!-- YAML added: v9.4.0 --> @@ -624,6 +644,7 @@ ready to be written. The value provides introspection data regarding the status of the `highWaterMark`. ##### `writable.writableNeedDrain` + <!-- YAML added: - v15.2.0 @@ -635,6 +656,7 @@ added: Is `true` if the stream's buffer has been full and stream will emit `'drain'`. ##### `writable.writableObjectMode` + <!-- YAML added: v12.3.0 --> @@ -644,6 +666,7 @@ added: v12.3.0 Getter for the property `objectMode` of a given `Writable` stream. ##### `writable.write(chunk[, encoding][, callback])` + <!-- YAML added: v0.9.4 changes: @@ -720,7 +743,7 @@ A `Writable` stream in object mode will always ignore the `encoding` argument. ### Readable streams -Readable streams are an abstraction for a *source* from which data is +Readable streams are an abstraction for a _source_ from which data is consumed. Examples of `Readable` streams include: @@ -768,13 +791,13 @@ The `Readable` can switch back to paused mode using one of the following: The important concept to remember is that a `Readable` will not generate data until a mechanism for either consuming or ignoring that data is provided. If -the consuming mechanism is disabled or taken away, the `Readable` will *attempt* +the consuming mechanism is disabled or taken away, the `Readable` will _attempt_ to stop generating the data. For backward compatibility reasons, removing [`'data'`][] event handlers will **not** automatically pause the stream. Also, if there are piped destinations, then calling [`stream.pause()`][stream-pause] will not guarantee that the -stream will *remain* paused once those destinations drain and ask for more data. +stream will _remain_ paused once those destinations drain and ask for more data. If a [`Readable`][] is switched into flowing mode and there are no consumers available to handle the data, that data will be lost. This can occur, for @@ -810,7 +833,7 @@ emitting events as data is generated. Calling `readable.pause()`, `readable.unpipe()`, or receiving backpressure will cause the `readable.readableFlowing` to be set as `false`, -temporarily halting the flowing of events but *not* halting the generation of +temporarily halting the flowing of events but _not_ halting the generation of data. While in this state, attaching a listener for the `'data'` event will not switch `readable.readableFlowing` to `true`. @@ -835,7 +858,7 @@ within the stream's internal buffer. The `Readable` stream API evolved across multiple Node.js versions and provides multiple methods of consuming stream data. In general, developers should choose -*one* of the methods of consuming data and *should never* use multiple methods +_one_ of the methods of consuming data and _should never_ use multiple methods to consume data from a single stream. Specifically, using a combination of `on('data')`, `on('readable')`, `pipe()`, or async iterators could lead to unintuitive behavior. @@ -847,6 +870,7 @@ use the [`EventEmitter`][] and `readable.on('readable')`/`readable.read()` or the `readable.pause()`/`readable.resume()` APIs. #### Class: `stream.Readable` + <!-- YAML added: v0.9.4 --> @@ -854,6 +878,7 @@ added: v0.9.4 <!--type=class--> ##### Event: `'close'` + <!-- YAML added: v0.9.4 changes: @@ -871,6 +896,7 @@ A [`Readable`][] stream will always emit the `'close'` event if it is created with the `emitClose` option. ##### Event: `'data'` + <!-- YAML added: v0.9.4 --> @@ -904,6 +930,7 @@ readable.on('data', (chunk) => { ``` ##### Event: `'end'` + <!-- YAML added: v0.9.4 --> @@ -927,6 +954,7 @@ readable.on('end', () => { ``` ##### Event: `'error'` + <!-- YAML added: v0.9.4 --> @@ -941,6 +969,7 @@ to push an invalid chunk of data. The listener callback will be passed a single `Error` object. ##### Event: `'pause'` + <!-- YAML added: v0.9.4 --> @@ -949,6 +978,7 @@ The `'pause'` event is emitted when [`stream.pause()`][stream-pause] is called and `readableFlowing` is not `false`. ##### Event: `'readable'` + <!-- YAML added: v0.9.4 changes: @@ -1018,6 +1048,7 @@ will start flowing, i.e. `'data'` events will be emitted without calling `.resume()`. ##### Event: `'resume'` + <!-- YAML added: v0.9.4 --> @@ -1026,6 +1057,7 @@ The `'resume'` event is emitted when [`stream.resume()`][stream-resume] is called and `readableFlowing` is not `true`. ##### `readable.destroy([error])` + <!-- YAML added: v8.0.0 changes: @@ -1049,6 +1081,7 @@ Implementors should not override this method, but instead implement [`readable._destroy()`][readable-_destroy]. ##### `readable.destroyed` + <!-- YAML added: v8.0.0 --> @@ -1058,6 +1091,7 @@ added: v8.0.0 Is `true` after [`readable.destroy()`][readable-destroy] has been called. ##### `readable.isPaused()` + <!-- YAML added: v0.11.14 --> @@ -1080,6 +1114,7 @@ readable.isPaused(); // === false ``` ##### `readable.pause()` + <!-- YAML added: v0.9.4 --> @@ -1107,6 +1142,7 @@ The `readable.pause()` method has no effect if there is a `'readable'` event listener. ##### `readable.pipe(destination[, options])` + <!-- YAML added: v0.9.4 --> @@ -1114,7 +1150,7 @@ added: v0.9.4 * `destination` {stream.Writable} The destination for writing data * `options` {Object} Pipe options * `end` {boolean} End the writer when the reader ends. **Default:** `true`. -* Returns: {stream.Writable} The *destination*, allowing for a chain of pipes if +* Returns: {stream.Writable} The _destination_, allowing for a chain of pipes if it is a [`Duplex`][] or a [`Transform`][] stream The `readable.pipe()` method attaches a [`Writable`][] stream to the `readable`, @@ -1137,7 +1173,7 @@ readable.pipe(writable); It is possible to attach multiple `Writable` streams to a single `Readable` stream. -The `readable.pipe()` method returns a reference to the *destination* stream +The `readable.pipe()` method returns a reference to the _destination_ stream making it possible to set up chains of piped streams: ```js @@ -1161,14 +1197,15 @@ reader.on('end', () => { ``` One important caveat is that if the `Readable` stream emits an error during -processing, the `Writable` destination *is not closed* automatically. If an -error occurs, it will be necessary to *manually* close each stream in order +processing, the `Writable` destination _is not closed_ automatically. If an +error occurs, it will be necessary to _manually_ close each stream in order to prevent memory leaks. The [`process.stderr`][] and [`process.stdout`][] `Writable` streams are never closed until the Node.js process exits, regardless of the specified options. ##### `readable.read([size])` + <!-- YAML added: v0.9.4 --> @@ -1183,7 +1220,7 @@ specified using the `readable.setEncoding()` method or the stream is operating in object mode. The optional `size` argument specifies a specific number of bytes to read. If -`size` bytes are not available to be read, `null` will be returned *unless* +`size` bytes are not available to be read, `null` will be returned _unless_ the stream has ended, in which case all of the data remaining in the internal buffer will be returned. @@ -1252,6 +1289,7 @@ Calling [`stream.read([size])`][stream-read] after the [`'end'`][] event has been emitted will return `null`. No runtime error will be raised. ##### `readable.readable` + <!-- YAML added: v11.4.0 --> @@ -1262,6 +1300,7 @@ Is `true` if it is safe to call [`readable.read()`][stream-read], which means the stream has not been destroyed or emitted `'error'` or `'end'`. ##### `readable.readableAborted` + <!-- YAML added: v16.8.0 --> @@ -1273,6 +1312,7 @@ added: v16.8.0 Returns whether the stream was destroyed or errored before emitting `'end'`. ##### `readable.readableDidRead` + <!-- YAML added: - v16.7.0 @@ -1286,6 +1326,7 @@ added: Returns whether `'data'` has been emitted. ##### `readable.readableEncoding` + <!-- YAML added: v12.7.0 --> @@ -1296,6 +1337,7 @@ Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the [`readable.setEncoding()`][] method. ##### `readable.readableEnded` + <!-- YAML added: v12.9.0 --> @@ -1305,6 +1347,7 @@ added: v12.9.0 Becomes `true` when [`'end'`][] event is emitted. ##### `readable.readableFlowing` + <!-- YAML added: v9.4.0 --> @@ -1315,6 +1358,7 @@ This property reflects the current state of a `Readable` stream as described in the [Three states][] section. ##### `readable.readableHighWaterMark` + <!-- YAML added: v9.3.0 --> @@ -1324,6 +1368,7 @@ added: v9.3.0 Returns the value of `highWaterMark` passed when creating this `Readable`. ##### `readable.readableLength` + <!-- YAML added: v9.4.0 --> @@ -1335,6 +1380,7 @@ ready to be read. The value provides introspection data regarding the status of the `highWaterMark`. ##### `readable.readableObjectMode` + <!-- YAML added: v12.3.0 --> @@ -1344,6 +1390,7 @@ added: v12.3.0 Getter for the property `objectMode` of a given `Readable` stream. ##### `readable.resume()` + <!-- YAML added: v0.9.4 changes: @@ -1373,6 +1420,7 @@ The `readable.resume()` method has no effect if there is a `'readable'` event listener. ##### `readable.setEncoding(encoding)` + <!-- YAML added: v0.9.4 --> @@ -1405,6 +1453,7 @@ readable.on('data', (chunk) => { ``` ##### `readable.unpipe([destination])` + <!-- YAML added: v0.9.4 --> @@ -1415,7 +1464,7 @@ added: v0.9.4 The `readable.unpipe()` method detaches a `Writable` stream previously attached using the [`stream.pipe()`][] method. -If the `destination` is not specified, then *all* pipes are detached. +If the `destination` is not specified, then _all_ pipes are detached. If the `destination` is specified, but no pipe is set up for it, then the method does nothing. @@ -1436,6 +1485,7 @@ setTimeout(() => { ``` ##### `readable.unshift(chunk[, encoding])` + <!-- YAML added: v0.9.11 changes: @@ -1514,6 +1564,7 @@ however it is best to simply avoid calling `readable.unshift()` while in the process of performing a read. ##### `readable.wrap(stream)` + <!-- YAML added: v0.9.4 --> @@ -1545,6 +1596,7 @@ myReader.on('readable', () => { ``` ##### `readable[Symbol.asyncIterator]()` + <!-- YAML added: v10.0.0 changes: @@ -1578,6 +1630,7 @@ has less then 64 KB of data because no `highWaterMark` option is provided to [`fs.createReadStream()`][]. ##### `readable.iterator([options])` + <!-- YAML added: v16.3.0 --> @@ -1633,6 +1686,7 @@ showBoth(); ### Duplex and transform streams #### Class: `stream.Duplex` + <!-- YAML added: v0.9.4 changes: @@ -1654,6 +1708,7 @@ Examples of `Duplex` streams include: * [crypto streams][crypto] ##### `duplex.allowHalfOpen` + <!-- YAML added: v0.9.4 --> @@ -1669,6 +1724,7 @@ This can be changed manually to change the half-open behavior of an existing emitted. #### Class: `stream.Transform` + <!-- YAML added: v0.9.4 --> @@ -1685,6 +1741,7 @@ Examples of `Transform` streams include: * [crypto streams][crypto] ##### `transform.destroy([error])` + <!-- YAML added: v8.0.0 changes: @@ -1707,6 +1764,7 @@ Once `destroy()` has been called, any further calls will be a no-op and no further errors except from `_destroy()` may be emitted as `'error'`. ### `stream.finished(stream[, options], callback)` + <!-- YAML added: v10.0.0 changes: @@ -1740,7 +1798,7 @@ changes: the stream ends even though the stream might still be writable. **Default:** `true`. * `signal` {AbortSignal} allows aborting the wait for the stream finish. The - underlying stream will *not* be aborted if the signal is aborted. The + underlying stream will _not_ be aborted if the signal is aborted. The callback will get called with an `AbortError`. All registered listeners added by this function will also be removed. * `callback` {Function} A callback function that takes an optional error @@ -1802,7 +1860,9 @@ const cleanup = finished(rs, (err) => { ``` ### `stream.pipeline(source[, ...transforms], destination, callback)` + ### `stream.pipeline(streams, callback)` + <!-- YAML added: v10.0.0 changes: @@ -1817,7 +1877,7 @@ changes: description: Add support for async generators. --> -* `streams` {Stream[]|Iterable[]|AsyncIterable[]|Function[]} +* `streams` {Stream\[]|Iterable\[]|AsyncIterable\[]|Function\[]} * `source` {Stream|Iterable|AsyncIterable|Function} * Returns: {Iterable|AsyncIterable} * `...transforms` {Stream|Function} @@ -1947,6 +2007,7 @@ run().catch(console.error); ``` `stream.pipeline()` will call `stream.destroy(err)` on all streams except: + * `Readable` streams which have emitted `'end'` or `'close'`. * `Writable` streams which have emitted `'finish'` or `'close'`. @@ -1955,13 +2016,14 @@ after the `callback` has been invoked. In the case of reuse of streams after failure, this can cause event listener leaks and swallowed errors. ### `stream.compose(...streams)` + <!-- YAML added: v16.9.0 --> > Stability: 1 - `stream.compose` is experimental. -* `streams` {Stream[]|Iterable[]|AsyncIterable[]|Function[]} +* `streams` {Stream\[]|Iterable\[]|AsyncIterable\[]|Function\[]} * Returns: {stream.Duplex} Combines two or more streams into a `Duplex` stream that writes to the @@ -2044,6 +2106,7 @@ console.log(res); // prints 'HELLOWORLD' ``` ### `stream.Readable.from(iterable[, options])` + <!-- YAML added: - v12.3.0 @@ -2052,7 +2115,7 @@ added: * `iterable` {Iterable} Object implementing the `Symbol.asyncIterator` or `Symbol.iterator` iterable protocol. Emits an 'error' event if a null - value is passed. + value is passed. * `options` {Object} 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`. @@ -2080,6 +2143,7 @@ the strings or buffers be iterated to match the other streams semantics for performance reasons. ### `stream.Readable.fromWeb(readableStream[, options])` + <!-- YAML added: v16.11.0 --> @@ -2095,6 +2159,7 @@ added: v16.11.0 * Returns: {stream.Readable} ### `stream.Readable.isDisturbed(stream)` + <!-- YAML added: v16.8.0 --> @@ -2107,6 +2172,7 @@ added: v16.8.0 Returns whether the stream has been read from or cancelled. ### `stream.Readable.toWeb(streamReadable)` + <!-- YAML added: v17.0.0 --> @@ -2117,6 +2183,7 @@ added: v17.0.0 * Returns: {ReadableStream} ### `stream.Writable.fromWeb(writableStream[, options])` + <!-- YAML added: v17.0.0 --> @@ -2132,6 +2199,7 @@ added: v17.0.0 * Returns: {stream.Writable} ### `stream.Writable.toWeb(streamWritable)` + <!-- YAML added: v17.0.0 --> @@ -2142,6 +2210,7 @@ added: v17.0.0 * Returns: {WritableStream} ### `stream.Duplex.from(src)` + <!-- YAML added: v16.8.0 --> @@ -2170,6 +2239,7 @@ A utility method for creating duplex streams. * Returns: {stream.Duplex} ### `stream.Duplex.fromWeb(pair[, options])` + <!-- YAML added: v17.0.0 --> @@ -2189,6 +2259,7 @@ added: v17.0.0 * Returns: {stream.Duplex} ### `stream.Duplex.toWeb(streamDuplex)` + <!-- YAML added: v17.0.0 --> @@ -2201,9 +2272,11 @@ added: v17.0.0 * `writable` {WritableStream} ### `stream.addAbortSignal(signal, stream)` + <!-- YAML added: v15.4.0 --> + * `signal` {AbortSignal} A signal representing possible cancellation * `stream` {Stream} a stream to attach a signal to @@ -2249,6 +2322,7 @@ const stream = addAbortSignal( } })(); ``` + ## API for stream implementers <!--type=misc--> @@ -2262,6 +2336,7 @@ of the four basic stream classes (`stream.Writable`, `stream.Readable`, parent class constructor: <!-- eslint-disable no-useless-constructor --> + ```js const { Writable } = require('stream'); @@ -2283,14 +2358,14 @@ options are forwarded instead of implicitly forwarding all options. The new stream class must then implement one or more specific methods, depending on the type of stream being created, as detailed in the chart below: -| Use-case | Class | Method(s) to implement | -| -------- | ----- | ---------------------- | -| Reading only | [`Readable`][] | [`_read()`][stream-_read] | -| Writing only | [`Writable`][] | [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | -| Reading and writing | [`Duplex`][] | [`_read()`][stream-_read], [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | -| Operate on written data, then read the result | [`Transform`][] | [`_transform()`][stream-_transform], [`_flush()`][stream-_flush], [`_final()`][stream-_final] | +| Use-case | Class | Method(s) to implement | +| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | +| Reading only | [`Readable`][] | [`_read()`][stream-_read] | +| Writing only | [`Writable`][] | [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | +| Reading and writing | [`Duplex`][] | [`_read()`][stream-_read], [`_write()`][stream-_write], [`_writev()`][stream-_writev], [`_final()`][stream-_final] | +| Operate on written data, then read the result | [`Transform`][] | [`_transform()`][stream-_transform], [`_flush()`][stream-_flush], [`_final()`][stream-_final] | -The implementation code for a stream should *never* call the "public" methods +The implementation code for a stream should _never_ call the "public" methods of a stream that are intended for use by consumers (as described in the [API for stream consumers][] section). Doing so may lead to adverse side effects in application code consuming the stream. @@ -2303,6 +2378,7 @@ and/or compatibility issues with other streams, stream utilities, and user expectations. ### Simplified construction + <!-- YAML added: v1.2.0 --> @@ -2332,11 +2408,12 @@ const myWritable = new Writable({ The `stream.Writable` class is extended to implement a [`Writable`][] stream. -Custom `Writable` streams *must* call the `new stream.Writable([options])` +Custom `Writable` streams _must_ call the `new stream.Writable([options])` constructor and implement the `writable._write()` and/or `writable._writev()` method. #### `new stream.Writable([options])` + <!-- YAML changes: - version: v15.5.0 @@ -2392,6 +2469,7 @@ changes: * `signal` {AbortSignal} A signal representing possible cancellation. <!-- eslint-disable no-useless-constructor --> + ```js const { Writable } = require('stream'); @@ -2453,7 +2531,9 @@ const myWritable = new Writable({ // Later, abort the operation closing the stream controller.abort(); ``` + #### `writable._construct(callback)` + <!-- YAML added: v15.0.0 --> @@ -2503,6 +2583,7 @@ class WriteStream extends Writable { ``` #### `writable._write(chunk, encoding, callback)` + <!-- YAML changes: - version: v12.11.0 @@ -2558,7 +2639,7 @@ user programs. #### `writable._writev(chunks, callback)` -* `chunks` {Object[]} The data to be written. The value is an array of {Object} +* `chunks` {Object\[]} The data to be written. The value is an array of {Object} that each represent a discrete chunk of data to write. The properties of these objects are: * `chunk` {Buffer|string} A buffer instance or string containing the data to @@ -2583,6 +2664,7 @@ internal to the class that defines it, and should never be called directly by user programs. #### `writable._destroy(err, callback)` + <!-- YAML added: v8.0.0 --> @@ -2595,6 +2677,7 @@ The `_destroy()` method is called by [`writable.destroy()`][writable-destroy]. It can be overridden by child classes but it **must not** be called directly. #### `writable._final(callback)` + <!-- YAML added: v8.0.0 --> @@ -2700,10 +2783,11 @@ console.log(w.data); // currency: € The `stream.Readable` class is extended to implement a [`Readable`][] stream. -Custom `Readable` streams *must* call the `new stream.Readable([options])` +Custom `Readable` streams _must_ call the `new stream.Readable([options])` constructor and implement the [`readable._read()`][] method. #### `new stream.Readable([options])` + <!-- YAML changes: - version: v15.5.0 @@ -2742,6 +2826,7 @@ changes: * `signal` {AbortSignal} A signal representing possible cancellation. <!-- eslint-disable no-useless-constructor --> + ```js const { Readable } = require('stream'); @@ -2798,6 +2883,7 @@ controller.abort(); ``` #### `readable._construct(callback)` + <!-- YAML added: v15.0.0 --> @@ -2855,6 +2941,7 @@ class ReadStream extends Readable { ``` #### `readable._read(size)` + <!-- YAML added: v0.9.4 --> @@ -2893,6 +2980,7 @@ internal to the class that defines it, and should never be called directly by user programs. #### `readable._destroy(err, callback)` + <!-- YAML added: v8.0.0 --> @@ -2905,6 +2993,7 @@ The `_destroy()` method is called by [`readable.destroy()`][readable-destroy]. It can be overridden by child classes but it **must not** be called directly. #### `readable.push(chunk[, encoding])` + <!-- YAML changes: - version: v8.0.0 @@ -3036,18 +3125,19 @@ A [`Duplex`][] stream is one that implements both [`Readable`][] and Because JavaScript does not have support for multiple inheritance, the `stream.Duplex` class is extended to implement a [`Duplex`][] stream (as opposed -to extending the `stream.Readable` *and* `stream.Writable` classes). +to extending the `stream.Readable` _and_ `stream.Writable` classes). The `stream.Duplex` class prototypically inherits from `stream.Readable` and parasitically from `stream.Writable`, but `instanceof` will work properly for both base classes due to overriding [`Symbol.hasInstance`][] on `stream.Writable`. -Custom `Duplex` streams *must* call the `new stream.Duplex([options])` -constructor and implement *both* the [`readable._read()`][] and +Custom `Duplex` streams _must_ call the `new stream.Duplex([options])` +constructor and implement _both_ the [`readable._read()`][] and `writable._write()` methods. #### `new stream.Duplex(options)` + <!-- YAML changes: - version: v8.4.0 @@ -3075,6 +3165,7 @@ changes: of the stream. Has no effect if `highWaterMark` is provided. <!-- eslint-disable no-useless-constructor --> + ```js const { Duplex } = require('stream'); @@ -3252,8 +3343,8 @@ The `stream.Transform` class is extended to implement a [`Transform`][] stream. The `stream.Transform` class prototypically inherits from `stream.Duplex` and implements its own versions of the `writable._write()` and -[`readable._read()`][] methods. Custom `Transform` implementations *must* -implement the [`transform._transform()`][stream-_transform] method and *may* +[`readable._read()`][] methods. Custom `Transform` implementations _must_ +implement the [`transform._transform()`][stream-_transform] method and _may_ also implement the [`transform._flush()`][stream-_flush] method. Care must be taken when using `Transform` streams in that data written to the @@ -3270,6 +3361,7 @@ output on the `Readable` side is not consumed. method. <!-- eslint-disable no-useless-constructor --> + ```js const { Transform } = require('stream'); @@ -3336,7 +3428,7 @@ store an amount of internal state used to optimally compress the output. When the stream ends, however, that additional data needs to be flushed so that the compressed data will be complete. -Custom [`Transform`][] implementations *may* implement the `transform._flush()` +Custom [`Transform`][] implementations _may_ implement the `transform._flush()` method. This will be called when there is no more written data to be consumed, but before the [`'end'`][] event is emitted signaling the end of the [`Readable`][] stream. @@ -3519,7 +3611,7 @@ less powerful and less useful. were required to store read data into buffers so the data would not be lost. * The [`stream.pause()`][stream-pause] method was advisory, rather than guaranteed. This meant that it was still necessary to be prepared to receive - [`'data'`][] events *even when the stream was in a paused state*. + [`'data'`][] events _even when the stream was in a paused state_. In Node.js 0.10, the [`Readable`][] class was added. For backward compatibility with older Node.js programs, `Readable` streams switch into @@ -3593,7 +3685,7 @@ situations within Node.js where this is done, particularly in the Use of `readable.push('')` is not recommended. Pushing a zero-byte string, `Buffer` or `Uint8Array` to a stream that is not in -object mode has an interesting side effect. Because it *is* a call to +object mode has an interesting side effect. Because it _is_ a call to [`readable.push()`][stream-push], the call will end the reading process. However, because the argument is an empty string, no data is added to the readable buffer so there is nothing for a user to consume. |