RubyGems - tck-lambdas - Versions diffs - 0.3.0 → 0.3.1 - Mend

tck-lambdas 0.3.0 → 0.3.1

Files changed (690) hide show

data/lib/tck/lambdas/chistacojs/node_modules/cheerio/node_modules/htmlparser2/node_modules/readable-stream/doc/stream.md DELETED Viewed

@@ -1,2015 +0,0 @@
-# Stream
-    Stability: 2 - Stable
-A stream is an abstract interface for working with streaming data in Node.js.
-The `stream` module provides a base API that makes it easy to build objects
-that implement the stream interface.
-There are many stream objects provided by Node.js. For instance, a
-[request to an HTTP server][http-incoming-message] and [`process.stdout`][]
-are both stream instances.
-Streams can be readable, writable, or both. All streams are instances of
-[`EventEmitter`][].
-The `stream` module can be accessed using:
-```js
-const stream = require('stream');
-```
-While it is important for all Node.js users to understand how streams works,
-the `stream` module itself is most useful for developer's that are creating new
-types of stream instances. Developer's who are primarily *consuming* stream
-objects will rarely (if ever) have need to use the `stream` module directly.
-## Organization of this document
-This document is divided into two primary sections and third section for
-additional notes. The first section explains the elements of the stream API that
-are required to *use* streams within an application. The second section explains
-the elements of the API that are required to *implement* new types of streams.
-## Types of Streams
-There are four fundamental stream types within Node.js:
-* [Readable][] - streams from which data can be read (for example
-  [`fs.createReadStream()`][]).
-* [Writable][] - streams to which data can be written (for example
-  [`fs.createWriteStream()`][]).
-* [Duplex][] - streams that are both Readable and Writable (for example
-  [`net.Socket`][]).
-* [Transform][] - Duplex streams that can modify or transform the data as it
-  is written and read (for example [`zlib.createDeflate()`][]).
-### Object Mode
-All streams created by Node.js APIs operate exclusively on strings and `Buffer`
-objects. It is possible, however, for stream implementations to work with other
-types of JavaScript values (with the exception of `null` which serves a special
-purpose within streams). Such streams are considered to operate in "object
-mode".
-Stream instances are switched into object mode using the `objectMode` option
-when the stream is created. Attempting to switch an existing stream into
-object mode is not safe.
-### Buffering
-<!--type=misc-->
-Both [Writable][] and [Readable][] streams will store data in an internal
-buffer that can be retrieved using `writable._writableState.getBuffer()` or
-`readable._readableState.buffer`, respectively.
-The amount of data potentially buffered depends on the `highWaterMark` option
-passed into the streams constructor. For normal streams, the `highWaterMark`
-option specifies a total number of bytes. For streams operating in object mode,
-the `highWaterMark` specifies a total number of objects.
-Data is buffered in Readable streams when the implementation calls
-[`stream.push(chunk)`][stream-push]. If the consumer of the Stream does not
-call [`stream.read()`][stream-read], the data will sit in the internal
-queue until it is consumed.
-Once the total size of the internal read buffer reaches the threshold specified
-by `highWaterMark`, the stream will temporarily stop reading data from the
-underlying resource until the data currently buffered can be consumed (that is,
-the stream will stop calling the internal `readable._read()` method that is
-used to fill the read buffer).
-Data is buffered in Writable streams when the
-[`writable.write(chunk)`][stream-write] method is called repeatedly. While the
-total size of the internal write buffer is below the threshold set by
-`highWaterMark`, calls to `writable.write()` will return `true`. Once the
-the size of the internal buffer reaches or exceeds the `highWaterMark`, `false`
-will be returned.
-A key goal of the `stream` API, and in particular the [`stream.pipe()`] method,
-is to limit the buffering of data to acceptable levels such that sources and
-destinations of differing speeds will not overwhelm the available memory.
-Because [Duplex][] and [Transform][] streams are both Readable and Writable,
-each maintain *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 faster or slower rate than data
-is received, it is important each side operate (and buffer) independently of
-the other.
-## API for Stream Consumers
-<!--type=misc-->
-Almost all Node.js applications, no matter how simple, use streams in some
-manner. The following is an example of using streams in a Node.js application
-that implements an HTTP server:
-```js
-const http = require('http');
-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
-  let body = '';
-  // Get the data as utf8 strings.
-  // If an encoding is not set, Buffer objects will be received.
-  req.setEncoding('utf8');
-  // Readable streams emit 'data' events once a listener is added
-  req.on('data', (chunk) => {
-    body += chunk;
-  });
-  // the end event indicates that the entire body has been received
-  req.on('end', () => {
-    try {
-      const data = JSON.parse(body);
-    } catch (er) {
-      // uh oh!  bad json!
-      res.statusCode = 400;
-      return res.end(`error: ${er.message}`);
-    }
-    // write back something interesting to the user:
-    res.write(typeof data);
-    res.end();
-  });
-});
-server.listen(1337);
-// $ curl localhost:1337 -d '{}'
-// object
-// $ curl localhost:1337 -d '"foo"'
-// string
-// $ curl localhost:1337 -d 'not json'
-// error: Unexpected token o
-```
-[Writable][] streams (such as `res` in the example) expose methods such as
-`write()` and `end()` that are used to write data onto the stream.
-[Readable][] streams use the [`EventEmitter`][] API for notifying application
-code when data is available to be read off the stream. That available data can
-be read from the stream in multiple ways.
-Both [Writable][] and [Readable][] streams use the [`EventEmitter`][] API in
-various ways to communicate the current state of the stream.
-[Duplex][] and [Transform][] streams are both [Writable][] and [Readable][].
-Applications that are either writing data to or consuming data from a stream
-are not required to implement the stream interfaces directly and will generally
-have no reason to call `require('stream')`.
-Developers wishing to implement new types of streams should refer to the
-section [API for Stream Implementers][].
-### Writable Streams
-Writable streams are an abstraction for a *destination* to which data is
-written.
-Examples of [Writable][] streams include:
-* [HTTP requests, on the client][]
-* [HTTP responses, on the server][]
-* [fs write streams][]
-* [zlib streams][zlib]
-* [crypto streams][crypto]
-* [TCP sockets][]
-* [child process stdin][]
-* [`process.stdout`][], [`process.stderr`][]
-*Note*: Some of these examples are actually [Duplex][] streams that implement
-the [Writable][] interface.
-All [Writable][] streams implement the interface defined by the
-`stream.Writable` class.
-While specific instances of [Writable][] streams may differ in various ways,
-all Writable streams follow the same fundamental usage pattern as illustrated
-in the example below:
-```js
-const myStream = getWritableStreamSomehow();
-myStream.write('some data');
-myStream.write('some more data');
-myStream.end('done writing data');
-```
-#### Class: stream.Writable
-<!-- YAML
-added: v0.9.4
--->
-<!--type=class-->
-##### Event: 'close'
-<!-- YAML
-added: v0.9.4
--->
-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
-that no more events will be emitted, and no further computation will occur.
-Not all Writable streams will emit the `'close'` event.
-##### Event: 'drain'
-<!-- YAML
-added: v0.9.4
--->
-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
-to the stream.
-```js
-// Write the data to the supplied writable stream one million times.
-// Be attentive to back-pressure.
-function writeOneMillionTimes(writer, data, encoding, callback) {
-  let i = 1000000;
-  write();
-  function write() {
-    var ok = true;
-    do {
-      i--;
-      if (i === 0) {
-        // last time!
-        writer.write(data, encoding, callback);
-      } else {
-        // see if we should continue, or wait
-        // don't pass the callback, because we're not done yet.
-        ok = writer.write(data, encoding);
-      }
-    } while (i > 0 && ok);
-    if (i > 0) {
-      // had to stop early!
-      // write some more once it drains
-      writer.once('drain', write);
-    }
-  }
-}
-```
-##### Event: 'error'
-<!-- YAML
-added: v0.9.4
--->
-* {Error}
-The `'error'` event is emitted if an error occurred while writing or piping
-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'
-<!-- YAML
-added: v0.9.4
--->
-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.
-```js
-const writer = getWritableStreamSomehow();
-for (var i = 0; i < 100; i ++) {
-  writer.write('hello, #${i}!\n');
-}
-writer.end('This is the end\n');
-writer.on('finish', () => {
-  console.error('All writes are now complete.');
-});
-```
-##### Event: 'pipe'
-<!-- YAML
-added: v0.9.4
--->
-* `src` {stream.Readable} source stream that is piping to this writable
-The `'pipe'` event is emitted when the [`stream.pipe()`][] method is called on
-a readable stream, adding this writable to its set of destinations.
-```js
-const writer = getWritableStreamSomehow();
-const reader = getReadableStreamSomehow();
-writer.on('pipe', (src) => {
-  console.error('something is piping into the writer');
-  assert.equal(src, reader);
-});
-reader.pipe(writer);
-```
-##### Event: 'unpipe'
-<!-- YAML
-added: v0.9.4
--->
-* `src` {[Readable][] Stream} The source stream that
-  [unpiped][`stream.unpipe()`] this writable
-The `'unpipe'` event is emitted when the [`stream.unpipe()`][] method is called
-on a [Readable][] stream, removing this [Writable][] from its set of
-destinations.
-```js
-const writer = getWritableStreamSomehow();
-const reader = getReadableStreamSomehow();
-writer.on('unpipe', (src) => {
-  console.error('Something has stopped piping into the writer.');
-  assert.equal(src, reader);
-});
-reader.pipe(writer);
-reader.unpipe(writer);
-```
-##### writable.cork()
-<!-- YAML
-added: v0.11.2
--->
-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
-[`stream.end()`][stream-end] methods are called.
-The primary intent of `writable.cork()` is to avoid a situation where writing
-many small chunks of data to a stream do not cause an backup in the internal
-buffer that would have an adverse impact on performance. In such situations,
-implementations that implement the `writable._writev()` method can perform
-buffered writes in a more optimized manner.
-##### writable.end([chunk][, encoding][, callback])
-<!-- YAML
-added: v0.9.4
--->
-* `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
-  streams, `chunk` may be any JavaScript value other than `null`.
-* `encoding` {String} The encoding, if `chunk` is a String
-* `callback` {Function} Optional callback for when the stream is finished
-Calling the `writable.end()` method signals that no more data will be written
-to the [Writable][]. The optional `chunk` and `encoding` arguments allow one
-final additional chunk of data to be written immediately before closing the
-stream. If provided, the optional `callback` function is attached as a listener
-for the [`'finish'`][] event.
-Calling the [`stream.write()`][stream-write] method after calling
-[`stream.end()`][stream-end] will raise an error.
-```js
-// write 'hello, ' and then end with 'world!'
-const file = fs.createWriteStream('example.txt');
-file.write('hello, ');
-file.end('world!');
-// writing more now is not allowed!
-```
-##### writable.setDefaultEncoding(encoding)
-<!-- YAML
-added: v0.11.15
--->
-* `encoding` {String} The new default encoding
-* Return: `this`
-The `writable.setDefaultEncoding()` method sets the default `encoding` for a
-[Writable][] stream.
-##### writable.uncork()
-<!-- YAML
-added: v0.11.2
--->
-The `writable.uncork()` method flushes all data buffered since
-[`stream.cork()`][] was called.
-When using `writable.cork()` and `writable.uncork()` to manage the buffering
-of writes to a stream, it is recommended that calls to `writable.uncork()` be
-deferred using `process.nextTick()`. Doing so allows batching of all
-`writable.write()` calls that occur within a given Node.js event loop phase.
-```js
-stream.cork();
-stream.write('some ');
-stream.write('data ');
-process.nextTick(() => stream.uncork());
-```
-If the `writable.cork()` method is called multiple times on a stream, the same
-number of calls to `writable.uncork()` must be called to flush the buffered
-data.
-```
-stream.cork();
-stream.write('some ');
-stream.cork();
-stream.write('data ');
-process.nextTick(() => {
-  stream.uncork();
-  // The data will not be flushed until uncork() is called a second time.
-  stream.uncork();
-});
-```
-##### writable.write(chunk[, encoding][, callback])
-<!-- YAML
-added: v0.9.4
--->
-* `chunk` {String|Buffer} The data to write
-* `encoding` {String} The encoding, if `chunk` is a String
-* `callback` {Function} Callback for when this chunk of data is flushed
-* Returns: {Boolean} `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`.
-The `writable.write()` method writes some data to the stream, and calls the
-supplied `callback` once the data has been fully handled. If an error
-occurs, the `callback` *may or may not* be called with the error as its
-first argument. To reliably detect write errors, add a listener for the
-`'error'` event.
-The return value indicates whether the written `chunk` was buffered internally
-and the buffer has exceeded the `highWaterMark` configured when the stream was
-created. If `false` is returned, further attempts to write data to the stream
-should be paused until the `'drain'` event is emitted.
-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
-consumed.
-Examples of Readable streams include:
-* [HTTP responses, on the client][http-incoming-message]
-* [HTTP requests, on the server][http-incoming-message]
-* [fs read streams][]
-* [zlib streams][zlib]
-* [crypto streams][crypto]
-* [TCP sockets][]
-* [child process stdout and stderr][]
-* [`process.stdin`][]
-All [Readable][] streams implement the interface defined by the
-`stream.Readable` class.
-#### Two Modes
-Readable streams effectively operate in one of two modes: flowing and paused.
-When in flowing mode, data is read from the underlying system automatically
-and provided to an application as quickly as possible using events via the
-[`EventEmitter`][] interface.
-In paused mode, the [`stream.read()`][stream-read] method must be called
-explicitly to read chunks of data from the stream.
-All [Readable][] streams begin in paused mode but can be switched to flowing
-mode in one of the following ways:
-* Adding a [`'data'`][] event handler.
-* Calling the [`stream.resume()`][stream-resume] method.
-* Calling the [`stream.pipe()`][] method to send the data to a [Writable][].
-The Readable can switch back to paused mode using one of the following:
-* If there are no pipe destinations, by calling the
-  [`stream.pause()`][stream-pause] method.
-* If there are pipe destinations, by removing any [`'data'`][] event
-  handlers, and removing all pipe destinations by calling the
-  [`stream.unpipe()`][] method.
-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*
-to stop generating the data.
-*Note*: For backwards 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.
-*Note*: If a [Readable][] is switched into flowing mode and there are no
-consumers available handle the data, that data will be lost. This can occur,
-for instance, when the `readable.resume()` method is called without a listener
-attached to the `'data'` event, or when a `'data'` event handler is removed
-from the stream.
-#### Three States
-The "two modes" of operation for a Readable stream are a simplified abstraction
-for the more complicated internal state management that is happening within the
-Readable stream implementation.
-Specifically, at any given point in time, every Readable is in one of three
-possible states:
-* `readable._readableState.flowing = null`
-* `readable._readableState.flowing = false`
-* `readable._readableState.flowing = true`
-When `readable._readableState.flowing` is `null`, no mechanism for consuming the
-streams data is provided so the stream will not generate its data.
-Attaching a listener for the `'data'` event, calling the `readable.pipe()`
-method, or calling the `readable.resume()` method will switch
-`readable._readableState.flowing` to `true`, causing the Readable to begin
-actively emitting events as data is generated.
-Calling `readable.pause()`, `readable.unpipe()`, or receiving "back pressure"
-will cause the `readable._readableState.flowing` to be set as `false`,
-temporarily halting the flowing of events but *not* halting the generation of
-data.
-While `readable._readableState.flowing` is `false`, data may be accumulating
-within the streams internal buffer.
-#### Choose One
-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
-to consume data from a single stream.
-Use of the `readable.pipe()` method is recommended for most users as it has been
-implemented to provide the easiest way of consuming stream data. Developers that
-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
-<!-- YAML
-added: v0.9.4
--->
-<!--type=class-->
-##### Event: 'close'
-<!-- YAML
-added: v0.9.4
--->
-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
-that no more events will be emitted, and no further computation will occur.
-Not all [Readable][] streams will emit the `'close'` event.
-##### Event: 'data'
-<!-- YAML
-added: v0.9.4
--->
-* `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`.
-  For streams that are in object mode, the chunk can be any JavaScript value
-  other than `null`.
-The `'data'` event is emitted whenever the stream is relinquishing ownership of
-a chunk of data to a consumer. This may occur whenever the stream is switched
-in flowing mode by calling `readable.pipe()`, `readable.resume()`, or by
-attaching a listener callback to the `'data'` event. The `'data'` event will
-also be emitted whenever the `readable.read()` method is called and a chunk of
-data is available to be returned.
-Attaching a `'data'` event listener to a stream that has not been explicitly
-paused will switch the stream into flowing mode. Data will then be passed as
-soon as it is available.
-The listener callback will be passed the chunk of data as a string if a default
-encoding has been specified for the stream using the
-`readable.setEncoding()` method; otherwise the data will be passed as a
-`Buffer`.
-```js
-const readable = getReadableStreamSomehow();
-readable.on('data', (chunk) => {
-  console.log(`Received ${chunk.length} bytes of data.`);
-});
-```
-##### Event: 'end'
-<!-- YAML
-added: v0.9.4
--->
-The `'end'` event is emitted when there is no more data to be consumed from
-the stream.
-*Note*: The `'end'` event **will not be emitted** unless the data is
-completely consumed. This can be accomplished by switching the stream into
-flowing mode, or by calling [`stream.read()`][stream-read] repeatedly until
-all data has been consumed.
-```js
-const readable = getReadableStreamSomehow();
-readable.on('data', (chunk) => {
-  console.log(`Received ${chunk.length} bytes of data.`);
-});
-readable.on('end', () => {
-  console.log('There will be no more data.');
-});
-```
-##### Event: 'error'
-<!-- YAML
-added: v0.9.4
--->
-* {Error}
-The `'error'` event may be emitted by a Readable implementation at any time.
-Typically, this may occur if the underlying stream in unable to generate data
-due to an underlying internal failure, or when a stream implementation attempts
-to push an invalid chunk of data.
-The listener callback will be passed a single `Error` object.
-##### Event: 'readable'
-<!-- YAML
-added: v0.9.4
--->
-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
-cause some amount of data to be read into an internal buffer.
-```javascript
-const readable = getReadableStreamSomehow();
-readable.on('readable', () => {
-  // there is some data to read now
-});
-```
-The `'readable'` event will also be emitted once the end of the stream data
-has been reached but before the `'end'` event is emitted.
-Effectively, the `'readable'` event indicates that the stream has new
-information: either new data is available or the end of the stream has been
-reached. In the former case, [`stream.read()`][stream-read] will return the
-available data. In the latter case, [`stream.read()`][stream-read] will return
-`null`. For instance, in the following example, `foo.txt` is an empty file:
-```js
-const fs = require('fs');
-const rr = fs.createReadStream('foo.txt');
-rr.on('readable', () => {
-  console.log('readable:', rr.read());
-});
-rr.on('end', () => {
-  console.log('end');
-});
-```
-The output of running this script is:
-```
-$ node test.js
-readable: null
-end
-```
-*Note*: In general, the `readable.pipe()` and `'data'` event mechanisms are
-preferred over the use of the `'readable'` event.
-##### readable.isPaused()
-<!--
-added: v0.11.14
--->
-* Return: {Boolean}
-The `readable.isPaused()` method returns the current operating state of the
-Readable. This is used primarily by the mechanism that underlies the
-`readable.pipe()` method. In most typical cases, there will be no reason to
-use this method directly.
-```js
-const readable = new stream.Readable
-readable.isPaused() // === false
-readable.pause()
-readable.isPaused() // === true
-readable.resume()
-readable.isPaused() // === false
-```
-##### readable.pause()
-<!-- YAML
-added: v0.9.4
--->
-* Return: `this`
-The `readable.pause()` method will cause a stream in flowing mode to stop
-emitting [`'data'`][] events, switching out of flowing mode. Any data that
-becomes available will remain in the internal buffer.
-```js
-const readable = getReadableStreamSomehow();
-readable.on('data', (chunk) => {
-  console.log(`Received ${chunk.length} bytes of data.`);
-  readable.pause();
-  console.log('There will be no additional data for 1 second.');
-  setTimeout(() => {
-    console.log('Now data will start flowing again.');
-    readable.resume();
-  }, 1000);
-});
-```
-##### readable.pipe(destination[, options])
-<!-- YAML
-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. Defaults to `true`.
-The `readable.pipe()` method attaches a [Writable][] stream to the `readable`,
-causing it to switch automatically into flowing mode and push all of its data
-to the attached [Writable][]. The flow of data will be automatically managed so
-that the destination Writable stream is not overwhelmed by a faster Readable
-stream.
-The following example pipes all of the data from the `readable` into a file
-named `file.txt`:
-```js
-const readable = getReadableStreamSomehow();
-const writable = fs.createWriteStream('file.txt');
-// All the data from readable goes into 'file.txt'
-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
-making it possible to set up chains of piped streams:
-```js
-const r = fs.createReadStream('file.txt');
-const z = zlib.createGzip();
-const w = fs.createWriteStream('file.txt.gz');
-r.pipe(z).pipe(w);
-```
-By default, [`stream.end()`][stream-end] is called on the destination Writable
-stream when the source Readable stream emits [`'end'`][], so that the
-destination is no longer writable. To disable this default behavior, the `end`
-option can be passed as `false`, causing the destination stream to remain open,
-as illustrated in the following example:
-```js
-reader.pipe(writer, { end: false });
-reader.on('end', () => {
-  writer.end('Goodbye\n');
-});
-```
-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
-to prevent memory leaks.
-*Note*: 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
--->
-* `size` {Number} Optional argument to specify how much data to read.
-* Return {String|Buffer|Null}
-The `readable.read()` method pulls some data out of the internal buffer and
-returns it. If no data available to be read, `null` is returned. By default,
-the data will be returned as a `Buffer` object unless an encoding has been
-specified using the `readable.setEncoding()` method or the stream is operating
-in object mode.
-The optional `size` argument specifies a specific number of bytes to read. If
-`size` bytes are not available to be read, `null` will be returned *unless*
-the stream has ended, in which case all of the data remaining in the internal
-buffer will be returned (*even if it exceeds `size` bytes*).
-If the `size` argument is not specified, all of the data contained in the
-internal buffer will be returned.
-The `readable.read()` method should only be called on Readable streams operating
-in paused mode. In flowing mode, `readable.read()` is called automatically until
-the internal buffer is fully drained.
-```js
-const readable = getReadableStreamSomehow();
-readable.on('readable', () => {
-  var chunk;
-  while (null !== (chunk = readable.read())) {
-    console.log(`Received ${chunk.length} bytes of data.`);
-  }
-});
-```
-In general, it is recommended that developers avoid the use of the `'readable'`
-event and the `readable.read()` method in favor of using either
-`readable.pipe()` or the `'data'` event.
-A Readable stream in object mode will always return a single item from
-a call to [`readable.read(size)`][stream-read], regardless of the value of the
-`size` argument.
-*Note:* If the `readable.read()` method returns a chunk of data, a `'data'`
-event will also be emitted.
-*Note*: Calling [`stream.read([size])`][stream-read] after the [`'end'`][]
-event has been emitted will return `null`. No runtime error will be raised.
-##### readable.resume()
-<!-- YAML
-added: v0.9.4
--->
-* Return: `this`
-The `readable.resume()` method causes an explicitly paused Readable stream to
-resume emitting [`'data'`][] events, switching the stream into flowing mode.
-The `readable.resume()` method can be used to fully consume the data from a
-stream without actually processing any of that data as illustrated in the
-following example:
-```js
-getReadableStreamSomehow()
-  .resume()
-  .on('end', () => {
-    console.log('Reached the end, but did not read anything.');
-  });
-```
-##### readable.setEncoding(encoding)
-<!-- YAML
-added: v0.9.4
--->
-* `encoding` {String} The encoding to use.
-* Return: `this`
-The `readable.setEncoding()` method sets the default character encoding for
-data read from the Readable stream.
-Setting an encoding causes the stream data
-to be returned as string of the specified encoding rather than as `Buffer`
-objects. For instance, calling `readable.setEncoding('utf8')` will cause the
-output data will be interpreted as UTF-8 data, and passed as strings. Calling
-`readable.setEncoding('hex')` will cause the data to be encoded in hexadecimal
-string format.
-The Readable stream will properly handle multi-byte characters delivered through
-the stream that would otherwise become improperly decoded if simply pulled from
-the stream as `Buffer` objects.
-Encoding can be disabled by calling `readable.setEncoding(null)`. This approach
-is useful when working with binary data or with large multi-byte strings spread
-out over multiple chunks.
-```js
-const readable = getReadableStreamSomehow();
-readable.setEncoding('utf8');
-readable.on('data', (chunk) => {
-  assert.equal(typeof chunk, 'string');
-  console.log('got %d characters of string data', chunk.length);
-});
-```
-##### readable.unpipe([destination])
-<!-- YAML
-added: v0.9.4
--->
-* `destination` {stream.Writable} Optional specific stream to unpipe
-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 specified, but no pipe is set up for it, then
-the method does nothing.
-```js
-const readable = getReadableStreamSomehow();
-const writable = fs.createWriteStream('file.txt');
-// All the data from readable goes into 'file.txt',
-// but only for the first second
-readable.pipe(writable);
-setTimeout(() => {
-  console.log('Stop writing to file.txt');
-  readable.unpipe(writable);
-  console.log('Manually close the file stream');
-  writable.end();
-}, 1000);
-```
-##### readable.unshift(chunk)
-<!-- YAML
-added: v0.9.11
--->
-* `chunk` {Buffer|String} Chunk of data to unshift onto the read queue
-The `readable.unshift()` method pushes a chunk of data back into the internal
-buffer. This is useful in certain situations where a stream is being consumed by
-code that needs to "un-consume" some amount of data that it has optimistically
-pulled out of the source, so that the data can be passed on to some other party.
-*Note*: The `stream.unshift(chunk)` method cannot be called after the
-[`'end'`][] event has been emitted or a runtime error will be thrown.
-Developers using `stream.unshift()` often should consider switching to
-use of a [Transform][] stream instead. See the [API for Stream Implementers][]
-section for more information.
-```js
-// Pull off a header delimited by \n\n
-// use unshift() if we get too much
-// Call the callback with (error, header, stream)
-const StringDecoder = require('string_decoder').StringDecoder;
-function parseHeader(stream, callback) {
-  stream.on('error', callback);
-  stream.on('readable', onReadable);
-  const decoder = new StringDecoder('utf8');
-  var header = '';
-  function onReadable() {
-    var chunk;
-    while (null !== (chunk = stream.read())) {
-      var str = decoder.write(chunk);
-      if (str.match(/\n\n/)) {
-        // found the header boundary
-        var split = str.split(/\n\n/);
-        header += split.shift();
-        const remaining = split.join('\n\n');
-        const buf = Buffer.from(remaining, 'utf8');
-        if (buf.length)
-          stream.unshift(buf);
-        stream.removeListener('error', callback);
-        stream.removeListener('readable', onReadable);
-        // now the body of the message can be read from the stream.
-        callback(null, header, stream);
-      } else {
-        // still reading the header.
-        header += str;
-      }
-    }
-  }
-}
-```
-*Note*: Unlike [`stream.push(chunk)`][stream-push], `stream.unshift(chunk)`
-will not end the reading process by resetting the internal reading state of the
-stream. This can cause unexpected results if `readable.unshift()` is called
-during a read (i.e. from within a [`stream._read()`][stream-_read]
-implementation on a custom stream). Following the call to `readable.unshift()`
-with an immediate [`stream.push('')`][stream-push] will reset the reading state
-appropriately, 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
--->
-* `stream` {Stream} An "old style" readable stream
-Versions of Node.js prior to v0.10 had streams that did not implement the
-entire `stream` module API as it is currently defined. (See [Compatibility][]
-for more information.)
-When using an older Node.js library that emits [`'data'`][] events and has a
-[`stream.pause()`][stream-pause] method that is advisory only, the
-`readable.wrap()` method can be used to create a [Readable][] stream that uses
-the old stream as its data source.
-It will rarely be necessary to use `readable.wrap()` but the method has been
-provided as a convenience for interacting with older Node.js applications and
-libraries.
-For example:
-```js
-const OldReader = require('./old-api-module.js').OldReader;
-const Readable = require('stream').Readable;
-const oreader = new OldReader;
-const myReader = new Readable().wrap(oreader);
-myReader.on('readable', () => {
-  myReader.read(); // etc.
-});
-```
-### Duplex and Transform Streams
-#### Class: stream.Duplex
-<!-- YAML
-added: v0.9.4
--->
-<!--type=class-->
-Duplex streams are streams that implement both the [Readable][] and
-[Writable][] interfaces.
-Examples of Duplex streams include:
-* [TCP sockets][]
-* [zlib streams][zlib]
-* [crypto streams][crypto]
-#### Class: stream.Transform
-<!-- YAML
-added: v0.9.4
--->
-<!--type=class-->
-Transform streams are [Duplex][] streams where the output is in some way
-related to the input. Like all [Duplex][] streams, Transform streams
-implement both the [Readable][] and [Writable][] interfaces.
-Examples of Transform streams include:
-* [zlib streams][zlib]
-* [crypto streams][crypto]
-## API for Stream Implementers
-<!--type=misc-->
-The `stream` module API has been designed to make it possible to easily
-implement streams using JavaScript's prototypical inheritance model.
-First, a stream developer would declare a new JavaScript class that extends one
-of the four basic stream classes (`stream.Writable`, `stream.Readable`,
-`stream.Duplex`, or `stream.Transform`), making sure the call the appropriate
-parent class constructor:
-```js
-const Writable = require('stream').Writable;
-class MyWritable extends Writable {
-  constructor(options) {
-    super(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:
-<table>
-  <thead>
-    <tr>
-      <th>
-        <p>Use-case</p>
-      </th>
-      <th>
-        <p>Class</p>
-      </th>
-      <th>
-        <p>Method(s) to implement</p>
-      </th>
-    </tr>
-  </thead>
-  <tr>
-    <td>
-      <p>Reading only</p>
-    </td>
-    <td>
-      <p>[Readable](#stream_class_stream_readable)</p>
-    </td>
-    <td>
-      <p><code>[_read][stream-_read]</code></p>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <p>Writing only</p>
-    </td>
-    <td>
-      <p>[Writable](#stream_class_stream_writable)</p>
-    </td>
-    <td>
-      <p><code>[_write][stream-_write]</code>, <code>[_writev][stream-_writev]</code></p>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <p>Reading and writing</p>
-    </td>
-    <td>
-      <p>[Duplex](#stream_class_stream_duplex)</p>
-    </td>
-    <td>
-      <p><code>[_read][stream-_read]</code>, <code>[_write][stream-_write]</code>, <code>[_writev][stream-_writev]</code></p>
-    </td>
-  </tr>
-  <tr>
-    <td>
-      <p>Operate on written data, then read the result</p>
-    </td>
-    <td>
-      <p>[Transform](#stream_class_stream_transform)</p>
-    </td>
-    <td>
-      <p><code>[_transform][stream-_transform]</code>, <code>[_flush][stream-_flush]</code></p>
-    </td>
-  </tr>
-</table>
-*Note*: 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.
-### Simplified Construction
-For many simple cases, it is possible to construct a stream without relying on
-inheritance. This can be accomplished by directly creating instances of the
-`stream.Writable`, `stream.Readable`, `stream.Duplex` or `stream.Transform`
-objects and passing appropriate methods as constructor options.
-For example:
-```js
-const Writable = require('stream').Writable;
-const myWritable = new Writable({
-  write(chunk, encoding, callback) {
-    // ...
-  }
-});
-```
-### Implementing a Writable Stream
-The `stream.Writable` class is extended to implement a [Writable][] stream.
-Custom Writable streams *must* call the `new stream.Writable([options])`
-constructor and implement the `writable._write()` method. The
-`writable._writev()` method *may* also be implemented.
-#### Constructor: new stream.Writable([options])
-* `options` {Object}
-  * `highWaterMark` {Number} Buffer level when
-    [`stream.write()`][stream-write] starts returning `false`. Defaults to
-    `16384` (16kb), or `16` for `objectMode` streams.
-  * `decodeStrings` {Boolean} Whether or not to decode strings into
-    Buffers before passing them to [`stream._write()`][stream-_write].
-    Defaults to `true`
-  * `objectMode` {Boolean} Whether or not the
-    [`stream.write(anyObj)`][stream-write] is a valid operation. When set,
-    it becomes possible to write JavaScript values other than string or
-    `Buffer` if supported by the stream implementation. Defaults to `false`
-  * `write` {Function} Implementation for the
-    [`stream._write()`][stream-_write] method.
-  * `writev` {Function} Implementation for the
-    [`stream._writev()`][stream-_writev] method.
-For example:
-```js
-const Writable = require('stream').Writable;
-class MyWritable extends Writable {
-  constructor(options) {
-    // Calls the stream.Writable() constructor
-    super(options);
-  }
-}
-```
-Or, when using pre-ES6 style constructors:
-```js
-const Writable = require('stream').Writable;
-const util = require('util');
-function MyWritable(options) {
-  if (!(this instanceof MyWritable))
-    return new MyWritable(options);
-  Writable.call(this, options);
-}
-util.inherits(MyWritable, Writable);
-```
-Or, using the Simplified Constructor approach:
-```js
-const Writable = require('stream').Writable;
-const myWritable = new Writable({
-  write(chunk, encoding, callback) {
-    // ...
-  },
-  writev(chunks, callback) {
-    // ...
-  }
-});
-```
-#### writable.\_write(chunk, encoding, callback)
-* `chunk` {Buffer|String} The chunk to be written. Will **always**
-  be a buffer unless the `decodeStrings` option was set to `false`.
-* `encoding` {String} If the chunk is a string, then `encoding` is the
-  character encoding of that string. If chunk is a `Buffer`, or if the
-  stream is operating in object mode, `encoding` may be ignored.
-* `callback` {Function} Call this function (optionally with an error
-  argument) when processing is complete for the supplied chunk.
-All Writable stream implementations must provide a
-[`writable._write()`][stream-_write] method to send data to the underlying
-resource.
-*Note*: [Transform][] streams provide their own implementation of the
-[`writable._write()`][stream-_write].
-*Note*: **This function MUST NOT be called by application code directly.** It
-should be implemented by child classes, and called only by the internal Writable
-class methods only.
-The `callback` method must be called to signal either that the write completed
-successfully or failed with an error. The first argument passed to the
-`callback` must be the `Error` object if the call failed or `null` if the
-write succeeded.
-It is important to note that all calls to `writable.write()` that occur between
-the time `writable._write()` is called and the `callback` is called will cause
-the written data to be buffered. Once the `callback` is invoked, the stream will
-emit a `'drain'` event. If a stream implementation is capable of processing
-multiple chunks of data at once, the `writable._writev()` method should be
-implemented.
-If the `decodeStrings` property is set in the constructor options, then
-`chunk` may be a string rather than a Buffer, and `encoding` will
-indicate the character encoding of the string. This is to support
-implementations that have an optimized handling for certain string
-data encodings. If the `decodeStrings` property is explicitly set to `false`,
-the `encoding` argument can be safely ignored, and `chunk` will always be a
-`Buffer`.
-The `writable._write()` method is prefixed with an underscore because it is
-internal to the class that defines it, and should never be called directly by
-user programs.
-#### writable.\_writev(chunks, callback)
-* `chunks` {Array} The chunks to be written. Each chunk has following
-  format: `{ chunk: ..., encoding: ... }`.
-* `callback` {Function} A callback function (optionally with an error
-  argument) to be invoked when processing is complete for the supplied chunks.
-*Note*: **This function MUST NOT be called by application code directly.** It
-should be implemented by child classes, and called only by the internal Writable
-class methods only.
-The `writable._writev()` method may be implemented in addition to
-`writable._write()` in stream implementations that are capable of processing
-multiple chunks of data at once. If implemented, the method will be called with
-all chunks of data currently buffered in the write queue.
-The `writable._writev()` method is prefixed with an underscore because it is
-internal to the class that defines it, and should never be called directly by
-user programs.
-#### Errors While Writing
-It is recommended that errors occurring during the processing of the
-`writable._write()` and `writable._writev()` methods are reported by invoking
-the callback and passing the error as the first argument. This will cause an
-`'error'` event to be emitted by the Writable. Throwing an Error from within
-`writable._write()` can result in expected and inconsistent behavior depending
-on how the stream is being used.  Using the callback ensures consistent and
-predictable handling of errors.
-```js
-const Writable = require('stream').Writable;
-const myWritable = new Writable({
-  write(chunk, encoding, callback) {
-    if (chunk.toString().indexOf('a') >= 0) {
-      callback(new Error('chunk is invalid'));
-    } else {
-      callback();
-    }
-  }
-});
-```
-#### An Example Writable Stream
-The following illustrates a rather simplistic (and somewhat pointless) custom
-Writable stream implementation. While this specific Writable stream instance
-is not of any real particular usefulness, the example illustrates each of the
-required elements of a custom [Writable][] stream instance:
-```js
-const Writable = require('stream').Writable;
-class MyWritable extends Writable {
-  constructor(options) {
-    super(options);
-  }
-  _write(chunk, encoding, callback) {
-    if (chunk.toString().indexOf('a') >= 0) {
-      callback(new Error('chunk is invalid'));
-    } else {
-      callback();
-    }
-  }
-}
-```
-### Implementing a Readable Stream
-The `stream.Readable` class is extended to implement a [Readable][] stream.
-Custom Readable streams *must* call the `new stream.Readable([options])`
-constructor and implement the `readable._read()` method.
-#### new stream.Readable([options])
-* `options` {Object}
-  * `highWaterMark` {Number} The maximum number of bytes to store in
-    the internal buffer before ceasing to read from the underlying
-    resource. Defaults to `16384` (16kb), or `16` for `objectMode` streams
-  * `encoding` {String} If specified, then buffers will be decoded to
-    strings using the specified encoding. Defaults to `null`
-  * `objectMode` {Boolean} Whether this stream should behave
-    as a stream of objects. Meaning that [`stream.read(n)`][stream-read] returns
-    a single value instead of a Buffer of size n. Defaults to `false`
-  * `read` {Function} Implementation for the [`stream._read()`][stream-_read]
-    method.
-For example:
-```js
-const Readable = require('stream').Readable;
-class MyReadable extends Readable {
-  constructor(options) {
-    // Calls the stream.Readable(options) constructor
-    super(options);
-  }
-}
-```
-Or, when using pre-ES6 style constructors:
-```js
-const Readable = require('stream').Readable;
-const util = require('util');
-function MyReadable(options) {
-  if (!(this instanceof MyReadable))
-    return new MyReadable(options);
-  Readable.call(this, options);
-}
-util.inherits(MyReadable, Readable);
-```
-Or, using the Simplified Constructor approach:
-```js
-const Readable = require('stream').Readable;
-const myReadable = new Readable({
-  read(size) {
-    // ...
-  }
-});
-```
-#### readable.\_read(size)
-* `size` {Number} Number of bytes to read asynchronously
-*Note*: **This function MUST NOT be called by application code directly.** It
-should be implemented by child classes, and called only by the internal Readable
-class methods only.
-All Readable stream implementations must provide an implementation of the
-`readable._read()` method to fetch data from the underlying resource.
-When `readable._read()` is called, if data is available from the resource, the
-implementation should begin pushing that data into the read queue using the
-[`this.push(dataChunk)`][stream-push] method. `_read()` should continue reading
-from the resource and pushing data until `readable.push()` returns `false`. Only
-when `_read()` is called again after it has stopped should it resume pushing
-additional data onto the queue.
-*Note*: Once the `readable._read()` method has been called, it will not be
-called again until the [`readable.push()`][stream-push] method is called.
-The `size` argument is advisory. For implementations where a "read" is a
-single operation that returns data can use the `size` argument to determine how
-much data to fetch. Other implementations may ignore this argument and simply
-provide data whenever it becomes available. There is no need to "wait" until
-`size` bytes are available before calling [`stream.push(chunk)`][stream-push].
-The `readable._read()` method is prefixed with an underscore because it is
-internal to the class that defines it, and should never be called directly by
-user programs.
-#### readable.push(chunk[, encoding])
-* `chunk` {Buffer|Null|String} Chunk of data to push into the read queue
-* `encoding` {String} Encoding of String chunks.  Must be a valid
-  Buffer encoding, such as `'utf8'` or `'ascii'`
-* Returns {Boolean} `true` if additional chunks of data may continued to be
-  pushed; `false` otherwise.
-When `chunk` is a `Buffer` or `string`, the `chunk` of data will be added to the
-internal queue for users of the stream to consume. Passing `chunk` as `null`
-signals the end of the stream (EOF), after which no more data can be written.
-When the Readable is operating in paused mode, the data added with
-`readable.push()` can be read out by calling the
-[`readable.read()`][stream-read] method when the [`'readable'`][] event is
-emitted.
-When the Readable is operating in flowing mode, the data added with
-`readable.push()` will be delivered by emitting a `'data'` event.
-The `readable.push()` method is designed to be as flexible as possible. For
-example, when wrapping a lower-level source that provides some form of
-pause/resume mechanism, and a data callback, the low-level source can be wrapped
-by the custom Readable instance as illustrated in the following example:
-```js
-// source is an object with readStop() and readStart() methods,
-// and an `ondata` member that gets called when it has data, and
-// an `onend` member that gets called when the data is over.
-class SourceWrapper extends Readable {
-  constructor(options) {
-    super(options);
-    this._source = getLowlevelSourceObject();
-    // Every time there's data, push it into the internal buffer.
-    this._source.ondata = (chunk) => {
-      // if push() returns false, then stop reading from source
-      if (!this.push(chunk))
-        this._source.readStop();
-    };
-    // When the source ends, push the EOF-signaling `null` chunk
-    this._source.onend = () => {
-      this.push(null);
-    };
-  }
-  // _read will be called when the stream wants to pull more data in
-  // the advisory size argument is ignored in this case.
-  _read(size) {
-    this._source.readStart();
-  }
-}
-```
-*Note*: The `readable.push()` method is intended be called only by Readable
-Implementers, and only from within the `readable._read()` method.
-#### Errors While Reading
-It is recommended that errors occurring during the processing of the
-`readable._read()` method are emitted using the `'error'` event rather than
-being thrown. Throwing an Error from within `readable._read()` can result in
-expected and inconsistent behavior depending on whether the stream is operating
-in flowing or paused mode. Using the `'error'` event ensures consistent and
-predictable handling of errors.
-```js
-const Readable = require('stream').Readable;
-const myReadable = new Readable({
-  read(size) {
-    if (checkSomeErrorCondition()) {
-      process.nextTick(() => this.emit('error', err));
-      return;
-    }
-    // do some work
-  }
-});
-```
-#### An Example Counting Stream
-<!--type=example-->
-The following is a basic example of a Readable stream that emits the numerals
-from 1 to 1,000,000 in ascending order, and then ends.
-```js
-const Readable = require('stream').Readable;
-class Counter extends Readable {
-  constructor(opt) {
-    super(opt);
-    this._max = 1000000;
-    this._index = 1;
-  }
-  _read() {
-    var i = this._index++;
-    if (i > this._max)
-      this.push(null);
-    else {
-      var str = '' + i;
-      var buf = Buffer.from(str, 'ascii');
-      this.push(buf);
-    }
-  }
-}
-```
-### Implementing a Duplex Stream
-A [Duplex][] stream is one that implements both [Readable][] and [Writable][],
-such as a TCP socket connection.
-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).
-*Note*: The `stream.Duplex` class prototypically inherits from `stream.Readable`
-and parasitically from `stream.Writable`.
-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)
-* `options` {Object} Passed to both Writable and Readable
-  constructors. Also has the following fields:
-  * `allowHalfOpen` {Boolean} Defaults to `true`. If set to `false`, then
-    the stream will automatically end the readable side when the
-    writable side ends and vice versa.
-  * `readableObjectMode` {Boolean} Defaults to `false`. Sets `objectMode`
-    for readable side of the stream. Has no effect if `objectMode`
-    is `true`.
-  * `writableObjectMode` {Boolean} Defaults to `false`. Sets `objectMode`
-    for writable side of the stream. Has no effect if `objectMode`
-    is `true`.
-For example:
-```js
-const Duplex = require('stream').Duplex;
-class MyDuplex extends Duplex {
-  constructor(options) {
-    super(options);
-  }
-}
-```
-Or, when using pre-ES6 style constructors:
-```js
-const Duplex = require('stream').Duplex;
-const util = require('util');
-function MyDuplex(options) {
-  if (!(this instanceof MyDuplex))
-    return new MyDuplex(options);
-  Duplex.call(this, options);
-}
-util.inherits(MyDuplex, Duplex);
-```
-Or, using the Simplified Constructor approach:
-```js
-const Duplex = require('stream').Duplex;
-const myDuplex = new Duplex({
-  read(size) {
-    // ...
-  },
-  write(chunk, encoding, callback) {
-    // ...
-  }
-});
-```
-#### An Example Duplex Stream
-The following illustrates a simple example of a Duplex stream that wraps a
-hypothetical lower-level source object to which data can be written, and
-from which data can be read, albeit using an API that is not compatible with
-Node.js streams.
-The following illustrates a simple example of a Duplex stream that buffers
-incoming written data via the [Writable][] interface that is read back out
-via the [Readable][] interface.
-```js
-const Duplex = require('stream').Duplex;
-const kSource = Symbol('source');
-class MyDuplex extends Duplex {
-  constructor(source, options) {
-    super(options);
-    this[kSource] = source;
-  }
-  _write(chunk, encoding, callback) {
-    // The underlying source only deals with strings
-    if (Buffer.isBuffer(chunk))
-      chunk = chunk.toString(encoding);
-    this[kSource].writeSomeData(chunk, encoding);
-    callback();
-  }
-  _read(size) {
-    this[kSource].fetchSomeData(size, (data, encoding) => {
-      this.push(Buffer.from(data, encoding));
-    });
-  }
-}
-```
-The most important aspect of a Duplex stream is that the Readable and Writable
-sides operate independently of one another despite co-existing within a single
-object instance.
-#### Object Mode Duplex Streams
-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
-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.
-```js
-const Transform = require('stream').Transform;
-// All Transform streams are also Duplex Streams
-const myTransform = new Transform({
-  writableObjectMode: true,
-  transform(chunk, encoding, callback) {
-    // Coerce the chunk to a number if necessary
-    chunk |= 0;
-    // Transform the chunk into something else.
-    const data = chunk.toString(16);
-    // Push the data onto the readable queue.
-    callback(null, '0'.repeat(data.length % 2) + data);
-  }
-});
-myTransform.setEncoding('ascii');
-myTransform.on('data', (chunk) => console.log(chunk));
-myTransform.write(1);
-  // Prints: 01
-myTransform.write(10);
-  // Prints: 0a
-myTransform.write(100);
-  // Prints: 64
-```
-### Implementing a Transform Stream
-A [Transform][] stream is a [Duplex][] stream where the output is computed
-in some way from the input. Examples include [zlib][] streams or [crypto][]
-streams that compress, encrypt, or decrypt data.
-*Note*: There is no requirement that the output be the same size as the input,
-the same number of chunks, or arrive at the same time. For example, a
-Hash stream will only ever have a single chunk of output which is
-provided when the input is ended. A `zlib` stream will produce output
-that is either much smaller or much larger than its input.
-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* also implement
-the [`transform._flush()`][stream-_flush] method.
-*Note*: Care must be taken when using Transform streams in that data written
-to the stream can cause the Writable side of the stream to become paused if
-the output on the Readable side is not consumed.
-#### new stream.Transform([options])
-* `options` {Object} Passed to both Writable and Readable
-  constructors. Also has the following fields:
-  * `transform` {Function} Implementation for the
-    [`stream._transform()`][stream-_transform] method.
-  * `flush` {Function} Implementation for the [`stream._flush()`][stream-_flush]
-    method.
-For example:
-```js
-const Transform = require('stream').Transform;
-class MyTransform extends Transform {
-  constructor(options) {
-    super(options);
-  }
-}
-```
-Or, when using pre-ES6 style constructors:
-```js
-const Transform = require('stream').Transform;
-const util = require('util');
-function MyTransform(options) {
-  if (!(this instanceof MyTransform))
-    return new MyTransform(options);
-  Transform.call(this, options);
-}
-util.inherits(MyTransform, Transform);
-```
-Or, using the Simplified Constructor approach:
-```js
-const Transform = require('stream').Transform;
-const myTransform = new Transform({
-  transform(chunk, encoding, callback) {
-    // ...
-  }
-});
-```
-#### Events: 'finish' and 'end'
-The [`'finish'`][] and [`'end'`][] events are from the `stream.Writable`
-and `stream.Readable` classes, respectively. The `'finish'` event is emitted
-after [`stream.end()`][stream-end] is called and all chunks have been processed
-by [`stream._transform()`][stream-_transform]. The `'end'` event is emitted
-after all data has been output, which occurs after the callback in
-[`transform._flush()`][stream-_flush] has been called.
-#### transform.\_flush(callback)
-* `callback` {Function} A callback function (optionally with an error
-  argument) to be called when remaining data has been flushed.
-*Note*: **This function MUST NOT be called by application code directly.** It
-should be implemented by child classes, and called only by the internal Readable
-class methods only.
-In some cases, a transform operation may need to emit an additional bit of
-data at the end of the stream. For example, a `zlib` compression stream will
-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()`
-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.
-Within the `transform._flush()` implementation, the `readable.push()` method
-may be called zero or more times, as appropriate. The `callback` function must
-be called when the flush operation is complete.
-The `transform._flush()` method is prefixed with an underscore because it is
-internal to the class that defines it, and should never be called directly by
-user programs.
-#### transform.\_transform(chunk, encoding, callback)
-* `chunk` {Buffer|String} The chunk to be transformed. Will **always**
-  be a buffer unless the `decodeStrings` option was set to `false`.
-* `encoding` {String} If the chunk is a string, then this is the
-  encoding type. If chunk is a buffer, then this is the special
-  value - 'buffer', ignore it in this case.
-* `callback` {Function} A callback function (optionally with an error
-  argument and data) to be called after the supplied `chunk` has been
-  processed.
-*Note*: **This function MUST NOT be called by application code directly.** It
-should be implemented by child classes, and called only by the internal Readable
-class methods only.
-All Transform stream implementations must provide a `_transform()`
-method to accept input and produce output. The `transform._transform()`
-implementation handles the bytes being written, computes an output, then passes
-that output off to the readable portion using the `readable.push()` method.
-The `transform.push()` method may be called zero or more times to generate
-output from a single input chunk, depending on how much is to be output
-as a result of the chunk.
-It is possible that no output is generated from any given chunk of input data.
-The `callback` function must be called only when the current chunk is completely
-consumed. The first argument passed to the `callback` must be an `Error` object
-if an error occurred while processing the input or `null` otherwise. If a second
-argument is passed to the `callback`, it will be forwarded on to the
-`readable.push()` method. In other words the following are equivalent:
-```js
-transform.prototype._transform = function (data, encoding, callback) {
-  this.push(data);
-  callback();
-};
-transform.prototype._transform = function (data, encoding, callback) {
-  callback(null, data);
-};
-```
-The `transform._transform()` method is prefixed with an underscore because it
-is internal to the class that defines it, and should never be called directly by
-user programs.
-#### Class: stream.PassThrough
-The `stream.PassThrough` class is a trivial implementation of a [Transform][]
-stream that simply passes the input bytes across to the output. Its purpose is
-primarily for examples and testing, but there are some use cases where
-`stream.PassThrough` is useful as a building block for novel sorts of streams.
-## Additional Notes
-<!--type=misc-->
-### Compatibility with Older Node.js Versions
-<!--type=misc-->
-In versions of Node.js prior to v0.10, the Readable stream interface was
-simpler, but also less powerful and less useful.
-* Rather than waiting for calls the [`stream.read()`][stream-read] method,
-  [`'data'`][] events would begin emitting immediately. Applications that
-  would need to perform some amount of work to decide how to handle data
-  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*.
-In Node.js v0.10, the [Readable][] class was added. For backwards compatibility
-with older Node.js programs, Readable streams switch into "flowing mode" when a
-[`'data'`][] event handler is added, or when the
-[`stream.resume()`][stream-resume] method is called. The effect is that, even
-when not using the new [`stream.read()`][stream-read] method and
-[`'readable'`][] event, it is no longer necessary to worry about losing
-[`'data'`][] chunks.
-While most applications will continue to function normally, this introduces an
-edge case in the following conditions:
-* No [`'data'`][] event listener is added.
-* The [`stream.resume()`][stream-resume] method is never called.
-* The stream is not piped to any writable destination.
-For example, consider the following code:
-```js
-// WARNING!  BROKEN!
-net.createServer((socket) => {
-  // we add an 'end' method, but never consume the data
-  socket.on('end', () => {
-    // It will never get here.
-    socket.end('The message was received but was not processed.\n');
-  });
-}).listen(1337);
-```
-In versions of Node.js prior to v0.10, the incoming message data would be
-simply discarded. However, in Node.js v0.10 and beyond, the socket remains
-paused forever.
-The workaround in this situation is to call the
-[`stream.resume()`][stream-resume] method to begin the flow of data:
-```js
-// Workaround
-net.createServer((socket) => {
-  socket.on('end', () => {
-    socket.end('The message was received but was not processed.\n');
-  });
-  // start the flow of data, discarding it.
-  socket.resume();
-}).listen(1337);
-```
-In addition to new Readable streams switching into flowing mode,
-pre-v0.10 style streams can be wrapped in a Readable class using the
-[`readable.wrap()`][`stream.wrap()`] method.
-### `readable.read(0)`
-There are some cases where it is necessary to trigger a refresh of the
-underlying readable stream mechanisms, without actually consuming any
-data. In such cases, it is possible to call `readable.read(0)`, which will
-always return `null`.
-If the internal read buffer is below the `highWaterMark`, and the
-stream is not currently reading, then calling `stream.read(0)` will trigger
-a low-level [`stream._read()`][stream-_read] call.
-While most applications will almost never need to do this, there are
-situations within Node.js where this is done, particularly in the
-Readable stream class internals.
-### `readable.push('')`
-Use of `readable.push('')` is not recommended.
-Pushing a zero-byte string or `Buffer` to a stream that is not in 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.
-[`'data'`]: #stream_event_data
-[`'drain'`]: #stream_event_drain
-[`'end'`]: #stream_event_end
-[`'finish'`]: #stream_event_finish
-[`'readable'`]: #stream_event_readable
-[`buf.toString(encoding)`]: https://nodejs.org/docs/v6.3.1/api/buffer.html#buffer_buf_tostring_encoding_start_end
-[`EventEmitter`]: https://nodejs.org/docs/v6.3.1/api/events.html#events_class_eventemitter
-[`process.stderr`]: https://nodejs.org/docs/v6.3.1/api/process.html#process_process_stderr
-[`process.stdin`]: https://nodejs.org/docs/v6.3.1/api/process.html#process_process_stdin
-[`process.stdout`]: https://nodejs.org/docs/v6.3.1/api/process.html#process_process_stdout
-[`stream.cork()`]: #stream_writable_cork
-[`stream.pipe()`]: #stream_readable_pipe_destination_options
-[`stream.uncork()`]: #stream_writable_uncork
-[`stream.unpipe()`]: #stream_readable_unpipe_destination
-[`stream.wrap()`]: #stream_readable_wrap_stream
-[`tls.CryptoStream`]: https://nodejs.org/docs/v6.3.1/api/tls.html#tls_class_cryptostream
-[API for Stream Consumers]: #stream_api_for_stream_consumers
-[API for Stream Implementers]: #stream_api_for_stream_implementers
-[child process stdin]: https://nodejs.org/docs/v6.3.1/api/child_process.html#child_process_child_stdin
-[child process stdout and stderr]: https://nodejs.org/docs/v6.3.1/api/child_process.html#child_process_child_stdout
-[Compatibility]: #stream_compatibility_with_older_node_js_versions
-[crypto]: crypto.html
-[Duplex]: #stream_class_stream_duplex
-[fs read streams]: https://nodejs.org/docs/v6.3.1/api/fs.html#fs_class_fs_readstream
-[fs write streams]: https://nodejs.org/docs/v6.3.1/api/fs.html#fs_class_fs_writestream
-[`fs.createReadStream()`]: https://nodejs.org/docs/v6.3.1/api/fs.html#fs_fs_createreadstream_path_options
-[`fs.createWriteStream()`]: https://nodejs.org/docs/v6.3.1/api/fs.html#fs_fs_createwritestream_path_options
-[`net.Socket`]: https://nodejs.org/docs/v6.3.1/api/net.html#net_class_net_socket
-[`zlib.createDeflate()`]: https://nodejs.org/docs/v6.3.1/api/zlib.html#zlib_zlib_createdeflate_options
-[HTTP requests, on the client]: https://nodejs.org/docs/v6.3.1/api/http.html#http_class_http_clientrequest
-[HTTP responses, on the server]: https://nodejs.org/docs/v6.3.1/api/http.html#http_class_http_serverresponse
-[http-incoming-message]: https://nodejs.org/docs/v6.3.1/api/http.html#http_class_http_incomingmessage
-[Object mode]: #stream_object_mode
-[Readable]: #stream_class_stream_readable
-[SimpleProtocol v2]: #stream_example_simpleprotocol_parser_v2
-[stream-_flush]: #stream_transform_flush_callback
-[stream-_read]: #stream_readable_read_size_1
-[stream-_transform]: #stream_transform_transform_chunk_encoding_callback
-[stream-_write]: #stream_writable_write_chunk_encoding_callback_1
-[stream-_writev]: #stream_writable_writev_chunks_callback
-[stream-end]: #stream_writable_end_chunk_encoding_callback
-[stream-pause]: #stream_readable_pause
-[stream-push]: #stream_readable_push_chunk_encoding
-[stream-read]: #stream_readable_read_size
-[stream-resume]: #stream_readable_resume
-[stream-write]: #stream_writable_write_chunk_encoding_callback
-[TCP sockets]: https://nodejs.org/docs/v6.3.1/api/net.html#net_class_net_socket
-[Transform]: #stream_class_stream_transform
-[Writable]: #stream_class_stream_writable
-[zlib]: zlib.html