Implementation:Puppeteer Puppeteer Deferred
| Property | Value |
|---|---|
| sources | packages/puppeteer-core/src/util/Deferred.ts |
| domains | Utility, Async Primitives |
| last_updated | 2026-02-12 00:00 GMT |
Overview
Description
The Deferred class provides a deferred promise abstraction for Puppeteer's internal asynchronous operations. It creates a promise whose resolve and reject functions are exposed externally, allowing callers to settle the promise from outside the executor. An optional timeout mechanism automatically rejects the deferred with a TimeoutError if it is not settled within a specified duration. This pattern is used extensively throughout Puppeteer's internals for coordinating asynchronous operations such as waiting for page navigation, protocol responses, and event-based flows.
The class exposes a static create factory method for construction and a static race method that behaves similarly to Promise.race but properly cleans up timeout timers on deferred instances to prevent Node.js event loop stalling.
Usage
Deferred is used internally by Puppeteer to manage asynchronous coordination with optional timeouts. It is not part of the public API. Common usage includes creating deferred objects for operations that must complete within a timeout window, and racing multiple deferred promises against each other.
Code Reference
Source Location
packages/puppeteer-core/src/util/Deferred.ts
Signature
export interface DeferredOptions {
message: string;
timeout: number;
}
export class Deferred<T, V extends Error = Error> {
static create<R, X extends Error = Error>(opts?: DeferredOptions): Deferred<R, X>;
static async race<R>(awaitables: Array<Promise<R> | Deferred<R>>): Promise<R>;
constructor(opts?: DeferredOptions);
resolve(value: T): void;
reject(error: V | TimeoutError): void;
resolved(): boolean;
finished(): boolean;
value(): T | V | TimeoutError | undefined;
valueOrThrow(): Promise<T>;
}
Import
import {Deferred} from '../util/Deferred.js';
I/O Contract
| Parameter | Type | Description |
|---|---|---|
| opts.message | string |
The error message used if the deferred times out |
| opts.timeout | number |
Timeout in milliseconds; ignored if not greater than 0 |
| Return | Type | Description |
|---|---|---|
| Deferred instance | Deferred<T, V> |
A deferred object with externally accessible resolve/reject |
| valueOrThrow() | Promise<T> |
Resolves with the value or throws the rejection error |
| race() | Promise<R> |
Resolves with the first settled value; cleans up timeouts for remaining deferreds |
Usage Examples
// Create a deferred with a 5-second timeout
const deferred = Deferred.create<string>({
message: 'Operation timed out',
timeout: 5000,
});
// Resolve the deferred from an external event
someEventEmitter.on('data', (data: string) => {
deferred.resolve(data);
});
// Await the result (will throw TimeoutError if not resolved in 5s)
const result = await deferred.valueOrThrow();
// Race multiple deferreds; timeout timers are cleaned up automatically
const result = await Deferred.race([
deferred1,
deferred2,
someRegularPromise,
]);