Incorporate timers into main Node.js lib defs and align with v24 (#55079)

Summary:
Pull Request resolved: #55079

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)](https://www.internalfb.com/wiki/Confucius/Analect/Shared_Analects/Confucius_Code_Assist_(CCA)/)
[Confucius Session](https://www.internalfb.com/confucius?host=devvm45708.cln0.facebook.com&port=8086&tab=Chat&session_id=1a3aa26e-e5a9-11f0-8d47-71a4a90f0494&entry_name=Code+Assist), [Trace](https://www.internalfb.com/confucius?session_id=1a3aa26e-e5a9-11f0-8d47-71a4a90f0494&tab=Trace)

Reviewed By: vzaidman

Differential Revision: D89944814

fbshipit-source-id: 38c1773d1a3591ef9f123681655720d17e7e53bb

Author: robhogan

flow-typed/environment/node.js

@@ -3702,6 +3702,75 @@ type url$urlObject = {
   ...
 };
 
+declare module 'timers' {
+  declare export class Timeout {
+    close(): this;
+    hasRef(): boolean;
+    ref(): this;
+    refresh(): this;
+    unref(): this;
+    [key: $SymbolToPrimitive]: () => number;
+    // [key: $SymbolDispose]: () => void;
+  }
+
+  declare export class Immediate {
+    hasRef(): boolean;
+    ref(): this;
+    unref(): this;
+    // [key: $SymbolDispose]: () => void;
+  }
+
+  declare export function setTimeout<TArgs: Iterable<mixed>>(
+    callback: (...args: TArgs) => mixed,
+    delay?: number,
+    ...args: TArgs
+  ): Timeout;
+
+  declare export function setInterval<TArgs: Iterable<mixed>>(
+    callback: (...args: TArgs) => mixed,
+    delay?: number,
+    ...args: TArgs
+  ): Timeout;
+
+  declare export function setImmediate<TArgs: Iterable<mixed>>(
+    callback: (...args: TArgs) => mixed,
+    ...args: TArgs
+  ): Immediate;
+
+  declare export function clearTimeout(timeout?: Timeout | number): void;
+  declare export function clearInterval(timeout?: Timeout | number): void;
+  declare export function clearImmediate(immediate?: Immediate | number): void;
+}
+
+declare module 'timers/promises' {
+  declare export type TimerOptions = Readonly<{
+    ref?: boolean,
+    signal?: AbortSignal,
+  }>;
+
+  declare export function setTimeout<T>(
+    delay?: number,
+    value?: T,
+    options?: TimerOptions,
+  ): Promise<T>;
+
+  declare export function setImmediate<T>(
+    value?: T,
+    options?: TimerOptions,
+  ): Promise<T>;
+
+  declare export function setInterval<T = void>(
+    delay?: number,
+    value?: T,
+    options?: TimerOptions,
+  ): AsyncIterator<T>;
+
+  declare export var scheduler: Readonly<{
+    wait(delay: number, options?: TimerOptions): Promise<void>,
+    yield(): Promise<void>,
+  }>;
+}
+
 declare module 'url' {
   declare type Url = {|
     protocol: string | null,
@@ -5057,6 +5126,14 @@ declare module 'node:process' {
   declare module.exports: $Exports<'process'>;
 }
 
+declare module 'node:timers' {
+  declare module.exports: $Exports<'timers'>;
+}
+
+declare module 'node:timers/promises' {
+  declare module.exports: $Exports<'timers/promises'>;
+}
+
 declare module 'node:util' {
   declare module.exports: $Exports<'util'>;
 }