Added details about setTimeout() and setInterval() returns a Timeout …

[Vishal-K-988]

Description

This PR updates the JavaScript Timers documentation to accurately reflect the Node.js-specific behavior of setTimeout() and setInterval(). The changes include:

• Clarified that these functions return a Timeout object in Node.js (vs. numeric ID in browsers)
• Added documentation for the Timeout object's additional methods:
  • ref(): Keeps the Node.js event loop active while the timer is running
  • unref(): Allows the Node.js event loop to exit even if the timer is still running
  • refresh(): Resets the timer's start time to the current time
• Maintained consistent mentions of browser vs Node.js behavior throughout the document
• Preserved existing examples and diagrams while enhancing explanations

These changes help prevent confusion for developers who might expect numeric IDs and make them aware of the additional functionality available in Node.js.

Validation

The changes have been validated by:

1. Reviewing the updated content for accuracy and clarity
2. Ensuring the documentation maintains its existing structure and readability
3. Verifying that all code examples remain functional
4. Confirming that the changes align with the Node.js Timers module documentation

Related Issues

This PR addresses the documentation issue regarding the misleading description of timer return values in Node.js. It helps clarify the distinction between browser and Node.js behavior for setTimeout() and setInterval().
Issue: #7672

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run pnpm format to ensure the code follows the style guide.
• I have run pnpm test to check if all tests are passing.
• I have run pnpm 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 18, 2025 6:40pm

[avivkeller]

Suggested change

	`setTimeout` and `setInterval` are available in Node.js, through the [Timers module](https://nodejs.org/api/timers.html). In Node.js, these functions return a Timeout object that provides additional functionality for timer management.
	`setTimeout` and `setInterval` are available in Node.js, through the [Timers module](https://nodejs.org/api/timers.html).

We've already said this earlier in the document.

[avivkeller]

Suggested change

Like `setTimeout`, `setInterval` returns a Timeout object in Node.js (and a numeric ID in browsers). This object provides the same additional methods (`ref()`, `unref()`, and `refresh()`).

Earlier, we say "setInterval is a function similar to setTimeout", which I think implies they have the same return.

[avivkeller]

Suggested change

	`setTimeout` returns a timer identifier. In Node.js, this is a Timeout object that provides additional functionality, while in browsers it returns a numeric ID. You can store this identifier and use it to cancel the scheduled function execution:
	`setTimeout` returns a [`Timeout`](https://nodejs.org/api/timers.html#class-timeout) instance in Node.js, whereas in browsers it returns a numeric ID. This object or ID can be used to cancel the scheduled function execution:

[avivkeller]

These example should probably not use id, they are meant for Node.js, so let's use a more specific variable name

Suggested change

	const id = setTimeout(() => {
	const timeout = setTimeout(() => {

[avivkeller]

Suggested change

	In Node.js, the Timeout object provides additional methods:
	- `timeout.ref()`: Keeps the Node.js event loop active while the timer is running
	- `timeout.unref()`: Allows the Node.js event loop to exit even if the timer is still running
	- `timeout.refresh()`: Resets the timer's start time to the current time

See my other suggestion. We can link to the documentation.