Incorporate perf_hooks into main Node.js lib defs and align with v24 (#55058)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/55058

This is an AI-assisted change to consolidate Metro's separate `perf_hooks.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 `metro/flow-typed/perf_hooks.js` into main `node.js` files
   - Deleted the separate perf_hooks.js file (no longer needed)
   - Both Metro and React Native now use unified definitions
   - Positioned alphabetically between 'path' and 'punycode' modules

**Enhanced Histogram Types:**

2. **Complete Histogram Interface** - Added missing bigint support (v17.4.0)
   - `count` and `countBigInt` - Total sample count
   - `exceeds` and `exceedsBigInt` - Samples exceeding 1-hour threshold
   - `max` and `maxBigInt` - Maximum recorded value
   - `min` and `minBigInt` - Minimum recorded value
   - `percentile()` and `percentileBigInt()` - Get value at percentile
   - `percentiles` and `percentilesBigInt` - Map of percentile distributions
   - https://nodejs.org/api/perf_hooks.html#class-histogram

3. **RecordableHistogram Interface** - Custom histogram creation (v15.9.0, v14.18.0)
   - `record(val)` - Record a value in the histogram
   - `recordDelta()` - Record time delta since last call
   - Used with `createHistogram()` for custom performance tracking
   - https://nodejs.org/api/perf_hooks.html#class-recordablehistogram

**Enhanced Performance Entry Classes:**

4. **PerformanceNodeTiming Class** - Complete Node.js lifecycle timing
   - Renamed from PerformanceNodeEntry for accuracy
   - `bootstrapComplete` - Bootstrap completion timestamp
   - `environment` - Environment initialization timestamp
   - `idleTime` - Event loop idle time (v14.10.0)
   - `loopStart`, `loopExit` - Event loop lifecycle timestamps
   - `nodeStart` - Process initialization timestamp
   - `v8Start` - V8 platform initialization timestamp
   - https://nodejs.org/api/perf_hooks.html#class-performancenodetiming

5. **PerformanceResourceTiming Class** - Network timing details (v18.2.0, v16.17.0)
   - Complete Web Performance API compatibility
   - Timing properties: `workerStart`, `redirectStart/End`, `fetchStart`, `domainLookupStart/End`, `connectStart/End`, `secureConnectionStart`, `requestStart`, `responseEnd`
   - Size properties: `transferSize`, `encodedBodySize`, `decodedBodySize`
   - Used for detailed network request profiling
   - https://nodejs.org/api/perf_hooks.html#class-performanceresourcetiming

6. **PerformanceMark and PerformanceMeasure** - Enhanced type safety
   - Generic type parameter `<T>` for custom detail objects
   - `PerformanceMark<T>` has `duration: 0` (point in time)
   - `PerformanceMeasure<T>` has variable duration (time span)
   - Both support custom `detail` property for user data

**New Functions:**

7. **createHistogram()** - Custom histogram creation (v15.9.0, v14.18.0)
   - Options: `lowest`, `highest` (number | bigint), `figures` (precision)
   - Returns `RecordableHistogram` for custom performance metrics
   - Enables fine-grained performance measurement
   - https://nodejs.org/api/perf_hooks.html#perf_hookscreatehistogramoptions

**Performance Object Enhancements:**

8. **Enhanced Performance Class**
   - `clearResourceTimings(name?)` - Clear specific resource timings
   - `timerify()` enhanced with histogram option: `Readonly<{histogram?: RecordableHistogram}>`
   - All timing methods return proper typed instances

9. **GC Constants Export** - Garbage collection monitoring
   - `constants.NODE_PERFORMANCE_GC_MAJOR` - Major GC
   - `constants.NODE_PERFORMANCE_GC_MINOR` - Minor/scavenge GC
   - `constants.NODE_PERFORMANCE_GC_INCREMENTAL` - Incremental marking GC
   - `constants.NODE_PERFORMANCE_GC_WEAKCB` - Weak callback processing
   - GC flags: `FLAGS_NO`, `FLAGS_CONSTRUCT_RETAINED`, `FLAGS_FORCED`, `FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING`, `FLAGS_ALL_AVAILABLE_GARBAGE`, `FLAGS_ALL_EXTERNAL_MEMORY`, `FLAGS_SCHEDULE_IDLE`
   - https://nodejs.org/api/perf_hooks.html#perf_hooksconstants

**Modern Flow Type Improvements:**

10. **Readonly Input Types** - Applied consistently
    - `PerformanceMarkOptions<T>`: `Readonly<{detail?, startTime?}>`
    - `PerformanceMeasureOptions<T>`: `Readonly<{detail?, duration?, end?, start?}>`
    - `PerformanceObserver.observe()`: `Readonly<{entryTypes?, type?, buffered?}>`
    - `monitorEventLoopDelay()`: `Readonly<{resolution?}>`
    - `createHistogram()`: `Readonly<{lowest?, highest?, figures?}>`
    - `timerify()` histogram option: `Readonly<{histogram?}>`

11. **Entry Type Safety** - Proper union type
    - `perf_hooks$EntryType`: `'function' | 'gc' | 'http' | 'http2' | 'mark' | 'measure' | 'navigation' | 'node' | 'resource'`
    - Used throughout for type-safe entry type filtering

12. **Export Type Aliases** - Better developer experience
    - All classes and interfaces exported as both types and values
    - Consistent `perf_hooks$` prefix for internal types
    - Clean module exports without duplication

**Observer Enhancements:**

13. **PerformanceObserver.observe()** - Flexible options (v16.0.0)
    - Support both `type` (single) and `entryTypes` (multiple) options
    - `buffered` option to include past entries
    - `takeRecords()` method for manual retrieval

**References:**
- Node.js perf_hooks module docs: https://nodejs.org/api/perf_hooks.html
- Web Performance API spec: https://w3c.github.io/performance-timeline/
- User Timing spec: https://w3c.github.io/user-timing/
- Resource Timing spec: https://w3c.github.io/resource-timing/

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: D89944490

fbshipit-source-id: 28e89ee27ce0150db063d6c3757defc3bba512c0
This commit is contained in:
Rob Hogan authored and meta-codesync[bot] committed 2026-01-06 11:54:53 -08:00
1 parent dcfe7f50f9
commit d19efcfae2
1 file changed
+200
+200
View File
@@ -2863,6 +2863,202 @@ declare module 'path' {
declare var win32: path$PlatformPath;
}
declare module 'perf_hooks' {
declare export type EntryType =
| 'function'
| 'gc'
| 'http'
| 'http2'
| 'mark'
| 'measure'
| 'navigation'
| 'node'
| 'resource';
declare export interface Histogram {
+count: number;
+countBigInt: bigint;
+exceeds: number;
+exceedsBigInt: bigint;
+max: number;
+maxBigInt: bigint;
+mean: number;
+min: number;
+minBigInt: bigint;
+stddev: number;
+percentiles: Map<number, number>;
+percentilesBigInt: Map<number, bigint>;
percentile(percentile: number): number;
percentileBigInt(percentile: number): bigint;
reset(): void;
}
declare export interface IntervalHistogram extends Histogram {
enable(): boolean;
disable(): boolean;
}
declare export interface RecordableHistogram extends Histogram {
record(val: number | bigint): void;
recordDelta(): void;
}
declare export class PerformanceEntry {
+duration: number;
+entryType: EntryType;
+name: string;
+startTime: number;
+detail?: mixed;
toJSON(): mixed;
}
declare export class PerformanceMark<T = mixed> extends PerformanceEntry {
+entryType: 'mark';
+duration: 0;
+detail?: T;
}
declare export class PerformanceMeasure<T = mixed> extends PerformanceEntry {
+entryType: 'measure';
+detail?: T;
}
declare export class PerformanceNodeEntry extends PerformanceEntry {
+entryType: 'node';
}
declare export class PerformanceNodeTiming extends PerformanceEntry {
+entryType: 'node';
+bootstrapComplete: number;
+environment: number;
+idleTime: number;
+loopExit: number;
+loopStart: number;
+nodeStart: number;
+v8Start: number;
}
declare export class PerformanceResourceTiming extends PerformanceEntry {
+entryType: 'resource';
+connectEnd: number;
+connectStart: number;
+decodedBodySize: number;
+domainLookupEnd: number;
+domainLookupStart: number;
+encodedBodySize: number;
+fetchStart: number;
+redirectEnd: number;
+redirectStart: number;
+requestStart: number;
+responseEnd: number;
+secureConnectionStart: number;
+transferSize: number;
+workerStart: number;
}
declare export class PerformanceObserverEntryList {
getEntries(): Array<PerformanceEntry>;
getEntriesByName(name: string, type?: EntryType): Array<PerformanceEntry>;
getEntriesByType(type: EntryType): Array<PerformanceEntry>;
}
declare export type PerformanceObserverCallback = (
list: PerformanceObserverEntryList,
observer: PerformanceObserver,
) => void;
declare export class PerformanceObserver {
static supportedEntryTypes: $ReadOnlyArray<EntryType>;
constructor(callback: PerformanceObserverCallback): this;
observe(
options: Readonly<{
entryTypes?: $ReadOnlyArray<EntryType>,
type?: EntryType,
buffered?: boolean,
}>,
): void;
disconnect(): void;
takeRecords(): Array<PerformanceEntry>;
}
declare export type EventLoopUtilization = {
+utilization: number,
+idle: number,
+active: number,
};
declare export type PerformanceMarkOptions<T = mixed> = Readonly<{
detail?: T,
startTime?: number,
}>;
declare export type PerformanceMeasureOptions<T = mixed> = Readonly<{
detail?: T,
duration?: number,
end?: number | string,
start?: number | string,
}>;
declare class Performance {
clearMarks(name?: string): void;
clearMeasures(name?: string): void;
clearResourceTimings(name?: string): void;
eventLoopUtilization(
elu1?: EventLoopUtilization,
elu2?: EventLoopUtilization,
): EventLoopUtilization;
getEntries(): Array<PerformanceEntry>;
getEntriesByName(name: string, type?: EntryType): Array<PerformanceEntry>;
getEntriesByType(type: EntryType): Array<PerformanceEntry>;
mark<T>(
name: string,
options?: PerformanceMarkOptions<T>,
): PerformanceMark<T>;
measure<T>(
name: string,
startMarkOrOptions?: string | PerformanceMeasureOptions<T>,
endMark?: string,
): PerformanceMeasure<T>;
+nodeTiming: PerformanceNodeTiming;
now(): number;
setResourceTimingBufferSize(maxSize: number): void;
+timeOrigin: number;
timerify<TArgs: Iterable<mixed>, TReturn>(
fn: (...TArgs) => TReturn,
options?: Readonly<{histogram?: RecordableHistogram}>,
): (...TArgs) => TReturn;
toJSON(): mixed;
}
declare export var performance: Performance;
declare export var constants: Readonly<{
NODE_PERFORMANCE_GC_MAJOR: number,
NODE_PERFORMANCE_GC_MINOR: number,
NODE_PERFORMANCE_GC_INCREMENTAL: number,
NODE_PERFORMANCE_GC_WEAKCB: number,
NODE_PERFORMANCE_GC_FLAGS_NO: number,
NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED: number,
NODE_PERFORMANCE_GC_FLAGS_FORCED: number,
NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING: number,
NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE: number,
NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY: number,
NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE: number,
}>;
declare export function monitorEventLoopDelay(
options?: Readonly<{resolution?: number}>,
): IntervalHistogram;
declare export function createHistogram(
options?: Readonly<{
lowest?: number | bigint,
highest?: number | bigint,
figures?: number,
}>,
): RecordableHistogram;
}
declare module 'punycode' {
declare function decode(string: string): string;
declare function encode(string: string): string;
@@ -4849,6 +5045,10 @@ declare module 'node:path' {
declare module.exports: $Exports<'path'>;
}
declare module 'node:perf_hooks' {
declare module.exports: $Exports<'perf_hooks'>;
}
declare module 'process' {
declare module.exports: Process;
}