From e4c86c3a58103932a948df18838187634d5a10ca Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 22 Feb 2021 15:03:09 -0800 Subject: [PATCH] doc: recommend queueMicrotask over process.nextTick We likely cannot ever deprecate process.nextTick, but we can start steering people towards queueMicrotask for most cases. Signed-off-by: James M Snell Fixes: https://github.com/nodejs/node/issues/36870 --- doc/api/process.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) 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`