diff --git a/doc/api/process.md b/doc/api/process.md index 5e798af0bb6cc4..036a754681497b 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -1730,6 +1730,41 @@ 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 +is drained immediately after. The timing of queued microtasks is nearly +identical to `process.nextTick()` with the notable exception that the next +tick queue always executes first. There are also minor differences in the way +errors raised from within the next tick queue and microtask queue are handled. + +For *most* userland use cases, the `queueMicrotask()` API provides a portable +and reliable mechanism for deferring execution that works across multiple +JavaScript platform environments and should be favored over `process.nextTick()`. +In most scenarios, `queueMicrotask()` can be a drop-in replacement for +`process.nextTick()`. + +When in doubt, use `queueMicrotask()`. + +```js +console.log('start'); +queueMicrotask(() => { + console.log('microtask callback'); +}); +console.log('scheduled'); +// Output: +// start +// scheduled +// microtask callback +``` + +Errors thrown within a queued microtask callback should be handled within the +queued callback. If they are not, the `process.on('uncaughtException')` event +handler can be used to capture and handle the errors. + ## `process.noDeprecation`