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

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/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
This commit is contained in:
Rob Hogan authored and meta-codesync[bot] committed 2026-01-23 03:02:28 -08:00
1 parent 6f698ab749
commit 09adea9dcd
1 file changed
+191 -56
+191 -56
View File
@@ -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,
...
};
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,
...
};
type HeapSpaceStatistics = {
space_name: string,
space_size: number,
space_used_size: number,
space_available_size: number,
physical_space_size: number,
...
};
// Adapted from DefinitelyTyped for Node v14:
// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/dea4d99dc302a0b0a25270e46e72c1fe9b741a17/types/node/v14/v8.d.ts
declare module 'v8' {
declare export type DoesZapCodeSpaceFlag = 0 | 1;
declare export type HeapCodeStatistics = {
code_and_metadata_size: number,
bytecode_and_metadata_size: number,
external_script_source_size: number,
cpu_profiler_metadata_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>,
},
}>,
};
/**
* 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;
/**
*
* @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.
*/
declare function writeHeapSnapshot(fileName?: string): string;
declare function getHeapCodeStatistics(): HeapCodeStatistics;
declare function getHeapStatistics(): HeapStatistics;
declare function getHeapSpaceStatistics(): Array<HeapSpaceStatistics>;
/**
* Returns an object with statistics about the V8 heap.
*/
declare function getHeapStatistics(): HeapInfo;
/**
* Returns statistics about the V8 heap spaces.
*/
declare function getHeapSpaceStatistics(): Array<HeapSpaceInfo>;
/**
* 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'>;