Skip to content

Commit

Permalink
doc: clarify cjs/esm diff in queueMicrotask() vs process.nextTick()
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
dario-piotrowicz authored and aduh95 committed Jan 27, 2025
1 parent f3b44a6 commit 434ef85
Showing 1 changed file with 22 additions and 16 deletions.
38 changes: 22 additions & 16 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -3006,34 +3006,40 @@ function definitelyAsync(arg, cb) {
### When to use `queueMicrotask()` vs. `process.nextTick()`
The [`queueMicrotask()`][] API is an alternative to `process.nextTick()` that
also defers execution of a function using the same microtask queue used to
execute the then, catch, and finally handlers of resolved promises. Within
Node.js, every time the "next tick queue" is drained, the microtask queue
The [`queueMicrotask()`][] API is an alternative to `process.nextTick()` that instead of using the
"next tick queue" defers execution of a function using the same microtask queue used to execute the
then, catch, and finally handlers of resolved promises.
Within Node.js, every time the "next tick queue" is drained, the microtask queue
is drained immediately after.
So in CJS modules `process.nextTick()` callbacks are always run before `queueMicrotask()` ones.
However since ESM modules are processed already as part of the microtask queue, there
`queueMicrotask()` callbacks are always exectued before `process.nextTick()` ones since Node.js
is already in the process of draining the microtask queue.
```mjs
import { nextTick } from 'node:process';

Promise.resolve().then(() => console.log(2));
queueMicrotask(() => console.log(3));
nextTick(() => console.log(1));
Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// 1
// 2
// 3
// resolve
// microtask
// nextTick
```
```cjs
const { nextTick } = require('node:process');

Promise.resolve().then(() => console.log(2));
queueMicrotask(() => console.log(3));
nextTick(() => console.log(1));
Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// 1
// 2
// 3
// nextTick
// resolve
// microtask
```
For _most_ userland use cases, the `queueMicrotask()` API provides a portable
Expand Down

0 comments on commit 434ef85

Please sign in to comment.