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	Apr 23, 2025 6:48pm

[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 74.61%. Comparing base (0b24039) to head (0b8d8c8).

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7677      +/-   ##
==========================================
- Coverage   74.63%   74.61%   -0.03%     
==========================================
  Files          96       96              
  Lines        7689     7689              
  Branches      192      192              
==========================================
- Hits         5739     5737       -2     
- Misses       1948     1950       +2     
  Partials        2        2              

☔ 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.