Implementation:Puppeteer Puppeteer Common Types

Property	Value
sources	packages/puppeteer-core/src/common/types.ts
domains	Type System, Core Infrastructure, TypeScript Utilities
last_updated	2026-02-12 00:00 GMT

Overview

Description

Common Types is a module that defines the foundational TypeScript type aliases, interfaces, and utility types used throughout the Puppeteer codebase. These types provide type-safe abstractions for working with element handles, evaluation functions, and async patterns.

The module defines the following types and interfaces:

Public types:

• AwaitablePredicate<T> -- A predicate function that returns a boolean or Promise of boolean for a given value.
• Moveable -- An interface for resources that support the move() pattern for ownership transfer when using the using keyword.
• AwaitableIterable<T> -- A union of Iterable<T> | AsyncIterable<T> for collections that may be sync or async.
• Awaitable<T> -- A union of T | PromiseLike<T> for values that may be sync or async.
• HandleFor<T> -- A conditional type that maps Node types to ElementHandle<T> and other types to JSHandle<T>.
• HandleOr<T> -- A union of HandleFor<T> | JSHandle<T> | T for parameters that accept either a handle or a raw value.
• FlattenHandle<T> -- Extracts the inner type from a HandleOr<T>.
• InnerParams<T> -- Maps a tuple of HandleOr types to their flattened inner types.
• ElementFor<TagName> -- Maps HTML/SVG tag names to their corresponding element interface types.
• EvaluateFunc<T> -- A function type for page.evaluate callbacks that takes inner params and returns an Awaitable<unknown>.
• EvaluateFuncWith<V, T> -- Similar to EvaluateFunc but with a leading V parameter (used for evaluateHandle with a context value).
• NodeFor<ComplexSelector> -- Uses the typed-query-selector library's ParseSelector to infer the element type from a CSS selector string at the type level.

Internal types:

• Disposed -- An interface with a disposed boolean getter for tracking disposal state.
• BindingPayload -- Describes the shape of a binding payload (type, name, sequence number, args, trivial flag).
• AwaitableIterator<T> -- A union of Iterator<T> | AsyncIterator<T>.
• FlattenLazyArg<T> -- Extracts the inner type from a LazyArg<T>.
• InnerLazyParams<T> -- Maps a tuple of potentially lazy arg types to their flattened types.

Usage

These types are imported extensively throughout Puppeteer's source code to provide type safety for element queries, function evaluations, and async iteration patterns. They are also re-exported in Puppeteer's public API for use in user TypeScript code.

Code Reference

Source Location

packages/puppeteer-core/src/common/types.ts

Signature

export type AwaitablePredicate<T> = (value: T) => Awaitable<boolean>;

export interface Moveable {
  move(): this;
}

export interface Disposed {
  get disposed(): boolean;
}

export interface BindingPayload {
  type: string;
  name: string;
  seq: number;
  args: unknown[];
  isTrivial: boolean;
}

export type AwaitableIterator<T> = Iterator<T> | AsyncIterator<T>;
export type AwaitableIterable<T> = Iterable<T> | AsyncIterable<T>;
export type Awaitable<T> = T | PromiseLike<T>;
export type HandleFor<T> = T extends Node ? ElementHandle<T> : JSHandle<T>;
export type HandleOr<T> = HandleFor<T> | JSHandle<T> | T;
export type FlattenHandle<T> = T extends HandleOr<infer U> ? U : never;
export type FlattenLazyArg<T> = T extends LazyArg<infer U> ? U : T;
export type InnerLazyParams<T extends unknown[]> = { [K in keyof T]: FlattenLazyArg<T[K]> };
export type InnerParams<T extends unknown[]> = { [K in keyof T]: FlattenHandle<T[K]> };
export type ElementFor<TagName extends keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap> = ...;
export type EvaluateFunc<T extends unknown[]> = (...params: InnerParams<T>) => Awaitable<unknown>;
export type EvaluateFuncWith<V, T extends unknown[]> = (...params: [V, ...InnerParams<T>]) => Awaitable<unknown>;
export type NodeFor<ComplexSelector extends string> = ParseSelector<ComplexSelector>;

Import

import type {
  Awaitable,
  AwaitableIterable,
  HandleFor,
  HandleOr,
  EvaluateFunc,
  EvaluateFuncWith,
  NodeFor,
  ElementFor,
  InnerParams,
  Moveable,
} from 'puppeteer-core/lib/esm/puppeteer/common/types.js';

I/O Contract

Type	Purpose	Key Constraint
Awaitable<T>	Accept sync or async values	PromiseLike<T>
AwaitableIterable<T>	Accept sync or async iterables	AsyncIterable<T>
HandleFor<T>	Map values to correct handle type	Node -> ElementHandle, other -> JSHandle
HandleOr<T>	Accept handle or raw value	JSHandle<T> | T
EvaluateFunc<T>	Type-safe evaluate callback	Params are flattened from handles
NodeFor<Selector>	Infer element type from CSS selector	Uses ParseSelector from typed-query-selector

Usage Examples

import type {Awaitable, HandleFor, EvaluateFunc, NodeFor} from 'puppeteer';

// Awaitable allows both sync and async return values
function processValue(val: Awaitable<string>) {
  // val can be string or Promise<string>
}

// HandleFor maps types to the correct handle
type DivHandle = HandleFor<HTMLDivElement>; // ElementHandle<HTMLDivElement>
type NumberHandle = HandleFor<number>;       // JSHandle<number>

// NodeFor infers element types from selectors
type DivNode = NodeFor<'div'>;              // HTMLDivElement
type InputNode = NodeFor<'input'>;          // HTMLInputElement

// EvaluateFunc provides type-safe evaluation
const fn: EvaluateFunc<[HandleFor<HTMLDivElement>]> = (div) => {
  return div.textContent; // div is typed as HTMLDivElement
};

// Using HandleOr in function signatures
async function clickElement(target: HandleOr<Element>) {
  // target can be an ElementHandle, JSHandle, or raw Element
}

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime