Align Flow lib defs for Node.js v8 module with v24 (#55225)

Summary:
Pull Request resolved: #55225

This is an AI-assisted change to align the Flow definitions for the `v8` module with the Node.js docs as at v24.

**New v18+ Features:**

1. **Heap Snapshot Near Limit** (v18.10.0) - Automatic snapshot generation
   - Added `setHeapSnapshotNearHeapLimit(limit: number): void` function
   - Generates heap snapshots automatically when heap usage reaches specified limit
   - Useful for debugging memory issues and OOM scenarios
   - https://nodejs.org/api/v8.html#v8setheapsnapshotnearhea plimit

2. **GCProfiler Class** (v19.6.0, v18.15.0) - Garbage collection profiling
   - Added `GCProfiler` class for detailed GC statistics collection
   - `start()` method begins profiling session
   - `stop()` method returns `GCProfilerResult` with detailed statistics
   - Includes before/after heap statistics for each GC event
   - https://nodejs.org/api/v8.html#class-v8gcprofiler

**New v20+ Features:**

3. **Query Objects** (v20.13.0) - Object instance tracking
   - Added `queryObjects(ctor, options?)` function with two overloads
   - Similar to Chrome DevTools console API
   - Searches for objects matching a constructor on prototype chain
   - Two formats: `'count'` (returns number) or `'summary'` (returns string array)
   - Useful for memory leak regression tests
   - https://nodejs.org/api/v8.html#v8queryobjectsctor-options

**New v22+ Features:**

4. **C++ Heap Statistics** (v22.15.0) - cppgc heap monitoring
   - Added `getCppHeapStatistics(detailLevel?)` function
   - Returns C++ heap statistics from cppgc
   - Two detail levels: `'brief'` (top-level stats) or `'detailed'` (includes space/page breakdown)
   - https://nodejs.org/api/v8.html#v8getcppheapstatisticsdetaillevel

5. **String Representation Check** (v23.10.0, backported to v22.15.0)
   - Added `isStringOneByteRepresentation(content: string): boolean` function
   - Checks if string uses Latin-1/ISO-8859-1 encoding (single byte per character)
   - Useful for optimizing string serialization
   - https://nodejs.org/api/v8.html#v8isstringonebyterepresentationvalue

**Type System Improvements:**

6. **Complete Type Definitions** - Added missing fields and proper types:
   - `DoesZapCodeSpaceFlag` type alias (0 | 1) for `does_zap_garbage`
   - `HeapCodeStatistics` - Added `cpu_profiler_metadata_size` field
   - `HeapInfo` (renamed from `HeapStatistics`) - Added 3 missing fields:
     - `total_global_handles_size` (v13.3.0)
     - `used_global_handles_size` (v13.3.0)
     - `external_memory` (v13.3.0)
   - `HeapSpaceInfo` (renamed from `HeapSpaceStatistics`) - Removed spread operator
   - `HeapSnapshotOptions` (new) - Options for heap snapshot generation:
     - `exposeInternals?: boolean` - Expose internals in snapshot
     - `exposeNumericValues?: boolean` - Expose numeric values
   - `HeapStatistics` (camelCase) - For GCProfiler, complete with all 11 fields
   - `HeapSpaceStatistics` (camelCase) - For GCProfiler, complete with all 5 fields
   - `GCProfilerResult` - Complete result type with version, timing, and statistics array
   - https://nodejs.org/api/v8.html#v8getheapstatistics

7. **Enhanced Function Signatures**:
   - `getHeapSnapshot(options?)` - Added optional `HeapSnapshotOptions` parameter
   - `writeHeapSnapshot(fileName?, options?)` - Added optional `HeapSnapshotOptions` parameter
   - `getHeapStatistics()` - Changed return type from `HeapStatistics` to `HeapInfo`
   - `getHeapSpaceStatistics()` - Changed return type to `Array<HeapSpaceInfo>`
   - https://nodejs.org/api/v8.html#v8getheapsnapshotoptions

8. **Coverage Functions** - For type profile analysis:
   - `takeCoverage(): void` (v15.1.0) - Starts capturing V8 type profile
   - `stopCoverage(): void` (v15.1.0) - Stops capturing V8 type profile
   - https://nodejs.org/api/v8.html#v8takecoverage

9. **Serialization Documentation**:
   - Added `since v8.0.0` tags to all serialization classes and functions
   - Improved class documentation for `Serializer`, `Deserializer`, `DefaultSerializer`, `DefaultDeserializer`
   - https://nodejs.org/api/v8.html#serialization-api

**References:**
- Node.js v8 module docs: https://nodejs.org/api/v8.html
- Heap statistics: https://nodejs.org/api/v8.html#v8getheapstatistics
- GC profiling: https://nodejs.org/api/v8.html#class-v8gcprofiler
- Query objects: https://nodejs.org/api/v8.html#v8queryobjectsctor-options

Changelog: [Internal]

Reviewed By: vzaidman

Differential Revision: D90762740

fbshipit-source-id: 41581da6af6e62198c94e336740241b7983d4486

Author: robhogan

flow-typed/environment/node.js

@@ -4975,73 +4975,186 @@ declare module 'assert/strict' {
   declare module.exports: $Exports<'assert'>['strict'];
 }
 
-type HeapCodeStatistics = {
-  code_and_metadata_size: number,
-  bytecode_and_metadata_size: number,
-  external_script_source_size: number,
-  ...
-};
+declare module 'v8' {
+  declare export type DoesZapCodeSpaceFlag = 0 | 1;
 
-type HeapStatistics = {
-  total_heap_size: number,
-  total_heap_size_executable: number,
-  total_physical_size: number,
-  total_available_size: number,
-  used_heap_size: number,
-  heap_size_limit: number,
-  malloced_memory: number,
-  peak_malloced_memory: number,
-  does_zap_garbage: 0 | 1,
-  number_of_native_contexts: number,
-  number_of_detached_contexts: number,
-  ...
-};
+  declare export type HeapCodeStatistics = {
+    code_and_metadata_size: number,
+    bytecode_and_metadata_size: number,
+    external_script_source_size: number,
+    cpu_profiler_metadata_size: number,
+  };
 
-type HeapSpaceStatistics = {
-  space_name: string,
-  space_size: number,
-  space_used_size: number,
-  space_available_size: number,
-  physical_space_size: number,
-  ...
-};
+  declare export type HeapInfo = {
+    total_heap_size: number,
+    total_heap_size_executable: number,
+    total_physical_size: number,
+    total_available_size: number,
+    used_heap_size: number,
+    heap_size_limit: number,
+    malloced_memory: number,
+    peak_malloced_memory: number,
+    does_zap_garbage: DoesZapCodeSpaceFlag,
+    number_of_native_contexts: number,
+    number_of_detached_contexts: number,
+    total_global_handles_size: number,
+    used_global_handles_size: number,
+    external_memory: number,
+  };
+
+  declare export type HeapSpaceInfo = {
+    space_name: string,
+    space_size: number,
+    space_used_size: number,
+    space_available_size: number,
+    physical_space_size: number,
+  };
+
+  declare export type HeapSnapshotOptions = Readonly<{
+    exposeInternals?: boolean,
+    exposeNumericValues?: boolean,
+  }>;
+
+  // For GCProfiler - uses camelCase naming convention
+  declare export type HeapStatistics = {
+    totalHeapSize: number,
+    totalHeapSizeExecutable: number,
+    totalPhysicalSize: number,
+    totalAvailableSize: number,
+    totalGlobalHandlesSize: number,
+    usedGlobalHandlesSize: number,
+    usedHeapSize: number,
+    heapSizeLimit: number,
+    mallocedMemory: number,
+    externalMemory: number,
+    peakMallocedMemory: number,
+  };
+
+  declare export type HeapSpaceStatistics = {
+    spaceName: string,
+    spaceSize: number,
+    spaceUsedSize: number,
+    spaceAvailableSize: number,
+    physicalSpaceSize: number,
+  };
+
+  declare export type GCProfilerResult = {
+    version: number,
+    startTime: number,
+    endTime: number,
+    statistics: $ReadOnlyArray<{
+      gcType: string,
+      cost: number,
+      beforeGC: {
+        heapStatistics: HeapStatistics,
+        heapSpaceStatistics: $ReadOnlyArray<HeapSpaceStatistics>,
+      },
+      afterGC: {
+        heapStatistics: HeapStatistics,
+        heapSpaceStatistics: $ReadOnlyArray<HeapSpaceStatistics>,
+      },
+    }>,
+  };
 
-// Adapted from DefinitelyTyped for Node v14:
-// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/dea4d99dc302a0b0a25270e46e72c1fe9b741a17/types/node/v14/v8.d.ts
-declare module 'v8' {
   /**
-   * Returns an integer representing a "version tag" derived from the V8 version, command line flags and detected CPU features.
-   * This is useful for determining whether a vm.Script cachedData buffer is compatible with this instance of V8.
+   * Returns an integer representing a "version tag" derived from the V8 version,
+   * command line flags and detected CPU features. This is useful for determining
+   * whether a vm.Script cachedData buffer is compatible with this instance of V8.
    */
   declare function cachedDataVersionTag(): number;
 
   /**
-   * Generates a snapshot of the current V8 heap and returns a Readable
-   * Stream that may be used to read the JSON serialized representation.
-   * This conversation was marked as resolved by joyeecheung
-   * This JSON stream format is intended to be used with tools such as
-   * Chrome DevTools. The JSON schema is undocumented and specific to the
-   * V8 engine, and may change from one version of V8 to the next.
+   * Returns statistics about code and its metadata in the heap.
    */
-  declare function getHeapSnapshot(): stream$Readable;
+  declare function getHeapCodeStatistics(): HeapCodeStatistics;
 
   /**
-   *
-   * @param fileName The file path where the V8 heap snapshot is to be
-   * saved. If not specified, a file name with the pattern
-   * `'Heap-${yyyymmdd}-${hhmmss}-${pid}-${thread_id}.heapsnapshot'` will be
-   * generated, where `{pid}` will be the PID of the Node.js process,
-   * `{thread_id}` will be `0` when `writeHeapSnapshot()` is called from
-   * the main Node.js thread or the id of a worker thread.
+   * Returns an object with statistics about the V8 heap.
    */
-  declare function writeHeapSnapshot(fileName?: string): string;
+  declare function getHeapStatistics(): HeapInfo;
 
-  declare function getHeapCodeStatistics(): HeapCodeStatistics;
+  /**
+   * Returns statistics about the V8 heap spaces.
+   */
+  declare function getHeapSpaceStatistics(): Array<HeapSpaceInfo>;
 
-  declare function getHeapStatistics(): HeapStatistics;
-  declare function getHeapSpaceStatistics(): Array<HeapSpaceStatistics>;
+  /**
+   * Generates a snapshot of the current V8 heap and returns a Readable Stream
+   * that may be used to read the JSON serialized representation. This JSON stream
+   * format is intended to be used with tools such as Chrome DevTools. The JSON
+   * schema is undocumented and specific to the V8 engine.
+   * @param options Optional settings for controlling snapshot detail
+   */
+  declare function getHeapSnapshot(
+    options?: HeapSnapshotOptions,
+  ): stream$Readable;
+
+  /**
+   * Generates a snapshot of the current V8 heap and writes it to a JSON file.
+   * @param fileName The file path where the snapshot will be saved. If not specified,
+   *   a file name with the pattern 'Heap-${yyyymmdd}-${hhmmss}-${pid}-${thread_id}.heapsnapshot'
+   *   will be generated.
+   * @param options Optional settings for controlling snapshot detail
+   * @returns The filename where the snapshot was saved
+   */
+  declare function writeHeapSnapshot(
+    fileName?: string,
+    options?: HeapSnapshotOptions,
+  ): string;
+
+  /**
+   * Sets V8 command-line flags. Use with care; changing settings after the VM has
+   * started may result in unpredictable behavior, crashes, or data loss.
+   */
   declare function setFlagsFromString(flags: string): void;
 
+  /**
+   * Generates a heap snapshot when the heap usage reaches the specified limit.
+   * @param limit The heap size limit that triggers snapshot generation
+   */
+  declare function setHeapSnapshotNearHeapLimit(limit: number): void;
+
+  /**
+   * Searches for objects that match the given constructor on their prototype chain.
+   * Similar to Chrome DevTools' queryObjects() console API.
+   * @since v20.13.0
+   * @experimental
+   */
+  declare function queryObjects(
+    ctor: Function,
+    options?: {format: 'count'},
+  ): number;
+  declare function queryObjects(
+    ctor: Function,
+    options: {format: 'summary'},
+  ): Array<string>;
+
+  /**
+   * Returns C++ heap statistics from the cppgc heap.
+   * @since v22.15.0
+   * @param detailLevel Level of detail: 'brief' for top-level stats, 'detailed' for space/page breakdown
+   */
+  declare function getCppHeapStatistics(
+    detailLevel?: 'brief' | 'detailed',
+  ): Object;
+
+  /**
+   * Checks if a string's internal representation uses one byte per character (Latin-1/ISO-8859-1 encoding).
+   * Useful for optimizing string serialization.
+   * @since v23.10.0, v22.15.0
+   */
+  declare function isStringOneByteRepresentation(content: string): boolean;
+
+  /**
+   * Starts capturing V8 type profile for coverage analysis.
+   */
+  declare function takeCoverage(): void;
+
+  /**
+   * Stops capturing V8 type profile for coverage analysis.
+   */
+  declare function stopCoverage(): void;
+
   declare class Serializer {
     constructor(): void;
 
@@ -5163,6 +5276,23 @@ declare module 'v8' {
    * Uses a `DefaultDeserializer` with default options to read a JS value from a buffer.
    */
   declare function deserialize(data: Buffer | $TypedArray | DataView): any;
+
+  /**
+   * Starts a GC profiling session that collects detailed garbage collection statistics.
+   */
+  declare class GCProfiler {
+    constructor(): void;
+
+    /**
+     * Starts the GC profiling session.
+     */
+    start(): void;
+
+    /**
+     * Stops the GC profiling session and returns collected statistics.
+     */
+    stop(): GCProfilerResult;
+  }
 }
 
 type repl$DefineCommandOptions = (...args: Array<any>) => void | {
@@ -5600,6 +5730,11 @@ declare module 'node:util' {
   declare module.exports: $Exports<'util'>;
 }
 
+declare module 'node:v8' {
+  export type * from 'v8';
+  declare module.exports: $Exports<'v8'>;
+}
+
 declare module 'node:worker_threads' {
   export type * from 'worker_threads';
   declare module.exports: $Exports<'worker_threads'>;