The current documentation for writable.write only specifies that the
callback is called "once the data has been fully handled". It is
ambiguous whether this means "successfully handled" and, if so,
whether the callback is called if the data can not be successfully
handled (i.e. an error occurs).
The ambiguity is not only in the documentation. The stream class
implementations differ on this point. stream.Writable invokes the
callback with any errors that occur during parameter checking or
during calls to _write. However, not all classes return all errors
to _write. zlib.Zlib does pass argument and state errors to the
_write (_transform) callback, but does not pass data errors.
http.OutgoingMessage passes argument type errors and some other types
of errors, but not all.
This inconsistency is behind issue #1746 and, I suspect, other issues
in client code which passes a callback to write.
This commit takes no position on whether the callback error behavior
should changed, but simply attempts to document the current behavior
in a way that is open to changes so that users are not caught by
surprise.
PR-URL: https://github.com/nodejs/node/pull/4810
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremy Whitlock <jwhitlock@apache.org>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
`readable.setEncoding(null)` - may be the most preferable way to proxy
a binary data without any encoding/decoding overhead
PR-URL: https://github.com/nodejs/node/pull/5155
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Fixes several type references in the docs so that the
doc html gen tool that parses them can put the correct
links in.
Changes css styling for the generated type links.
PR-URL: https://github.com/nodejs/node/pull/4741
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Chris Dickinson <chris@neversaw.us>
Reviewed-By: Roman Reiss <me@silverwind.io>
This commit replaces multiple usages of `function(){}` with ES2015
arrow functions in places it was forgotten earlier. The goal is to
make the docs more consistent since other functions were already
replaced with ES2015 arrows.
In addition, it fixes invalid syntax in modules.markdown to valid
syntax as well as remove `var self = this` pattern usages in the code
where they are now possible to avoid through arrow functions.
PR-URL: https://github.com/nodejs/node/pull/4832
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/4805
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
This changes the code blocks from 4-space indentation to ``` fences for
better syntax highlighting and future linting support. Minor On-the-fly
changes for typos and highlight breaking markdown have been made.
JSON-Style objects have been changed so their closing bracket is
on the same line as the opening one.
Known issues:
* Not every JSON / object notation has been improved. Should
make another run for this.
* Some example functions break hightlighting due to various
combinations of brackets. However changing them means leaving
the code style.
Fixes: https://github.com/nodejs/node/issues/4726
PR-URL: https://github.com/nodejs/node/pull/4733
Reviewed-By: Roman Reiss <me@silverwind.io>
Add a bytesRead property for readable is
useful in some use cases.
When user want know how many bytes read of
readable, need to caculate it in userland.
If encoding is specificed, get the value is
very slowly.
PR-URL: https://github.com/nodejs/node/pull/4372
Reviewed-By: Trevor Norris <trev.norris@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
The last sentence of the explanation for the first stream section
seemed a bit confusing. I tried to change the sentence to clarify it.
Additionally, the sections were turned into a numbered list to be more
clear about which section is being described, and improve readability.
PR-URL: https://github.com/nodejs/node/pull/4234
Reviewed-By: James M Snell <jasnell@gmail.com>
The docs were recently refactored, and some "above" and "below"
references were no longer accurate. This commit removes many
such references, and replaces others with links.
PR-URL: https://github.com/nodejs/node/pull/4499
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
* Use single quotes consistently
* Modernize examples to use template strings and arrow funcs
* Fix a few typos
* Example edits for consistency
PR-URL: https://github.com/nodejs/node/pull/4282
Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
* add backticks around names
* add single quotes around event names
* add parenthesis after function names
* add internal links between different sections
* add external links to MDN for some JavaScript references
* sort the link definitions alphabetically
PR-URL: https://github.com/nodejs/node/pull/4054
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Moved all the URLs in API docs to the bottom of the files as
reference-style links.
PR-URL: https://github.com/nodejs/node/pull/3845
Reviewed-By: James M Snell <jasnell@gmail.com>
The examples for implementing the simplified constructor API
was missing some details on its correct usages.
PR-URL: https://github.com/nodejs/node/pull/3602
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chris Dickinson <chris@neversaw.us>
Reorders, with no contextual changes, the stream documentation
alphabetically.
PR-URL: https://github.com/nodejs/node/pull/3662
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
`process.stdout` always blocks as of
20176a9841
`WritableState.buffer` is `getBuffer()` as of
91586661c9
PR-URL: https://github.com/nodejs/node/pull/2549
Reviewed-By: Alexis Campailla <orangemocha@nodejs.org>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Per feedback from @thefourtheye: (a) improve word on the
description of the `close` event in stream.markdown and
(b) remove `[module section]: modules.html` from
globals.markdown
Reviewed By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/2378
This commit replaces instances of io.js with Node.js, based on the
recent convergence. There are some remaining instances of io.js,
related to build and the installer.
Fixes: https://github.com/nodejs/node/issues/2361
PR-URL: https://github.com/nodejs/node/pull/2367
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: João Reis <reis@janeasystems.com>
This simplifies the stability index to 4 levels:
0 - deprecated
1 - experimental / feature-flagged
2 - stable
3 - locked
Domains has been downgraded to deprecated, assert has been
downgraded to stable. Timers and Module remain locked. All
other APIs are now stable.
PR-URL: https://github.com/iojs/io.js/pull/943
Fixes: https://github.com/iojs/io.js/issues/930
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Vladimir Kurchatkin <vladimir.kurchatkin@gmail.com>
Setting the default encoding for a writable stream does
not return a boolean (true if successful or false if not)
as the docs indicate. Instead, if the operation is successful
nothing is returned and the method throws an error when
something goes wrong.
This stems from a contribution that was tweaked but the
docs were never updated accordingly.
PR-URL: https://github.com/iojs/io.js/pull/502
Reviewed-By: Rod Vagg <rod@vagg.org>
Slightly fix and supplement the documentation for Writable#write and
Transform#transform methods. Make it more consistent. Mention passing
'buffer' as an encoding param in case chunk is a Buffer.
PR: https://github.com/iojs/io.js/pull/142
Reviewed-by: Bert Belder <bertbelder@gmail.com>
Reviewed-by: Rod Vagg <rod@vagg.org>
Expands the paragraph in the transform stream
implementation docs about the callback that is passed
to the _transform method to include details about how
two arguments may be passed, error and data. A code
example is also included.
Reviewed-by: Fedor Indutny <fedor@indutny.com>
Cherry-picked-from: c8e0bdd7cf
Currently there's an example using http.ServerResponse stream, which
has a known bug and will not throw an error while writing after end().
Changed to a writable stream from fs which behaves as expected.
Fixes https://github.com/joyent/node/issues/8814.
PR-URL: https://github.com/iojs/io.js/pull/155
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Brendan Ashworth <squirrelslikeacorns@gmail.com>
The parameter parser specifically looked for the old bracket syntax.
This generated a lot of warnings when building the docs. Those warnings
have been fixed by changing the parsing logic.
Signed-off-by: Trevor Norris <trev.norris@gmail.com>
Documentation incorrectly used bracket notation for optional parameters.
This caused inconsistencies in usage because of examples like the
following:
fs.write(fd, data[, position[, encoding]], callback)
This simply fixes all uses of bracket notation in documentation.
Signed-off-by: Trevor Norris <trev.norris@gmail.com>
Reviewed-by: Fedor Indutny <fedor@indutny.com>
net Sockets were calling read(0) to start reading, without
checking to see if they were paused first. This would result
in paused Socket objects keeping the event loop alive.
Fixes #8200
Reviewed-by: Trevor Norris <trev.norris@gmail.com>
Adds a section to the transform stream docs to clarify the
difference between the `end` event and the `finish` events.
Also clarifies the wording on the `end` event.
This commit introduces `readableObjectMode` and
`writableObjectMode` options for Duplex streams.
This can be used mostly to make parsers and
serializers with Transform streams.
Also the docs section about stream state objects
is removed, because it is not relevant anymore.
The example from the section is remade to show
new options.
fixes #6284
Signed-off-by: Timothy J Fontaine <tjfontaine@gmail.com>
