Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add added: information for stream #7287

Closed
wants to merge 12 commits into from
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