Skip to content

Commit 3db136a

Browse files
ramsgoliapapirovski
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 <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Jon Moss <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]>
1 parent efffcc2 commit 3db136a

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

@@ -530,8 +531,8 @@ added: v8.0.0
530531
* `original` {Function}
531532
* Returns: {Function}
532533

533-
Takes a function following the common Node.js callback style, i.e. taking a
534-
`(err, value) => ...` callback as the last argument, and returns a version
534+
Takes a function following the common error-first callback style, i.e. taking
535+
a `(err, value) => ...` callback as the last argument, and returns a version
535536
that returns promises.
536537

537538
For example:
@@ -567,9 +568,9 @@ will return its value, see [Custom promisified functions][].
567568

568569
`promisify()` assumes that `original` is a function taking a callback as its
569570
final argument in all cases. If `original` is not a function, `promisify()`
570-
will throw an error. If `original` is a function but its last argument is not a
571-
Node.js style callback, it will still be passed a Node.js style callback
572-
as its last argument.
571+
will throw an error. If `original` is a function but its last argument is not
572+
an error-first callback, it will still be passed an error-first
573+
callback as its last argument.
573574

574575
### Custom promisified functions
575576

0 commit comments

Comments
 (0)