From d19efcfae2a8988b67bf5dd3e6f75b0c8966a572 Mon Sep 17 00:00:00 2001 From: Rob Hogan Date: Tue, 6 Jan 2026 11:54:53 -0800 Subject: [PATCH] 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 `` for custom detail objects - `PerformanceMark` has `duration: 0` (point in time) - `PerformanceMeasure` 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`: `Readonly<{detail?, startTime?}>` - `PerformanceMeasureOptions`: `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 --- flow-typed/environment/node.js | 200 +++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) diff --git a/flow-typed/environment/node.js b/flow-typed/environment/node.js index 40987554080..949a3382b9e 100644 --- a/flow-typed/environment/node.js +++ b/flow-typed/environment/node.js @@ -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; + +percentilesBigInt: Map; + 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 extends PerformanceEntry { + +entryType: 'mark'; + +duration: 0; + +detail?: T; + } + + declare export class PerformanceMeasure 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; + getEntriesByName(name: string, type?: EntryType): Array; + getEntriesByType(type: EntryType): Array; + } + + declare export type PerformanceObserverCallback = ( + list: PerformanceObserverEntryList, + observer: PerformanceObserver, + ) => void; + + declare export class PerformanceObserver { + static supportedEntryTypes: $ReadOnlyArray; + constructor(callback: PerformanceObserverCallback): this; + observe( + options: Readonly<{ + entryTypes?: $ReadOnlyArray, + type?: EntryType, + buffered?: boolean, + }>, + ): void; + disconnect(): void; + takeRecords(): Array; + } + + declare export type EventLoopUtilization = { + +utilization: number, + +idle: number, + +active: number, + }; + + declare export type PerformanceMarkOptions = Readonly<{ + detail?: T, + startTime?: number, + }>; + + declare export type PerformanceMeasureOptions = 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; + getEntriesByName(name: string, type?: EntryType): Array; + getEntriesByType(type: EntryType): Array; + mark( + name: string, + options?: PerformanceMarkOptions, + ): PerformanceMark; + measure( + name: string, + startMarkOrOptions?: string | PerformanceMeasureOptions, + endMark?: string, + ): PerformanceMeasure; + +nodeTiming: PerformanceNodeTiming; + now(): number; + setResourceTimingBufferSize(maxSize: number): void; + +timeOrigin: number; + timerify, 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; }