doc: fix process.nextTick() scheduling differences between module types

[dnalborczyk]

fixes #45048

[devsnek]

process.nextTick is not scheduled differently, the module's execution is scheduled differently (specifically, it is a microtask). I think we should be careful of our wording here so people don't get confused.

[jasnell]

Agree. The wording here is a bit off. I would suggest wording like, "The timing of the execution of tasks scheduled with process.nextTick() will vary depending on the module type being used."

[theanarkh]

I think it is because the mjs module is loaded by promise, so after Node.js execute the code of mjs module, it will handle the microtask(except for tasks created by nextTick) created by mjs module. But the js module is loaded synchronously, so it is different. Is it right ?

[parmishh]

This code imports the nextTick function from the built-in Node.js process module and then creates a chain of asynchronous operations using Promise.resolve(), queueMicrotask(), and nextTick().

Here's a breakdown of what each part of the code does:

The Promise.resolve().then(() => console.log(2)) creates a resolved promise and schedules a callback to be executed when the promise is resolved. In this case, the callback logs the number 2 to the console.

The queueMicrotask(() => console.log(3)) adds a function to the microtask queue, which will be executed after the current task has finished executing. In this case, the function logs the number 3 to the console.

The nextTick(() => console.log(1)) schedules a callback to be executed on the next iteration of the event loop. In this case, the callback logs the number 1 to the console.

Since the callbacks are executed asynchronously, the order in which the numbers are logged to the console may not be what you expect. Here is the expected output:
1
2
3
The reason for this order is that the nextTick() callback is executed before the Promise.resolve() and queueMicrotask() callbacks. Then, the Promise.resolve() callback is executed before the queueMicrotask() callback because Promise.resolve() callbacks are executed before microtask queue callbacks. Finally, the queueMicrotask() callback is executed last.

BUT

The reason why the output is 2 3 1 instead of 1 2 3 is that the nextTick() function and queueMicrotask() function are similar but have slightly different behavior. In this case, the queueMicrotask() callback is executed before the nextTick() callback, which causes the output to be in the order of 2 3 1.

The nextTick() function schedules a callback to be executed on the next iteration of the event loop, but after I/O operations have been processed. The queueMicrotask() function, on the other hand, schedules a callback to be executed on the microtask queue, which is executed before the next event loop iteration.

In this specific case, it's possible that the nextTick() callback was delayed due to I/O operations, which allowed the queueMicrotask() callback to be executed first. This behavior can vary depending on the environment and platform that the code is running on, so it's not always predictable which callback will be executed first.

In general, when scheduling multiple asynchronous operations, it's important to be aware of the differences between the various scheduling functions and their behavior in different contexts.

@Trott @dnalborczyk @devsnek @theanarkh

If you Guys want I can do a PR

[dnalborczyk]

@parmishh the issue is that running the same code differs in behavior when run as a commonjs module vs. an es module. this PR corrects the expected output for the latter (esm). As I understand, the differences are working as intended, and are specific to how the modules (cjs vs. esm) have been implemented in node.js . Keep in mind that neither commonjs nor nextTick have a proper spec from TC39/WHATWG/W3C.

Anyhow, what's needed is a short description why the example code differs in both module systems.

creates a chain of asynchronous operations using Promise.resolve(), queueMicrotask(), and nextTick().

If I'm not mistaken, a Promise is actually going into the same microtask queue as something scheduled with queueMicrotask()

[outbits]

I had to crawl the issues for some time to understand that the esm/cjs divergence was not a bug.
Any update on making this good to merge?

[luoxzhg]

what is blocking this PR?

[github-actions]

This issue/PR was marked as stalled, it will be automatically closed in 30 days. If it should remain open, please leave a comment explaining why it should remain open.