fix(learn): improve setImmediate in Promises article

[pakobarbakadze]

Description

This PR updates the documentation for setImmediate() to provide a more accurate and precise explanation of its behavior within the Node.js event loop. The new description clarifies that setImmediate() callbacks run during the check phase, immediately after I/O callbacks (poll phase), and helps distinguish its timing relative to other asynchronous mechanisms like setTimeout().

It also refines the usage guidance in the "When to Use Each" section, removing redundant and potentially confusing statements.

Validation

The example code has been reviewed to correctly reflect the behavior of setImmediate() in relation to I/O and timers.

Reviewers should verify that the updated explanation is both technically correct and clearly communicates when and why to use setImmediate(). No functional or visual changes—only documentation improvements.

Related Issues

Fixes: nodejs/node#57993

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run npm run format to ensure the code follows the style guide.
• I have run npm run test to check if all tests are passing.
• I have run npx turbo build to check if the website builds without errors.
• I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nodejs-org	✅ Ready (Inspect)	Visit Preview	May 19, 2025 0:32am

[Copilot]

Pull Request Overview

This PR improves the documentation for setImmediate() by clarifying its behavior in the Node.js event loop and refining usage guidance.

• Updated the explanation for setImmediate() to specify that its callbacks are scheduled in the event loop’s check phase after I/O callbacks.
• Augmented the code example to include an I/O operation and a timer to illustrate the order of execution.
• Revised the "When to Use Each" section to provide clearer guidance on the use of setImmediate().

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 75.05%. Comparing base (0b24039) to head (ba7eec6).
Report is 56 commits behind head on main.

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7677      +/-   ##
==========================================
+ Coverage   74.63%   75.05%   +0.41%     
==========================================
  Files          96       98       +2     
  Lines        7689     7914     +225     
  Branches      192      196       +4     
==========================================
+ Hits         5739     5940     +201     
- Misses       1948     1973      +25     
+ Partials        2        1       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pakobarbakadze]

Hey @avivkeller — I noticed that the approval didn't trigger the checks. Is there anything else I should do to get them running?

[avivkeller]

Hi, @pakobarbakadze. The checks are run manually, so no need to re-request approval.

An approving review is different than a workflow run approval.

[github-actions]

Lighthouse Results

URL	Performance	Accessibility	Best Practices	SEO	Report
/en	🟢 99	🟢 100	🟢 100	🟢 91	🔗
/en/about	🟢 100	🟢 100	🟢 100	🟢 91	🔗
/en/about/previous-releases	🟢 99	🟢 100	🟢 100	🟢 92	🔗
/en/download	🟢 98	🟢 100	🟢 100	🟢 91	🔗
/en/blog	🟢 100	🟢 100	🟢 96	🟢 92	🔗

[ovflowd]

I don't think the proposed documentation is any better.

[pakobarbakadze]

@ovflowd Initially, I suggested using a setImmediate example related to setTimeout and I/O to illustrate its role in the event loop. However, since this blog targets beginners, me and @avivkeller decided that that approach may have been too complex. While the current proposal doesn’t fully clarify where setImmediate fits in the event loop, it does help reduce confusion around timers—which is a good step forward.

Could you please suggest how we might improve the explanation further?

Thanks.

[avivkeller]

@ovflowd IIUC (and I might be wrong), @pakobarbakadze pointed out that the specific "but before timers" claim may not be accurate, so it was removed.

If I misunderstood, LMK.

[ovflowd]

Im fine removing my block, but @avivkeller, we don't own content. Please keep that in mind, I'd like to have @nodejs/collaborators chiming in to say if this change is accurate and reflects their perview.

[Trott]

@nodejs/timers

[jakecastelli]

The event loop in Node.js is provided by libuv. If we dive into the source code — specifically this line in core.c — we can see that the check phase is scheduled after the io_poll phase. Interestingly, there’s also another run_pending phase, which can run up to 8 pending callbacks. This phase isn’t mentioned in the graph. And there is due timer phase in the end.

For reference, libuv’s official event loop design is described here: libuv Design Overview.

Since this is part of a learning-focused article, I am not entirely sure what would be better wording.

[ovflowd]

The event loop in Node.js is provided by libuv. If we dive into the source code — specifically this line in core.c — we can see that the check phase is scheduled after the io_poll phase. Interestingly, there’s also another run_pending phase, which can run up to 8 pending callbacks. This phase isn’t mentioned in the graph.

For reference, libuv’s official event loop design is described here: libuv Design Overview.

Since this is part of a learning-focused article, I am not entirely sure what would be better wording.

I believe my ask is if the proposed changes and revised document are in-line with real-world (and/or technical expectations) for setImmediate.

[jakecastelli]

@ovflowd Sorry if I've brought in more confusion!

If we consider

I believe my ask is if the proposed changes and revised document are in-line with real-world (and/or technical expectations) for setImmediate.

This change looks fine to me, it simplified the check phase in the event loop where setImmediate is run.

[jakecastelli]

"but before timers" claim may not be accurate, so it was removed.

This should be before due timers, but considering this is a learn article, maybe simplifying it makes more sense. @avivkeller (in my opinion though)

[ovflowd]

LGTM

[mcollina]

This is factually incorrect. Read:

https://nodejs.org/en/learn/asynchronous-work/event-loop-timers-and-nexttick