1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: reword stream docs to clarify that decodeStrings encodes strings

Browse Source 
I was implementing a Writable stream and misunderstood `decodeStrings`
to mean 'will decode `Buffer`s into `string`s before calling `_write`'.
This change adds a little more detail to the description of
`decodeStrings` to clarify its effect on a Writable stream & what gets
passed to `_write`.

Changing the name of the option to `encodeStrings` would make it much
easier to understand, but the name was chosen in 2012 and the option
used in many projects (22k mentions of 'decodeStringsr in JS projects in
GitHub). Deprecating the old name & rolling out a replacement is beyond
my capabilities as a first-time contributor.

PR-URL: https://github.com/nodejs/node/pull/25468
Fixes: https://github.com/nodejs/node/issues/25464
Reviewed-By: Anna Henningsen <anna@addaleax.net>
This commit is contained in:
Daniel George Holz 2019-01-12 22:35:34 +00:00 committed by Vse Mozhet Byt
parent 5571c0ddeb
commit fac11b05b7
1 changed files with 16 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/api/stream.md
View File

@ -1537,10 +1537,12 @@ changes:
* `highWaterMark` {number} Buffer level when * `highWaterMark` {number} Buffer level when
[`stream.write()`][stream-write] starts returning `false`. **Default:** [`stream.write()`][stream-write] starts returning `false`. **Default:**
`16384` (16kb), or `16` for `objectMode` streams. `16384` (16kb), or `16` for `objectMode` streams.
* `decodeStrings` {boolean} Whether or not to encode strings as * `decodeStrings` {boolean} Whether to encode `string`s passed to
`Buffer`s before passing them to [`stream._write()`][stream-_write], [`stream.write()`][stream-write] to `Buffer`s (with the encoding
using the encoding specified in the [`stream.write()`][stream-write] call. specified in the [`stream.write()`][stream-write] call) before passing
**Default:** `true`. them to [`stream._write()`][stream-_write]. Other types of data are not
converted (i.e. `Buffer`s are not decoded into `string`s). Setting to
false will prevent `string`s from being converted. **Default:** `true`.
* `defaultEncoding` {string} The default encoding that is used when no * `defaultEncoding` {string} The default encoding that is used when no
encoding is specified as an argument to [`stream.write()`][stream-write]. encoding is specified as an argument to [`stream.write()`][stream-write].
**Default:** `'utf8'`. **Default:** `'utf8'`.
@ -1606,9 +1608,11 @@ const myWritable = new Writable({
#### writable.\_write(chunk, encoding, callback) #### writable.\_write(chunk, encoding, callback)
* `chunk` {Buffer|string|any} The chunk to be written. Will **always** * `chunk` {Buffer|string|any} The `Buffer` to be written, converted from the
be a buffer unless the `decodeStrings` option was set to `false` `string` passed to [`stream.write()`][stream-write]. If the stream's
or the stream is operating in object mode. `decodeStrings` option is `false` or the stream is operating in object mode,
the chunk will not be converted & will be whatever was passed to
[`stream.write()`][stream-write].
* `encoding` {string} If the chunk is a string, then `encoding` is the * `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 character encoding of that string. If chunk is a `Buffer`, or if the
stream is operating in object mode, `encoding` may be ignored. stream is operating in object mode, `encoding` may be ignored.
@ -2301,9 +2305,11 @@ user programs.
#### transform.\_transform(chunk, encoding, callback) #### transform.\_transform(chunk, encoding, callback)
* `chunk` {Buffer|string|any} The chunk to be transformed. Will **always** * `chunk` {Buffer|string|any} The `Buffer` to be transformed, converted from
be a buffer unless the `decodeStrings` option was set to `false` the `string` passed to [`stream.write()`][stream-write]. If the stream's
or the stream is operating in object mode. `decodeStrings` option is `false` or the stream is operating in object mode,
the chunk will not be converted & will be whatever was passed to
[`stream.write()`][stream-write].
* `encoding` {string} If the chunk is a string, then this is the * `encoding` {string} If the chunk is a string, then this is the
encoding type. If chunk is a buffer, then this is the special encoding type. If chunk is a buffer, then this is the special
value - 'buffer', ignore it in this case. value - 'buffer', ignore it in this case.