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

doc: change "Node.js style cb" to "error-first cb"

Browse Source 
Change the awkward "Node.js style callback" phrasing to the more
informative "error-first callback."

PR-URL: https://github.com/nodejs/node/pull/17638
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
This commit is contained in:
Ram Goli 2017-12-12 23:46:25 +00:00 committed by Anatoli Papirovski
parent efffcc262c
commit 3db136a74a
No known key found for this signature in database
GPG Key ID: 614E2E1ABEB4B2C0
2 changed files with 20 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/api/errors.md
View File

@ -128,21 +128,22 @@ they are thrown *after* the calling code has already exited.
Developers must refer to the documentation for each method to determine Developers must refer to the documentation for each method to determine
exactly how errors raised by those methods are propagated. exactly how errors raised by those methods are propagated.
### Node.js style callbacks ### Error-first callbacks
<!--type=misc--> <!--type=misc-->
Most asynchronous methods exposed by the Node.js core API follow an idiomatic Most asynchronous methods exposed by the Node.js core API follow an idiomatic
pattern referred to as a "Node.js style callback". With this pattern, a pattern referred to as an _error-first callback_ (sometimes referred to as
callback function is passed to the method as an argument. When the operation a _Node.js style callback_). With this pattern, a callback function is passed
either completes or an error is raised, the callback function is called with to the method as an argument. When the operation either completes or an error
the Error object (if any) passed as the first argument. If no error was raised, is raised, the callback function is called with
the first argument will be passed as `null`. the Error object (if any) passed as the first argument. If no error was
raised, the first argument will be passed as `null`.
```js ```js
const fs = require('fs'); const fs = require('fs');
function nodeStyleCallback(err, data) { function errorFirstCallback(err, data) {
if (err) { if (err) {
console.error('There was an error', err); console.error('There was an error', err);
return; return;
@ -150,13 +151,13 @@ function nodeStyleCallback(err, data) {
console.log(data); console.log(data);
} }
fs.readFile('/some/file/that/does-not-exist', nodeStyleCallback); fs.readFile('/some/file/that/does-not-exist', errorFirstCallback);
fs.readFile('/some/file/that/does-exist', nodeStyleCallback); fs.readFile('/some/file/that/does-exist', errorFirstCallback);
``` ```
The JavaScript `try / catch` mechanism **cannot** be used to intercept errors The JavaScript `try / catch` mechanism **cannot** be used to intercept errors
generated by asynchronous APIs. A common mistake for beginners is to try to generated by asynchronous APIs. A common mistake for beginners is to try to
use `throw` inside a Node.js style callback: use `throw` inside an error-first callback:
```js ```js
// THIS WILL NOT WORK: // THIS WILL NOT WORK:

17
doc/api/util.md
View File

@ -21,9 +21,10 @@ added: v8.2.0
* Returns: {Function} a callback style function * Returns: {Function} a callback style function
Takes an `async` function (or a function that returns a Promise) and returns a Takes an `async` function (or a function that returns a Promise) and returns a
function following the Node.js error first callback style. In the callback, the function following the error-first callback style, i.e. taking
first argument will be the rejection reason (or `null` if the Promise resolved), a `(err, value) => ...` callback as the last argument. In the callback, the
and the second argument will be the resolved value. first argument will be the rejection reason (or `null` if the Promise
resolved), and the second argument will be the resolved value.
For example: For example:
@ -530,8 +531,8 @@ added: v8.0.0
* `original` {Function} * `original` {Function}
* Returns: {Function} * Returns: {Function}
Takes a function following the common Node.js callback style, i.e. taking a Takes a function following the common error-first callback style, i.e. taking
`(err, value) => ...` callback as the last argument, and returns a version a `(err, value) => ...` callback as the last argument, and returns a version
that returns promises. that returns promises.
For example: For example:
@ -567,9 +568,9 @@ will return its value, see [Custom promisified functions][].
`promisify()` assumes that `original` is a function taking a callback as its `promisify()` assumes that `original` is a function taking a callback as its
final argument in all cases. If `original` is not a function, `promisify()` final argument in all cases. If `original` is not a function, `promisify()`
will throw an error. If `original` is a function but its last argument is not a will throw an error. If `original` is a function but its last argument is not
Node.js style callback, it will still be passed a Node.js style callback an error-first callback, it will still be passed an error-first
as its last argument. callback as its last argument.
### Custom promisified functions ### Custom promisified functions