The doc specified that writable.write() was advisory only. However,
ignoring that value might lead to memory leaks. This PR specifies that
behavior. Moreover, it adds an example on how to listen for the 'drain'
event correctly.
See: f347dad0b7
PR-URL: https://github.com/nodejs/node/pull/10631
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
When decodeStrings is false and given data is string, _write() function
receives the string data not `Buffer`.
PR-URL: https://github.com/nodejs/node/pull/10411
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Currently, some of the docs use different indentation for comments
in the code examples. This commit makes the indentation consistent
by putting the comments at the beginning of the line (really no
indentation that is).
PR-URL: https://github.com/nodejs/node/pull/9518
Reviewed-By: Teddy Katz <teddy.katz@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
For consistency, changed all `Return:` to `Returns:` in the API docs.
PR-URL: https://github.com/nodejs/node/pull/9554
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Sections:
- Introduction
- Orginization of this Document
- Object Mode
- Buffering
- API for Stream Implementers
PR-URL: https://github.com/nodejs/node/pull/9100
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Use `[Symbol.hasInstance]()` to return `true` when asking for
`new Duplex() instanceof Writable`.
PR-URL: https://github.com/nodejs/node/pull/8834
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Calvin Metcalf <calvin.metcalf@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/8370
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Prince John Wesley <princejohnwesley@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/8326
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Brian White <mscdex@mscdex.net>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
In example parseHeader, stream listen **readable** event,
if call stream.unshift(buf) before stream.removeListener('readable',
onReadable), readable event will be emited before removeListener,
so callback will not been called correctlly.
After change to
```js
stream.removeListener('error', callback);
stream.removeListener('readable', onReadable);
if (buf.length)
stream.unshift(buf);
```
It solves this problem.
PR-URL: https://github.com/nodejs/node/pull/8200
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Const is block scoped.
PR-URL: https://github.com/nodejs/node/pull/8124
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Use blockquotes instead of code blocks for stability markers in
the docs. Doing that:
- Makes the makers appear correctly when viewed e.g. on github.
- Allows remark-lint rules like `no-undefined-references` to work
properly (https://github.com/nodejs/node/pull/7729).
PR-URL: https://github.com/nodejs/node/pull/7757
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Adds missing semicolons, removes extra white space, and properly indents
various code snippets in the documentation.
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: targos - Michaël Zasso <mic.besace@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/7745
Fix small typo in Buffering section of stream doc.
PR-URL: https://github.com/nodejs/node/pull/7738
Reviewed-By: Brian White <mscdex@mscdex.net>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
* Fix markdown code sample in releases.md, it was <a id="x.y.x></a>"
* Fix some markdown errors, e.g. in changelogs
* Fix broken defs links, e.g. in domain-postmortem.md
* Fix other broken refs, by addaleax
* Add links to some defs that were present but not linked to
* Remove dead defs
* Move defs to the bottom (one file affected)
* Add language indicators to all code blocks, using `txt` when no
specific language could be chosen
* Some minor formatting changes (spaces, ident, headings)
PR-URL: https://github.com/nodejs/node/pull/7637
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Roman Reiss <me@silverwind.io>
In prose, always surround `null`-as-a-value in backticks.
PR-URL: https://github.com/nodejs/node/pull/6986
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Majoring restructuring and update for streams doc.
This is the first step of multiple to updating and
correcting the streams documentation.
PR-URL: https://github.com/nodejs/node/pull/6947
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Add 'close' event to doc/api/fs.md --> fs.ReadStream
Add 'close' event to doc/api/fs.md --> fs.WriteStream
Add 'close event to doc/api/stream.md --> stream.Writable
From squashed history:
Add 'close' event to stream.Writable per Issue #6484
Add #### prefix to Event: 'close' and backticks to 'close'
similar to stream.Readable event: 'close' section
Add more specifics to 'close' events for fs.ReadStream
and fs.WriteStream
Fix/Changed 'close' event from 'fs.ReadStream' to 'fs.WriteStream'
wrapped long lines at 80 chars, reworded
per Issue #6484
including the 'close' event as optional
add 'close' event as optional in stream.Readable
per issue #6484
doc: Add 'close' events to fs.ReadStream, 80char nit
Fixes: #6484
PR-URL: https://github.com/nodejs/node/pull/6499
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Let this function return `this` for parity with `readable.setEncoding()`.
PR-URL: https://github.com/nodejs/node/pull/5040
Fixes: https://github.com/nodejs/node/issues/5013
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Calvin Metcalf <calvin.metcalf@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Use new API of Buffer to developers in most documents.
PR-URL: https://github.com/nodejs/node/pull/6367
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
* doc: rename .markdown references in content
* doc: rename to .md in tools
* doc: rename to .md in CONTRIBUTING.md
PR-URL: https://github.com/nodejs/node/pull/4747
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: techjeffharris
Reviewed-By: Johan Bergström <bugs@bergstroem.nu>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
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>
Matteo Collina
Johannes Rieken
Fumiya KARASAWA
Tanuja-Sawant
Daniel Bevenius
Roman Reiss
Benji Marinacci
Anna Henningsen
Luigi Pinca
Mike Ralphson
Hubert Mine
Zwb
lazlojuly
Alex Perkins
Italo A. Casas
saadq
Kevin Donahue
Сковорода Никита Андреевич
vsemozhetbyt
Jesús Leganés Combarro "piranna
Rich Trott
James M Snell
Robert Jefe Lindstaedt
Jenna Vuong
Alexander Makarenko
Jackson Tian
Jackson Tian
Kevin Locke
Anton Andesen
Claudio Rodriguez
piepmatz
Benjamin Gruenbaum
cjihrig
Vitor Cortez
zoubin
Richard Sun
iamchenxin
jpersson
Bryan English
Tom Gallacher