diff --git a/doc/api/stream.md b/doc/api/stream.md index 6510dec5410114..8f8e73fc2ea7e0 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -544,6 +544,15 @@ added: v12.3.0 Getter for the property `objectMode` of a given `Writable` stream. +##### writable.writableReady + + +* {boolean} + +Is set to `true` immediately before the [`'ready'`][] event is emitted. + ##### writable.write(chunk[, encoding][, callback]) + +* {boolean} + +Is set to `true` immediately before the [`'ready'`][] event is emitted. + ##### readable.resume() + +* `options` {Object} Options passed to constructor. +* `callback` {Function} Call this function (optionally with an error + argument) when finished writing any remaining data. + +The `_construct()` method **must not** be called directly. It may be implemented +by child classes, and if so, will be called by the internal `Writable` +class methods only. + +This optional function will be called by the stream constructor, +delaying the `'ready'` event until `callback` is called. This is useful to +initalize state or asynchronously initialize resources before the stream +can be used. + +```js +const { Writable } = require('stream'); +const fs = require('fs'); + +class WriteStream extends Writable { + constructor(filename) { + super({ filename, autoDestroy: true }); + } + _construct({ filename }, callback) { + this.filename = filename; + this.fd = null; + fs.open(this.filename, (fd, err) => { + if (err) { + callback(err); + } else { + this.fd = fd; + callback(); + } + }); + } + _write(chunk, encoding, callback) { + fs.write(this.fd, chunk, callback); + } + _destroy(err, callback) { + if (this.fd) { + fs.close(this.fd, (er) => callback(er || err)); + } else { + callback(err); + } + } +} +``` + #### writable.\_write(chunk, encoding, callback) * `chunk` {Buffer|string|any} The `Buffer` to be written, converted from the @@ -1958,6 +2035,8 @@ changes: method. * `destroy` {Function} Implementation for the [`stream._destroy()`][readable-_destroy] method. + * `construct` {Function} Implementation for the + [`stream._construct()`][readable-_construct] method. * `autoDestroy` {boolean} Whether this stream should automatically call `.destroy()` on itself after ending. **Default:** `false`. @@ -2000,6 +2079,64 @@ const myReadable = new Readable({ }); ``` +#### readable.\_construct(options, callback) + + +* `options` {Object} Options passed to constructor. +* `callback` {Function} Call this function (optionally with an error + argument) when finished writing any remaining data. + +The `_construct()` method **must not** be called directly. It may be implemented +by child classes, and if so, will be called by the internal `Writable` +class methods only. + +This optional function will be called by the stream constructor, +delaying the `'ready'` event until `callback` is called. This is useful to +initalize state or asynchronously initialize resources before the stream +can be used. + +```js +const { Readable } = require('stream'); +const fs = require('fs'); + +class ReadStream extends Readable { + constructor(filename) { + super({ autoDestroy: true, filename }); + } + _construct({ filename }, callback) { + this.filename = filename; + this.fd = null; + fs.open(this.filename, (fd, err) => { + if (err) { + callback(err); + } else { + this.fd = fd; + callback(); + } + }); + } + _read(n) { + const buf = Buffer.alloc(n); + fs.read(this.fd, buf, 0, n, null, (err, bytesRead) => { + if (err) { + this.destroy(err); + } else { + this.push(bytesRead > 0 ? buf.slice(bytesRead) : null); + } + }); + } + _destroy(err, callback) { + if (this.fd) { + fs.close(this.fd, (er) => callback(er || err)); + } else { + callback(err); + } + } +} +``` + #### readable.\_read(size)