Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 9ab4771

Browse files
committedJan 19, 2025·
doc: clarify cjs and esm scheduling difference between queueMicrotask() and 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
1 parent 6f946c9 commit 9ab4771

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
@@ -3020,34 +3020,40 @@ function definitelyAsync(arg, cb) {
30203020
30213021
### When to use `queueMicrotask()` vs. `process.nextTick()`
30223022
3023-
The [`queueMicrotask()`][] API is an alternative to `process.nextTick()` that
3024-
also defers execution of a function using the same microtask queue used to
3025-
execute the then, catch, and finally handlers of resolved promises. Within
3026-
Node.js, every time the "next tick queue" is drained, the microtask queue
3023+
The [`queueMicrotask()`][] API is an alternative to `process.nextTick()` that instead of using the
3024+
"next tick queue" defers execution of a function using the same microtask queue used to execute the
3025+
then, catch, and finally handlers of resolved promises.
3026+
3027+
Within Node.js, every time the "next tick queue" is drained, the microtask queue
30273028
is drained immediately after.
30283029
3030+
So in CJS modules `process.nextTick()` callbacks are always run before `queueMicrotask()` ones.
3031+
However since ESM modules are processed already as part of the microtask queue, there
3032+
`queueMicrotask()` callbacks are always exectued before `process.nextTick()` ones since Node.js
3033+
is already in the process of draining the microtask queue.
3034+
30293035
```mjs
30303036
import { nextTick } from 'node:process';
30313037

3032-
Promise.resolve().then(() => console.log(2));
3033-
queueMicrotask(() => console.log(3));
3034-
nextTick(() => console.log(1));
3038+
Promise.resolve().then(() => console.log('resolve'));
3039+
queueMicrotask(() => console.log('microtask'));
3040+
nextTick(() => console.log('nextTick'));
30353041
// Output:
3036-
// 1
3037-
// 2
3038-
// 3
3042+
// resolve
3043+
// microtask
3044+
// nextTick
30393045
```
30403046
30413047
```cjs
30423048
const { nextTick } = require('node:process');
30433049

3044-
Promise.resolve().then(() => console.log(2));
3045-
queueMicrotask(() => console.log(3));
3046-
nextTick(() => console.log(1));
3050+
Promise.resolve().then(() => console.log('resolve'));
3051+
queueMicrotask(() => console.log('microtask'));
3052+
nextTick(() => console.log('nextTick'));
30473053
// Output:
3048-
// 1
3049-
// 2
3050-
// 3
3054+
// nextTick
3055+
// resolve
3056+
// microtask
30513057
```
30523058
30533059
For _most_ userland use cases, the `queueMicrotask()` API provides a portable

0 commit comments

Comments
 (0)
Please sign in to comment.