@@ -3006,34 +3006,40 @@ function definitelyAsync(arg, cb) { |
3006 | 3006 |
|
3007 | 3007 | ### When to use `queueMicrotask()` vs. `process.nextTick()` |
3008 | 3008 |
|
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 |
3013 | 3014 | is drained immediately after. |
3014 | 3015 |
|
| 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 | +
|
3015 | 3021 | ```mjs |
3016 | 3022 | import { nextTick } from 'node:process'; |
3017 | 3023 |
|
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')); |
3021 | 3027 | // Output: |
3022 | | -// 1 |
3023 | | -// 2 |
3024 | | -// 3 |
| 3028 | +// resolve |
| 3029 | +// microtask |
| 3030 | +// nextTick |
3025 | 3031 | ``` |
3026 | 3032 |
|
3027 | 3033 | ```cjs |
3028 | 3034 | const { nextTick } = require('node:process'); |
3029 | 3035 |
|
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')); |
3033 | 3039 | // Output: |
3034 | | -// 1 |
3035 | | -// 2 |
3036 | | -// 3 |
| 3040 | +// nextTick |
| 3041 | +// resolve |
| 3042 | +// microtask |
3037 | 3043 | ``` |
3038 | 3044 |
|
3039 | 3045 | For _most_ userland use cases, the `queueMicrotask()` API provides a portable |
|