Align Flow lib defs for Node.js v8 module with v24

[robhogan]

Summary:
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]

Differential Revision: D90762740

[meta-codesync]

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