Skip to content

Commit

Permalink
doc: change Node.js style to error-first style
Browse files Browse the repository at this point in the history
We change the awkward "Node.js style callback" phrasing to the
more informative "error-first style callback," which is more
in line with its usage

Refs: nodejs#17593 (comment)
  • Loading branch information
ramsgoli committed Dec 13, 2017
1 parent 04ae486 commit 324b87b
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 10 deletions.
12 changes: 6 additions & 6 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,12 +128,12 @@ they are thrown *after* the calling code has already exited.
Developers must refer to the documentation for each method to determine
exactly how errors raised by those methods are propagated.

### Node.js style callbacks
### Error-first style callbacks

<!--type=misc-->

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 style callback". With this pattern, a
callback function is passed to the method as an argument. When the operation
either completes or an error is raised, the callback function is called with
the Error object (if any) passed as the first argument. If no error was raised,
Expand All @@ -142,21 +142,21 @@ the first argument will be passed as `null`.
```js
const fs = require('fs');

function nodeStyleCallback(err, data) {
function errorFirstStyleCallback(err, data) {
if (err) {
console.error('There was an error', err);
return;
}
console.log(data);
}

fs.readFile('/some/file/that/does-not-exist', nodeStyleCallback);
fs.readFile('/some/file/that/does-exist', nodeStyleCallback);
fs.readFile('/some/file/that/does-not-exist', errorFirstStyleCallback);
fs.readFile('/some/file/that/does-exist', errorFirstStyleCallback);
```

The JavaScript `try / catch` mechanism **cannot** be used to intercept errors
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 style callback:

```js
// THIS WILL NOT WORK:
Expand Down
8 changes: 4 additions & 4 deletions doc/api/util.md
Original file line number Diff line number Diff line change
Expand Up @@ -517,7 +517,7 @@ added: v8.0.0
* `original` {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 style callback, i.e. taking a
`(err, value) => ...` callback as the last argument, and returns a version
that returns promises.

Expand Down Expand Up @@ -554,9 +554,9 @@ will return its value, see [Custom promisified functions][].

`promisify()` assumes that `original` is a function taking a callback as its
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
Node.js style callback, it will still be passed a Node.js style callback
as its last argument.
will throw an error. If `original` is a function but its last argument is not
an error-first style callback, it will still be passed an error-first style
callback as its last argument.

### Custom promisified functions

Expand Down

0 comments on commit 324b87b

Please sign in to comment.