@types/node
Version:
TypeScript definitions for node
622 lines (621 loc) • 24 kB
TypeScript
/**
* This module provides an implementation of a subset of the W3C [Web Performance APIs](https://w3c.github.io/perf-timing-primer/) as well as additional APIs for
* Node.js-specific performance measurements.
*
* Node.js supports the following [Web Performance APIs](https://w3c.github.io/perf-timing-primer/):
*
* * [High Resolution Time](https://www.w3.org/TR/hr-time-2)
* * [Performance Timeline](https://w3c.github.io/performance-timeline/)
* * [User Timing](https://www.w3.org/TR/user-timing/)
* * [Resource Timing](https://www.w3.org/TR/resource-timing-2/)
*
* ```js
* import { PerformanceObserver, performance } from 'node:perf_hooks';
*
* const obs = new PerformanceObserver((items) => {
* console.log(items.getEntries()[0].duration);
* performance.clearMarks();
* });
* obs.observe({ type: 'measure' });
* performance.measure('Start to Now');
*
* performance.mark('A');
* doSomeLongRunningProcess(() => {
* performance.measure('A to Now', 'A');
*
* performance.mark('B');
* performance.measure('A to B', 'A', 'B');
* });
* ```
* @see [source](https://github.com/nodejs/node/blob/v25.x/lib/perf_hooks.js)
*/
declare module "node:perf_hooks" {
import { InternalEventTargetEventProperties } from "node:events";
// #region web types
type EntryType =
| "dns" // Node.js only
| "function" // Node.js only
| "gc" // Node.js only
| "http2" // Node.js only
| "http" // Node.js only
| "mark" // available on the Web
| "measure" // available on the Web
| "net" // Node.js only
| "node" // Node.js only
| "resource"; // available on the Web
interface EventLoopUtilization {
idle: number;
active: number;
utilization: number;
}
interface ConnectionTimingInfo {
domainLookupStartTime: number;
domainLookupEndTime: number;
connectionStartTime: number;
connectionEndTime: number;
secureConnectionStartTime: number;
ALPNNegotiatedProtocol: string;
}
interface FetchTimingInfo {
startTime: number;
redirectStartTime: number;
redirectEndTime: number;
postRedirectStartTime: number;
finalServiceWorkerStartTime: number;
finalNetworkRequestStartTime: number;
finalNetworkResponseStartTime: number;
endTime: number;
finalConnectionTimingInfo: ConnectionTimingInfo | null;
encodedBodySize: number;
decodedBodySize: number;
}
type PerformanceEntryList = PerformanceEntry[];
interface PerformanceMarkOptions {
detail?: any;
startTime?: number;
}
interface PerformanceMeasureOptions {
detail?: any;
duration?: number;
end?: string | number;
start?: string | number;
}
interface PerformanceObserverCallback {
(entries: PerformanceObserverEntryList, observer: PerformanceObserver): void;
}
interface PerformanceObserverInit {
buffered?: boolean;
entryTypes?: EntryType[];
type?: EntryType;
}
interface PerformanceEventMap {
"resourcetimingbufferfull": Event;
}
interface Performance extends EventTarget, InternalEventTargetEventProperties<PerformanceEventMap> {
readonly nodeTiming: PerformanceNodeTiming;
readonly timeOrigin: number;
clearMarks(markName?: string): void;
clearMeasures(measureName?: string): void;
clearResourceTimings(resourceTimingName?: string): void;
getEntries(): PerformanceEntryList;
getEntriesByName(name: string, type?: EntryType): PerformanceEntryList;
getEntriesByType(type: EntryType): PerformanceEntryList;
mark(markName: string, markOptions?: PerformanceMarkOptions): PerformanceMark;
markResourceTiming(
timingInfo: FetchTimingInfo,
requestedUrl: string,
initiatorType: string,
global: unknown,
cacheMode: string,
bodyInfo: unknown,
responseStatus: number,
deliveryType?: string,
): PerformanceResourceTiming;
measure(measureName: string, startMark?: string, endMark?: string): PerformanceMeasure;
measure(measureName: string, options: PerformanceMeasureOptions, endMark?: string): PerformanceMeasure;
now(): number;
setResourceTimingBufferSize(maxSize: number): void;
toJSON(): any;
addEventListener<K extends keyof PerformanceEventMap>(
type: K,
listener: (ev: PerformanceEventMap[K]) => void,
options?: AddEventListenerOptions | boolean,
): void;
addEventListener(
type: string,
listener: EventListener | EventListenerObject,
options?: AddEventListenerOptions | boolean,
): void;
removeEventListener<K extends keyof PerformanceEventMap>(
type: K,
listener: (ev: PerformanceEventMap[K]) => void,
options?: EventListenerOptions | boolean,
): void;
removeEventListener(
type: string,
listener: EventListener | EventListenerObject,
options?: EventListenerOptions | boolean,
): void;
/**
* The `eventLoopUtilization()` method returns an object that contains the
* cumulative duration of time the event loop has been both idle and active as a
* high resolution milliseconds timer. The `utilization` value is the calculated
* Event Loop Utilization (ELU).
*
* If bootstrapping has not yet finished on the main thread the properties have
* the value of `0`. The ELU is immediately available on [Worker threads](https://nodejs.org/docs/latest-v25.x/api/worker_threads.html#worker-threads) since
* bootstrap happens within the event loop.
*
* Both `utilization1` and `utilization2` are optional parameters.
*
* If `utilization1` is passed, then the delta between the current call's `active`
* and `idle` times, as well as the corresponding `utilization` value are
* calculated and returned (similar to `process.hrtime()`).
*
* If `utilization1` and `utilization2` are both passed, then the delta is
* calculated between the two arguments. This is a convenience option because,
* unlike `process.hrtime()`, calculating the ELU is more complex than a
* single subtraction.
*
* ELU is similar to CPU utilization, except that it only measures event loop
* statistics and not CPU usage. It represents the percentage of time the event
* loop has spent outside the event loop's event provider (e.g. `epoll_wait`).
* No other CPU idle time is taken into consideration. The following is an example
* of how a mostly idle process will have a high ELU.
*
* ```js
* import { eventLoopUtilization } from 'node:perf_hooks';
* import { spawnSync } from 'node:child_process';
*
* setImmediate(() => {
* const elu = eventLoopUtilization();
* spawnSync('sleep', ['5']);
* console.log(eventLoopUtilization(elu).utilization);
* });
* ```
*
* Although the CPU is mostly idle while running this script, the value of
* `utilization` is `1`. This is because the call to
* `child_process.spawnSync()` blocks the event loop from proceeding.
*
* Passing in a user-defined object instead of the result of a previous call to
* `eventLoopUtilization()` will lead to undefined behavior. The return values
* are not guaranteed to reflect any correct state of the event loop.
* @since v14.10.0, v12.19.0
* @param utilization1 The result of a previous call to
* `eventLoopUtilization()`.
* @param utilization2 The result of a previous call to
* `eventLoopUtilization()` prior to `utilization1`.
*/
eventLoopUtilization(
utilization1?: EventLoopUtilization,
utilization2?: EventLoopUtilization,
): EventLoopUtilization;
/**
* _This property is an extension by Node.js. It is not available in Web browsers._
*
* Wraps a function within a new function that measures the running time of the
* wrapped function. A `PerformanceObserver` must be subscribed to the `'function'`
* event type in order for the timing details to be accessed.
*
* ```js
* import { performance, PerformanceObserver } from 'node:perf_hooks';
*
* function someFunction() {
* console.log('hello world');
* }
*
* const wrapped = performance.timerify(someFunction);
*
* const obs = new PerformanceObserver((list) => {
* console.log(list.getEntries()[0].duration);
*
* performance.clearMarks();
* performance.clearMeasures();
* obs.disconnect();
* });
* obs.observe({ entryTypes: ['function'] });
*
* // A performance timeline entry will be created
* wrapped();
* ```
*
* If the wrapped function returns a promise, a finally handler will be attached
* to the promise and the duration will be reported once the finally handler is
* invoked.
* @since v8.5.0
*/
timerify<T extends (...args: any[]) => any>(fn: T, options?: PerformanceTimerifyOptions): T;
}
var Performance: {
prototype: Performance;
new(): Performance;
};
interface PerformanceEntry {
readonly duration: number;
readonly entryType: EntryType;
readonly name: string;
readonly startTime: number;
toJSON(): any;
}
var PerformanceEntry: {
prototype: PerformanceEntry;
new(): PerformanceEntry;
};
interface PerformanceMark extends PerformanceEntry {
readonly detail: any;
readonly entryType: "mark";
}
var PerformanceMark: {
prototype: PerformanceMark;
new(markName: string, markOptions?: PerformanceMarkOptions): PerformanceMark;
};
interface PerformanceMeasure extends PerformanceEntry {
readonly detail: any;
readonly entryType: "measure";
}
var PerformanceMeasure: {
prototype: PerformanceMeasure;
new(): PerformanceMeasure;
};
interface PerformanceObserver {
disconnect(): void;
observe(options: PerformanceObserverInit): void;
takeRecords(): PerformanceEntryList;
}
var PerformanceObserver: {
prototype: PerformanceObserver;
new(callback: PerformanceObserverCallback): PerformanceObserver;
readonly supportedEntryTypes: readonly EntryType[];
};
interface PerformanceObserverEntryList {
getEntries(): PerformanceEntryList;
getEntriesByName(name: string, type?: EntryType): PerformanceEntryList;
getEntriesByType(type: EntryType): PerformanceEntryList;
}
var PerformanceObserverEntryList: {
prototype: PerformanceObserverEntryList;
new(): PerformanceObserverEntryList;
};
interface PerformanceResourceTiming extends PerformanceEntry {
readonly connectEnd: number;
readonly connectStart: number;
readonly decodedBodySize: number;
readonly domainLookupEnd: number;
readonly domainLookupStart: number;
readonly encodedBodySize: number;
readonly entryType: "resource";
readonly fetchStart: number;
readonly initiatorType: string;
readonly nextHopProtocol: string;
readonly redirectEnd: number;
readonly redirectStart: number;
readonly requestStart: number;
readonly responseEnd: number;
readonly responseStart: number;
readonly responseStatus: number;
readonly secureConnectionStart: number;
readonly transferSize: number;
readonly workerStart: number;
toJSON(): any;
}
var PerformanceResourceTiming: {
prototype: PerformanceResourceTiming;
new(): PerformanceResourceTiming;
};
var performance: Performance;
// #endregion
interface PerformanceTimerifyOptions {
/**
* A histogram object created using
* `perf_hooks.createHistogram()` that will record runtime durations in
* nanoseconds.
*/
histogram?: RecordableHistogram | undefined;
}
/**
* _This class is an extension by Node.js. It is not available in Web browsers._
*
* Provides detailed Node.js timing data.
*
* The constructor of this class is not exposed to users directly.
* @since v19.0.0
*/
class PerformanceNodeEntry extends PerformanceEntry {
/**
* Additional detail specific to the `entryType`.
* @since v16.0.0
*/
readonly detail: any;
readonly entryType: "dns" | "function" | "gc" | "http2" | "http" | "net" | "node";
}
interface UVMetrics {
/**
* Number of event loop iterations.
*/
readonly loopCount: number;
/**
* Number of events that have been processed by the event handler.
*/
readonly events: number;
/**
* Number of events that were waiting to be processed when the event provider was called.
*/
readonly eventsWaiting: number;
}
/**
* _This property is an extension by Node.js. It is not available in Web browsers._
*
* Provides timing details for Node.js itself. The constructor of this class
* is not exposed to users.
* @since v8.5.0
*/
interface PerformanceNodeTiming extends PerformanceEntry {
/**
* The high resolution millisecond timestamp at which the Node.js process
* completed bootstrapping. If bootstrapping has not yet finished, the property
* has the value of -1.
* @since v8.5.0
*/
readonly bootstrapComplete: number;
readonly entryType: "node";
/**
* The high resolution millisecond timestamp at which the Node.js environment was
* initialized.
* @since v8.5.0
*/
readonly environment: number;
/**
* The high resolution millisecond timestamp of the amount of time the event loop
* has been idle within the event loop's event provider (e.g. `epoll_wait`). This
* does not take CPU usage into consideration. If the event loop has not yet
* started (e.g., in the first tick of the main script), the property has the
* value of 0.
* @since v14.10.0, v12.19.0
*/
readonly idleTime: number;
/**
* The high resolution millisecond timestamp at which the Node.js event loop
* exited. If the event loop has not yet exited, the property has the value of -1\.
* It can only have a value of not -1 in a handler of the `'exit'` event.
* @since v8.5.0
*/
readonly loopExit: number;
/**
* The high resolution millisecond timestamp at which the Node.js event loop
* started. If the event loop has not yet started (e.g., in the first tick of the
* main script), the property has the value of -1.
* @since v8.5.0
*/
readonly loopStart: number;
/**
* The high resolution millisecond timestamp at which the Node.js process was initialized.
* @since v8.5.0
*/
readonly nodeStart: number;
/**
* This is a wrapper to the `uv_metrics_info` function.
* It returns the current set of event loop metrics.
*
* It is recommended to use this property inside a function whose execution was
* scheduled using `setImmediate` to avoid collecting metrics before finishing all
* operations scheduled during the current loop iteration.
* @since v22.8.0, v20.18.0
*/
readonly uvMetricsInfo: UVMetrics;
/**
* The high resolution millisecond timestamp at which the V8 platform was
* initialized.
* @since v8.5.0
*/
readonly v8Start: number;
}
namespace constants {
const NODE_PERFORMANCE_GC_MAJOR: number;
const NODE_PERFORMANCE_GC_MINOR: number;
const NODE_PERFORMANCE_GC_INCREMENTAL: number;
const NODE_PERFORMANCE_GC_WEAKCB: number;
const NODE_PERFORMANCE_GC_FLAGS_NO: number;
const NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED: number;
const NODE_PERFORMANCE_GC_FLAGS_FORCED: number;
const NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING: number;
const NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE: number;
const NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY: number;
const NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE: number;
}
interface EventLoopMonitorOptions {
/**
* The sampling rate in milliseconds.
* Must be greater than zero.
* @default 10
*/
resolution?: number | undefined;
}
interface Histogram {
/**
* The number of samples recorded by the histogram.
* @since v17.4.0, v16.14.0
*/
readonly count: number;
/**
* The number of samples recorded by the histogram.
* v17.4.0, v16.14.0
*/
readonly countBigInt: bigint;
/**
* The number of times the event loop delay exceeded the maximum 1 hour event
* loop delay threshold.
* @since v11.10.0
*/
readonly exceeds: number;
/**
* The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold.
* @since v17.4.0, v16.14.0
*/
readonly exceedsBigInt: bigint;
/**
* The maximum recorded event loop delay.
* @since v11.10.0
*/
readonly max: number;
/**
* The maximum recorded event loop delay.
* v17.4.0, v16.14.0
*/
readonly maxBigInt: number;
/**
* The mean of the recorded event loop delays.
* @since v11.10.0
*/
readonly mean: number;
/**
* The minimum recorded event loop delay.
* @since v11.10.0
*/
readonly min: number;
/**
* The minimum recorded event loop delay.
* v17.4.0, v16.14.0
*/
readonly minBigInt: bigint;
/**
* Returns the value at the given percentile.
* @since v11.10.0
* @param percentile A percentile value in the range (0, 100].
*/
percentile(percentile: number): number;
/**
* Returns the value at the given percentile.
* @since v17.4.0, v16.14.0
* @param percentile A percentile value in the range (0, 100].
*/
percentileBigInt(percentile: number): bigint;
/**
* Returns a `Map` object detailing the accumulated percentile distribution.
* @since v11.10.0
*/
readonly percentiles: Map<number, number>;
/**
* Returns a `Map` object detailing the accumulated percentile distribution.
* @since v17.4.0, v16.14.0
*/
readonly percentilesBigInt: Map<bigint, bigint>;
/**
* Resets the collected histogram data.
* @since v11.10.0
*/
reset(): void;
/**
* The standard deviation of the recorded event loop delays.
* @since v11.10.0
*/
readonly stddev: number;
}
interface IntervalHistogram extends Histogram {
/**
* Enables the update interval timer. Returns `true` if the timer was
* started, `false` if it was already started.
* @since v11.10.0
*/
enable(): boolean;
/**
* Disables the update interval timer. Returns `true` if the timer was
* stopped, `false` if it was already stopped.
* @since v11.10.0
*/
disable(): boolean;
/**
* Disables the update interval timer when the histogram is disposed.
*
* ```js
* const { monitorEventLoopDelay } = require('node:perf_hooks');
* {
* using hist = monitorEventLoopDelay({ resolution: 20 });
* hist.enable();
* // The histogram will be disabled when the block is exited.
* }
* ```
* @since v24.2.0
*/
[Symbol.dispose](): void;
}
interface RecordableHistogram extends Histogram {
/**
* @since v15.9.0, v14.18.0
* @param val The amount to record in the histogram.
*/
record(val: number | bigint): void;
/**
* Calculates the amount of time (in nanoseconds) that has passed since the
* previous call to `recordDelta()` and records that amount in the histogram.
* @since v15.9.0, v14.18.0
*/
recordDelta(): void;
/**
* Adds the values from `other` to this histogram.
* @since v17.4.0, v16.14.0
*/
add(other: RecordableHistogram): void;
}
/**
* _This property is an extension by Node.js. It is not available in Web browsers._
*
* Creates an `IntervalHistogram` object that samples and reports the event loop
* delay over time. The delays will be reported in nanoseconds.
*
* Using a timer to detect approximate event loop delay works because the
* execution of timers is tied specifically to the lifecycle of the libuv
* event loop. That is, a delay in the loop will cause a delay in the execution
* of the timer, and those delays are specifically what this API is intended to
* detect.
*
* ```js
* import { monitorEventLoopDelay } from 'node:perf_hooks';
* const h = monitorEventLoopDelay({ resolution: 20 });
* h.enable();
* // Do something.
* h.disable();
* console.log(h.min);
* console.log(h.max);
* console.log(h.mean);
* console.log(h.stddev);
* console.log(h.percentiles);
* console.log(h.percentile(50));
* console.log(h.percentile(99));
* ```
* @since v11.10.0
*/
function monitorEventLoopDelay(options?: EventLoopMonitorOptions): IntervalHistogram;
interface CreateHistogramOptions {
/**
* The minimum recordable value. Must be an integer value greater than 0.
* @default 1
*/
lowest?: number | bigint | undefined;
/**
* The maximum recordable value. Must be an integer value greater than min.
* @default Number.MAX_SAFE_INTEGER
*/
highest?: number | bigint | undefined;
/**
* The number of accuracy digits. Must be a number between 1 and 5.
* @default 3
*/
figures?: number | undefined;
}
/**
* Returns a `RecordableHistogram`.
* @since v15.9.0, v14.18.0
*/
function createHistogram(options?: CreateHistogramOptions): RecordableHistogram;
// TODO: remove these in a future major
/** @deprecated Use the canonical `PerformanceMarkOptions` instead. */
interface MarkOptions extends PerformanceMarkOptions {}
/** @deprecated Use the canonical `PerformanceMeasureOptions` instead. */
interface MeasureOptions extends PerformanceMeasureOptions {}
/** @deprecated Use `PerformanceTimerifyOptions` instead. */
interface TimerifyOptions extends PerformanceTimerifyOptions {}
}
declare module "perf_hooks" {
export * from "node:perf_hooks";
}