This page documents the TypeScript type definition files that provide types for browser DOM APIs and Web Worker APIs. These auto-generated declaration files enable type-safe usage of web platform APIs in TypeScript code.
For information about ECMAScript standard library types (Object, Array, Promise, etc.), see ECMAScript Standard Libraries.
The DOM and Web Worker API type definitions provide comprehensive TypeScript interfaces for:
for...of loops.These type definitions are automatically generated from authoritative web specifications and maintained separately from hand-written ECMAScript standard library types.
Sources: src/lib/dom.generated.d.ts1-10 src/lib/webworker.generated.d.ts1-10
DOM and WebWorker Type Definition File Structure
The type definitions are organized into four main files:
| File | Purpose | Size | Auto-generated |
|---|---|---|---|
dom.generated.d.ts | Main browser window/document APIs | 4000+ interfaces | Yes |
webworker.generated.d.ts | Web Worker context APIs | Subset of DOM | Yes |
dom.iterable.generated.d.ts | Backwards compatibility stub | Empty | Yes |
webworker.iterable.generated.d.ts | Backwards compatibility stub | Empty | Yes |
The .iterable.generated.d.ts files are legacy compatibility stubs—their contents have been merged into the main files.
Sources: src/lib/dom.generated.d.ts1-6 src/lib/webworker.generated.d.ts1-6 src/lib/dom.iterable.generated.d.ts1-3 src/lib/webworker.iterable.generated.d.ts1-3
The dom.generated.d.ts file provides type definitions for all browser window and document APIs, organized into several major categories:
Major DOM API Categories
Sources: src/lib/dom.generated.d.ts1-100
DOM type definitions follow consistent patterns:
DOM Type Definition Structure
Interface Options Pattern: Configuration objects for API methods are defined as interfaces with optional properties:
Element Tag Name Mapping: TypeScript uses mapped types to provide precise types when creating or querying elements by tag name:
This pattern enables type-safe element creation and querying, as demonstrated in test cases where document.getElementsByTagName("a") correctly returns HTMLCollectionOf<HTMLAnchorElement>.
Sources: src/lib/dom.generated.d.ts8-16 tests/baselines/reference/modularizeLibrary_Dom.iterable.types4-26 tests/baselines/reference/intersectionsOfLargeUnions.types42-88
The DOM type definitions declare numerous global interfaces available in the browser window context:
Global Browser Objects
The Window interface extends multiple mixins and provides access to all browser window APIs. TypeScript users can access these globals directly without imports.
Sources: tests/baselines/reference/globalThisBlockscopedProperties.types73-88
The webworker.generated.d.ts file contains type definitions for APIs available in Web Worker contexts. Workers have a restricted API surface compared to the main window context. For instance, they lack access to the Document and HTMLElement APIs but share low-level APIs like Crypto and Fetch.
Worker vs Window API Availability
Sources: src/lib/webworker.generated.d.ts1-100
Worker type definitions include interfaces specific to different worker contexts:
| Worker Type | Global Scope Interface | Use Case |
|---|---|---|
| Dedicated Worker | DedicatedWorkerGlobalScope | Background computation in single page |
| Shared Worker | SharedWorkerGlobalScope | Shared background processing across tabs |
| Service Worker | ServiceWorkerGlobalScope | Network proxying, offline support |
Service Worker Specific Types: The worker definitions include Service Worker APIs like FetchEvent, ExtendableEvent, and CacheStorage:
Sources: src/lib/webworker.generated.d.ts316-323
DOM Type Definition Generation Process
The DOM and WebWorker type definition files are auto-generated from web specifications rather than hand-written. This ensures accuracy and completeness across the 4000+ interfaces of the web platform. The generation process occurs in the TypeScript-DOM-lib-generator project, which parses WebIDL and produces the .d.ts files found in src/lib/.
File Comments: Each generated file includes a reference comment indicating its dependencies:
Sources: src/lib/dom.generated.d.ts1-6 src/lib/webworker.generated.d.ts1-6
Modern DOM collections (like NodeList or HTMLCollection) implement the iterable protocol. TypeScript provides support for iterating over these using for...of loops.
DOM Collection Iteration Support
The iterable functionality is integrated into the main dom.generated.d.ts and webworker.generated.d.ts files. The separate .iterable.generated.d.ts files exist only for backwards compatibility.
Usage Example:
Sources: src/lib/dom.iterable.generated.d.ts1-3 src/lib/webworker.iterable.generated.d.ts1-3 tests/baselines/reference/modularizeLibrary_Dom.iterable.types4-26
DOM Library Integration with Compiler
TypeScript projects specify library inclusion via tsconfig.json. The "dom" and "webworker" options are typically mutually exclusive as they define different global scopes.
The compiler uses these definitions to validate API usage and provide IntelliSense. When a name is missing, the compiler may suggest a DOM API name from the library:
Sources: tests/baselines/reference/baseCheck.errors.txt1-24 tests/baselines/reference/globalThisBlockscopedProperties.types107-153
The compiler can perform deep inference on complex DOM objects like XMLHttpRequest:
The type checker recursively maps the properties of XMLHttpRequest, including nested structures like responseXML.
Sources: tests/baselines/reference/mappedTypeRecursiveInference.types155-160 tests/baselines/reference/mappedTypeRecursiveInference.errors.txt1-10
DOM element tag maps involve large unions that the compiler must resolve when performing property access:
Sources: tests/baselines/reference/intersectionsOfLargeUnions.types90-124 tests/baselines/reference/intersectionsOfLargeUnions2.errors.txt1-4
Refresh this wiki