Skip to content

Commit 6215004

Browse files
ramsgoliMylesBorins
authored andcommitted
doc: change "Node.js style cb" to "error-first cb"
Change the awkward "Node.js style callback" phrasing to the more informative "error-first callback." PR-URL: #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>
1 parent 53b2a98 commit 6215004

File tree

2 files changed

+20
-18
lines changed

2 files changed

+20
-18
lines changed

doc/api/errors.md

+11-10
Original file line numberDiff line numberDiff line change
@@ -128,35 +128,36 @@ they are thrown *after* the calling code has already exited.
128128
Developers must refer to the documentation for each method to determine
129129
exactly how errors raised by those methods are propagated.
130130

131-
### Node.js style callbacks
131+
### Error-first callbacks
132132

133133
<!--type=misc-->
134134

135135
Most asynchronous methods exposed by the Node.js core API follow an idiomatic
136-
pattern referred to as a "Node.js style callback". With this pattern, a
137-
callback function is passed to the method as an argument. When the operation
138-
either completes or an error is raised, the callback function is called with
139-
the Error object (if any) passed as the first argument. If no error was raised,
140-
the first argument will be passed as `null`.
136+
pattern referred to as an _error-first callback_ (sometimes referred to as
137+
a _Node.js style callback_). With this pattern, a callback function is passed
138+
to the method as an argument. When the operation either completes or an error
139+
is raised, the callback function is called with
140+
the Error object (if any) passed as the first argument. If no error was
141+
raised, the first argument will be passed as `null`.
141142

142143
```js
143144
const fs = require('fs');
144145

145-
function nodeStyleCallback(err, data) {
146+
function errorFirstCallback(err, data) {
146147
if (err) {
147148
console.error('There was an error', err);
148149
return;
149150
}
150151
console.log(data);
151152
}
152153

153-
fs.readFile('/some/file/that/does-not-exist', nodeStyleCallback);
154-
fs.readFile('/some/file/that/does-exist', nodeStyleCallback);
154+
fs.readFile('/some/file/that/does-not-exist', errorFirstCallback);
155+
fs.readFile('/some/file/that/does-exist', errorFirstCallback);
155156
```
156157

157158
The JavaScript `try / catch` mechanism **cannot** be used to intercept errors
158159
generated by asynchronous APIs. A common mistake for beginners is to try to
159-
use `throw` inside a Node.js style callback:
160+
use `throw` inside an error-first callback:
160161

161162
```js
162163
// THIS WILL NOT WORK:

doc/api/util.md

+9-8
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,10 @@ added: v8.2.0
2121
* Returns: {Function} a callback style function
2222

2323
Takes an `async` function (or a function that returns a Promise) and returns a
24-
function following the Node.js error first callback style. In the callback, the
25-
first argument will be the rejection reason (or `null` if the Promise resolved),
26-
and the second argument will be the resolved value.
24+
function following the error-first callback style, i.e. taking
25+
a `(err, value) => ...` callback as the last argument. In the callback, the
26+
first argument will be the rejection reason (or `null` if the Promise
27+
resolved), and the second argument will be the resolved value.
2728

2829
For example:
2930

@@ -463,8 +464,8 @@ added: v8.0.0
463464
* `original` {Function}
464465
* Returns: {Function}
465466

466-
Takes a function following the common Node.js callback style, i.e. taking a
467-
`(err, value) => ...` callback as the last argument, and returns a version
467+
Takes a function following the common error-first callback style, i.e. taking
468+
a `(err, value) => ...` callback as the last argument, and returns a version
468469
that returns promises.
469470

470471
For example:
@@ -500,9 +501,9 @@ will return its value, see [Custom promisified functions][].
500501

501502
`promisify()` assumes that `original` is a function taking a callback as its
502503
final argument in all cases. If `original` is not a function, `promisify()`
503-
will throw an error. If `original` is a function but its last argument is not a
504-
Node.js style callback, it will still be passed a Node.js style callback
505-
as its last argument.
504+
will throw an error. If `original` is a function but its last argument is not
505+
an error-first callback, it will still be passed an error-first
506+
callback as its last argument.
506507

507508
### Custom promisified functions
508509

0 commit comments

Comments
 (0)