Skip to content

Commit e1e1200

Browse files
dario-piotrowiczaduh95
authored andcommitted
doc: clarify cjs/esm diff in queueMicrotask() vs process.nextTick()
the section comparing `queueMicrotask()` and `process.nextTick()` doesn't address the different scheduling behavior that the two functions have in cjs and esm modules, the section's introductory mjs example also provides an incorrect output, the changes here address such by explaining the difference between the two module types and updating the example accordingly PR-URL: #56659 Fixes: #45048 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
1 parent 57a7b93 commit e1e1200

File tree

1 file changed

+22
-16
lines changed

1 file changed

+22
-16
lines changed

doc/api/process.md

+22-16
Original file line numberDiff line numberDiff line change
@@ -3006,34 +3006,40 @@ function definitelyAsync(arg, cb) {
30063006
30073007
### When to use `queueMicrotask()` vs. `process.nextTick()`
30083008
3009-
The [`queueMicrotask()`][] API is an alternative to `process.nextTick()` that
3010-
also defers execution of a function using the same microtask queue used to
3011-
execute the then, catch, and finally handlers of resolved promises. Within
3012-
Node.js, every time the "next tick queue" is drained, the microtask queue
3009+
The [`queueMicrotask()`][] API is an alternative to `process.nextTick()` that instead of using the
3010+
"next tick queue" defers execution of a function using the same microtask queue used to execute the
3011+
then, catch, and finally handlers of resolved promises.
3012+
3013+
Within Node.js, every time the "next tick queue" is drained, the microtask queue
30133014
is drained immediately after.
30143015
3016+
So in CJS modules `process.nextTick()` callbacks are always run before `queueMicrotask()` ones.
3017+
However since ESM modules are processed already as part of the microtask queue, there
3018+
`queueMicrotask()` callbacks are always exectued before `process.nextTick()` ones since Node.js
3019+
is already in the process of draining the microtask queue.
3020+
30153021
```mjs
30163022
import { nextTick } from 'node:process';
30173023

3018-
Promise.resolve().then(() => console.log(2));
3019-
queueMicrotask(() => console.log(3));
3020-
nextTick(() => console.log(1));
3024+
Promise.resolve().then(() => console.log('resolve'));
3025+
queueMicrotask(() => console.log('microtask'));
3026+
nextTick(() => console.log('nextTick'));
30213027
// Output:
3022-
// 1
3023-
// 2
3024-
// 3
3028+
// resolve
3029+
// microtask
3030+
// nextTick
30253031
```
30263032
30273033
```cjs
30283034
const { nextTick } = require('node:process');
30293035

3030-
Promise.resolve().then(() => console.log(2));
3031-
queueMicrotask(() => console.log(3));
3032-
nextTick(() => console.log(1));
3036+
Promise.resolve().then(() => console.log('resolve'));
3037+
queueMicrotask(() => console.log('microtask'));
3038+
nextTick(() => console.log('nextTick'));
30333039
// Output:
3034-
// 1
3035-
// 2
3036-
// 3
3040+
// nextTick
3041+
// resolve
3042+
// microtask
30373043
```
30383044
30393045
For _most_ userland use cases, the `queueMicrotask()` API provides a portable

0 commit comments

Comments
 (0)