Skip to content
51 changes: 48 additions & 3 deletions doc/api/stream.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down Expand Up @@ -205,10 +205,16 @@ myStream.end('done writing data');
```

#### Class: stream.Writable
<!-- YAML
added: v0.3.0
-->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0.9.4


<!--type=class-->

##### Event: 'close'
<!-- YAML
added: v0.3.1
-->

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
Expand All @@ -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'
<!-- YAML
added: v0.3.0
-->

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
Expand All @@ -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;
Expand All @@ -251,6 +260,9 @@ function writeOneMillionTimes(writer, data, encoding, callback) {
```

##### Event: 'error'
<!-- YAML
added: v0.3.1
-->

* {Error}

Expand All @@ -276,6 +288,9 @@ writer.on('finish', () => {
```

##### Event: 'pipe'
<!-- YAML
added: v0.3.0
-->

* `src` {stream.Readable} source stream that is piping to this writable

Expand All @@ -293,6 +308,9 @@ reader.pipe(writer);
```

##### Event: 'unpipe'
<!-- YAML
added: v0.9.4
-->

* `src` {[Readable][] Stream} The source stream that
[unpiped][`stream.unpipe()`] this writable
Expand Down Expand Up @@ -391,6 +409,9 @@ process.nextTick(() => {
```

##### 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
Expand All @@ -413,6 +434,9 @@ should be paused until the `'drain'` event is emitted.
A Writable stream in object mode will always ignore the `encoding` argument.

### Readable Streams
<!-- YAML
added: v0.3.0
-->

Readable streams are an abstraction for a *source* from which data is
consumed.
Expand Down Expand Up @@ -520,6 +544,9 @@ use the [`EventEmitter`][] and `readable.pause()`/`readable.resume()` APIs.
<!--type=class-->

##### Event: 'close'
<!-- YAML
added: v0.3.1
-->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should be an added: tag for the stream.Readable class, too, and since what is documented here is what is accessible via stream.Readable, I’d set all of these to 0.9.4, too.


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
Expand All @@ -528,6 +555,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'
<!-- YAML
added: v0.3.1
-->

* `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`.
Expand Down Expand Up @@ -558,6 +588,9 @@ readable.on('data', (chunk) => {
```

##### Event: 'end'
<!-- YAML
added: v0.3.1
-->

The `'end'` event is emitted when there is no more data to be consumed from
the stream.
Expand All @@ -578,6 +611,9 @@ readable.on('end', () => {
```

##### Event: 'error'
<!-- YAML
added: v0.3.1
-->

* {Error}

Expand Down Expand Up @@ -651,6 +687,9 @@ readable.isPaused() // === false
```

##### readable.pause()
<!-- YAML
added: v0.3.1
-->

* Return: `this`

Expand Down Expand Up @@ -774,6 +813,9 @@ event will also be emitted.
event has been emitted will return `null`. No runtime error will be raised.

##### readable.resume()
<!-- YAML
added: v0.3.1
-->

* Return: `this`

Expand All @@ -793,6 +835,9 @@ getReadableStreamSomehow()
```

##### readable.setEncoding(encoding)
<!-- YAML
added: v0.3.1
-->

* `encoding` {String} The encoding to use.
* Return: `this`
Expand Down Expand Up @@ -1579,7 +1624,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.
Expand Down