lib: move queueMicrotask to stable by devsnek · Pull Request #25594 · nodejs/node (original) (raw)

I'm not sure if this is the right place, but I would like to suggest that the documentation be enhanced to describe why Node.js has this API, and/or under what conditions we think it should be used.

https://nodejs.org/api/globals.html#globals_queuemicrotask_callback is ATM a purely factual description of what it does, but given the difficulty in knowing when to use setImmediate() vs nextTick(), adding a third option seems to just add to the confusion.

I'm personally confused, because while the docs don't say anything on expected usage, there is some example code, that is virtually identical in purpose to the examples in process.nextTick, but with the additional mention of something about interaction with promises. The example just makes me wonder if all usages of nextTick somehow don't interact with promises, or perhaps the example is not specific enough.

See https://nodejs.org/api/process.html#process_process_nexttick_callback_args to compare the examples, and description.

For me, this kind of vagueness is fine for experimental APIs, but once they have had some use, it should be clarified.

Its possible the docs should be something like:

This API allows access to the same callback queue used by promises. Most Node.js code should be using nextTick, but implementors of promise utility libraries may need to schedule callbacks with precise ordering relationships with respect to promises. It may also be useful for running non-Node.js specific javascript code, since the API also exists in browsers (ref to browser docs....).

If the above guess at the purpose is somewhat correct, the example should not be so similar to the nextTick example, but instead be a Promise.waitAll() implementation, or something of the like.