Incorporate timers into main Node.js lib defs and align with v24

[robhogan]

Summary:
This is an AI-assisted change to consolidate Metro's separate node.js file into the main Node.js library definitions and align with Node.js v24 (effectively v22) standards.

Consolidation Changes:

1. Incorporated Separate File - Removed duplication
   • Moved definitions from xplat/js/tools/metro/flow-typed/node.js into main node.js files
   • Deleted the separate node.js file (no longer needed)
   • Both Metro and React Native now use unified definitions
   • Positioned alphabetically between 'tls' and 'url' modules

Timeout Class Enhancements:

2. Complete Timeout Class - All timer management methods
   • close() - Cancels the timeout (added in v0.9.1)
   • hasRef() - Returns true if timer will keep Node.js running (added in v11.0.0)
   • ref() - Request timer keep Node.js running (added in v0.9.1)
   • refresh() - Refresh timer's start time (added in v10.2.0)
   • unref() - Allow Node.js to exit if timer is only active thing (added in v0.9.1)
   • [Symbol.toPrimitive] - Get numeric timer ID (added in v14.9.0) - Uses [key: $SymbolToPrimitive] syntax
   • https://nodejs.org/api/timers.html#class-timeout

Immediate Class Enhancements:

3. Complete Immediate Class - Immediate timer management
   • hasRef() - Returns true if immediate will keep Node.js running (added in v11.0.0)
   • ref() - Request immediate keep Node.js running (added in v9.7.0, v8.12.0)
   • unref() - Allow Node.js to exit if immediate is only active thing (added in v9.7.0, v8.12.0)
   • https://nodejs.org/api/timers.html#class-immediate

Core Timer Functions:

4. setTimeout/setInterval/setImmediate - Complete signatures

   • Generic <TArgs: Iterable<mixed>> for type-safe callback arguments
   • setTimeout(callback, delay?, ...args) - Returns Timeout
   • setInterval(callback, delay?, ...args) - Returns Timeout
   • setImmediate(callback, ...args) - Returns Immediate
   • All support passing additional arguments to callback
   • https://nodejs.org/api/timers.html#settimeoutcallback-delay-args

5. Clear Functions - Flexible cancellation

   • clearTimeout(timeout?) - Accepts Timeout or numeric ID
   • clearInterval(timeout?) - Accepts Timeout or numeric ID
   • clearImmediate(immediate?) - Accepts Immediate or numeric ID
   • All parameters optional (no-op if not provided)
   • https://nodejs.org/api/timers.html#cleartimeouttimeout

Promises API (timers/promises):

6. Promise-based Timers - Async/await compatible

   • setTimeout<T>(delay?, value?, options?) - Returns Promise<T> (added in v15.0.0)
   • setImmediate<T>(value?, options?) - Returns Promise<T> (added in v15.0.0)
   • setInterval<T>(delay?, value?, options?) - Returns AsyncIterator<T> (added in v15.9.0)
   • All support AbortSignal for cancellation
   • https://nodejs.org/api/timers.html#timers-promises-api

7. TimerOptions Type - Modern options object

   • ref?: boolean - Control if timer keeps Node.js running
   • signal?: AbortSignal - Abort controller for cancellation
   • Type uses Readonly<{...}> for input immutability
   • https://nodejs.org/api/timers.html#timerspromisessettimeoutdelay-value-options

8. setInterval as AsyncIterator - Async iteration support (added in v15.9.0)

   • Returns AsyncIterator<T> instead of Promise<T>
   • Enables for await (const value of setInterval(100, data)) patterns
   • Useful for periodic async operations
   • https://nodejs.org/api/timers.html#timerspromisessetintervaldelay-value-options

Scheduler API:

9. scheduler object - Task scheduling utilities (added in v16.0.0)
   • scheduler.wait(delay, options?) - Promise-based delay (alternative to setTimeout)
   • scheduler.yield() - Yield to event loop (microtask yield)
   • Object marked as Readonly<{...}> for immutability
   • https://nodejs.org/api/timers.html#timerspromisesschedulerwaitdelay-options

Type Safety Improvements:

10. Readonly Input Types - Applied consistently

    • TimerOptions: Readonly<{ref?, signal?}>
    • scheduler object: Readonly<{wait, yield}>
    • Allows passing readonly types safely (inputs should be readonly)

11. Generic Type Parameters - Type-safe callbacks

    • Timer functions: <TArgs: Iterable<mixed>> for variadic args
    • Promises API: <T> for resolved value types
    • Default generic: <T = void> for setInterval iterator

12. Export Type Aliases - Better developer experience

    • Timeout and Immediate exported as types from module
    • Consistent timers$ prefix for internal types
    • Clean module exports without duplication

Symbol Support:

13. Symbol.toPrimitive - Convert Timeout to number (added in v14.9.0)
    • Allows implicit conversion: Number(timeout) or +timeout
    • Returns the numeric timer ID
    • Flow syntax: [key: $SymbolToPrimitive]: () => number
    • https://nodejs.org/api/timers.html#timeoutsymboltoprimitive

Flow Limitations:

14. Symbol.dispose not included - Explicit resource management
    • [key: $SymbolDispose]: () => void is commented out
    • Node.js added Symbol.dispose in v18.18.0, v20.4.0
    • Flow doesn't fully support this symbol yet or has issues with multiple symbol-keyed properties
    • Will be enabled when Flow support improves
    • https://nodejs.org/api/timers.html#timeoutsymboldispose

References:

• Node.js timers module docs: https://nodejs.org/api/timers.html
• TC39 Explicit Resource Management: https://github.com/tc39/proposal-explicit-resource-management

Changelog: [Internal]

Generated by Confucius Code Assist (CCA)
Confucius Session, Trace

Reviewed By: vzaidman

Differential Revision: D89944814

[meta-codesync]

@robhogan has exported this pull request. If you are a Meta employee, you can view the originating Diff in D89944814.

[github-actions]

Job Summary for Gradle

Test All :: run_fantom_tests

Gradle Root Project	Requested Tasks	Gradle Version	Build Outcome	Build Scan®
react-native-github	:private:react-native-fantom:buildFantomTester	9.0.0	❌

[github-actions]

Job Summary for Gradle

Test All :: run_fantom_tests

Gradle Root Project	Requested Tasks	Gradle Version	Build Outcome	Build Scan®
react-native-github	:private:react-native-fantom:buildFantomTester	9.0.0	❌

[react-native-bot]

This pull request was successfully merged by @robhogan in a5fc307

^{When will my fix make it into a release? | How to file a pick request?}

[meta-codesync]

This pull request has been merged in a5fc307.

[github-actions]

Job Summary for Gradle

Test All :: run_fantom_tests

Gradle Root Project	Requested Tasks	Gradle Version	Build Outcome	Build Scan®
react-native-github	:private:react-native-fantom:buildFantomTester	9.0.0	❌