From 9847f8459c863921af48337b7a4fea28c666a23f Mon Sep 17 00:00:00 2001 From: "Italo A. Casas" Date: Mon, 13 Jun 2016 10:32:44 -0400 Subject: [PATCH] doc: add `added:` information for stream Ref: https://github.com/nodejs/node/issues/6578 PR-URL: https://github.com/nodejs/node/pull/7287 Reviewed-By: Anna Henningsen Reviewed-By: Claudio Rodriguez --- doc/api/stream.md | 93 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/doc/api/stream.md b/doc/api/stream.md index ad014a2a69..2afdbf51fa 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -116,7 +116,7 @@ const server = http.createServer( (req, res) => { // req is an http.IncomingMessage, which is a Readable Stream // res is an http.ServerResponse, which is a Writable Stream - var body = ''; + let body = ''; // Get the data as utf8 strings. // If an encoding is not set, Buffer objects will be received. req.setEncoding('utf8'); @@ -205,10 +205,16 @@ myStream.end('done writing data'); ``` #### Class: stream.Writable + ##### Event: 'close' + The `'close'` event is emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed. The event indicates @@ -217,6 +223,9 @@ that no more events will be emitted, and no further computation will occur. Not all Writable streams will emit the `'close'` event. ##### Event: 'drain' + If a call to [`stream.write(chunk)`][stream-write] returns `false`, the `'drain'` event will be emitted when it is appropriate to resume writing data @@ -226,7 +235,7 @@ to the stream. // Write the data to the supplied writable stream one million times. // Be attentive to back-pressure. function writeOneMillionTimes(writer, data, encoding, callback) { - var i = 1000000; + let i = 1000000; write(); function write() { var ok = true; @@ -251,6 +260,9 @@ function writeOneMillionTimes(writer, data, encoding, callback) { ``` ##### Event: 'error' + * {Error} @@ -260,6 +272,9 @@ data. The listener callback is passed a single `Error` argument when called. *Note*: The stream is not closed when the `'error'` event is emitted. ##### Event: 'finish' + The `'finish'` event is emitted after the [`stream.end()`][stream-end] method has been called, and all data has been flushed to the underlying system. @@ -276,6 +291,9 @@ writer.on('finish', () => { ``` ##### Event: 'pipe' + * `src` {stream.Readable} source stream that is piping to this writable @@ -293,6 +311,9 @@ reader.pipe(writer); ``` ##### Event: 'unpipe' + * `src` {[Readable][] Stream} The source stream that [unpiped][`stream.unpipe()`] this writable @@ -313,6 +334,9 @@ reader.unpipe(writer); ``` ##### writable.cork() + The `writable.cork()` method forces all written data to be buffered in memory. The buffered data will be flushed when either the [`stream.uncork()`][] or @@ -325,6 +349,9 @@ implementations that implement the `writable._writev()` method can perform buffered writes in a more optimized manner. ##### writable.end([chunk][, encoding][, callback]) + * `chunk` {String|Buffer|any} Optional data to write. For streams not operating in object mode, `chunk` must be a string or a `Buffer`. For object mode @@ -350,6 +377,9 @@ file.end('world!'); ``` ##### writable.setDefaultEncoding(encoding) + * `encoding` {String} The new default encoding * Return: `this` @@ -358,6 +388,9 @@ The `writable.setDefaultEncoding()` method sets the default `encoding` for a [Writable][] stream. ##### writable.uncork() + The `writable.uncork()` method flushes all data buffered since [`stream.cork()`][] was called. @@ -391,6 +424,9 @@ process.nextTick(() => { ``` ##### writable.write(chunk[, encoding][, callback]) + * `chunk` {String|Buffer} The data to write * `encoding` {String} The encoding, if `chunk` is a String @@ -516,10 +552,16 @@ require more fine-grained control over the transfer and generation of data can use the [`EventEmitter`][] and `readable.pause()`/`readable.resume()` APIs. #### Class: stream.Readable + ##### Event: 'close' + The `'close'` event is emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed. The event indicates @@ -528,6 +570,9 @@ that no more events will be emitted, and no further computation will occur. Not all [Readable][] streams will emit the `'close'` event. ##### Event: 'data' + * `chunk` {Buffer|String|any} The chunk of data. For streams that are not operating in object mode, the chunk will be either a string or `Buffer`. @@ -558,6 +603,9 @@ readable.on('data', (chunk) => { ``` ##### Event: 'end' + The `'end'` event is emitted when there is no more data to be consumed from the stream. @@ -578,6 +626,9 @@ readable.on('end', () => { ``` ##### Event: 'error' + * {Error} @@ -589,6 +640,9 @@ to push an invalid chunk of data. The listener callback will be passed a single `Error` object. ##### Event: 'readable' + The `'readable'` event is emitted when there is data available to be read from the stream. In some cases, attaching a listener for the `'readable'` event will @@ -632,6 +686,9 @@ end preferred over the use of the `'readable'` event. ##### readable.isPaused() + * Return: {Boolean} @@ -651,6 +708,9 @@ readable.isPaused() // === false ``` ##### readable.pause() + * Return: `this` @@ -672,6 +732,9 @@ readable.on('data', (chunk) => { ``` ##### readable.pipe(destination[, options]) + * `destination` {stream.Writable} The destination for writing data * `options` {Object} Pipe options @@ -727,6 +790,9 @@ never closed until the Node.js process exits, regardless of the specified options. ##### readable.read([size]) + * `size` {Number} Optional argument to specify how much data to read. * Return {String|Buffer|Null} @@ -774,6 +840,9 @@ event will also be emitted. event has been emitted will return `null`. No runtime error will be raised. ##### readable.resume() + * Return: `this` @@ -793,6 +862,9 @@ getReadableStreamSomehow() ``` ##### readable.setEncoding(encoding) + * `encoding` {String} The encoding to use. * Return: `this` @@ -825,6 +897,9 @@ readable.on('data', (chunk) => { ``` ##### readable.unpipe([destination]) + * `destination` {stream.Writable} Optional specific stream to unpipe @@ -851,6 +926,9 @@ setTimeout(() => { ``` ##### readable.unshift(chunk) + * `chunk` {Buffer|String} Chunk of data to unshift onto the read queue @@ -911,6 +989,9 @@ appropriately, however it is best to simply avoid calling `readable.unshift()` while in the process of performing a read. ##### readable.wrap(stream) + * `stream` {Stream} An "old style" readable stream @@ -943,6 +1024,9 @@ myReader.on('readable', () => { ### Duplex and Transform Streams #### Class: stream.Duplex + @@ -956,6 +1040,9 @@ Examples of Duplex streams include: * [crypto streams][crypto] #### Class: stream.Transform + @@ -1579,7 +1666,7 @@ For Duplex streams, `objectMode` can be set exclusively for either the Readable or Writable side using the `readableObjectMode` and `writableObjectMode` options respectively. -In the following example, for instance, a new Transform stream (which is a +In the following example, for instance, a new Transform stream (which is a type of [Duplex][] stream) is created that has an object mode Writable side that accepts JavaScript numbers that are converted to hexidecimal strings on the Readable side.