This page documents the ECMAScript standard library declaration files shipped with TypeScript — from es5.d.ts through esnext — covering their organization, what each file contains, and how the lib compiler option selects which files are included in a compilation. For DOM and Web Worker API declarations, see DOM and Web Worker APIs. For an overview of all standard library files and how the lib option is processed by the compiler, see Standard Library.
All ECMAScript standard library sources live in src/lib/. The built output files are placed in the lib/ directory at the repo root and are prefixed with lib. (e.g. lib.es5.d.ts, lib.es2015.d.ts). Source files use the unprefixed name (e.g. es5.d.ts).
There are two categories of files:
es2015.d.ts does nothing but emit /// <reference lib="..."> directives. They are the values you pass to the lib compiler option.es2015.collection.d.ts declares Map, Set, WeakMap, and WeakSet.es5.d.ts is the only version file that is monolithic — it contains all ES5 declarations directly rather than delegating to sub-files.
| Pattern | Example | Meaning |
|---|---|---|
es<year>.d.ts | es2017.d.ts | Rollup for the entire version |
es<year>.<feature>.d.ts | es2017.object.d.ts | Single feature area within a version |
es<year>.full.d.ts | es2019.full.d.ts | Rollup including DOM and WebWorker libs |
esnext.<feature>.d.ts | esnext.array.d.ts | Proposal-stage features |
Sources: src/lib/es2015.d.ts1-10 src/lib/es2017.d.ts1-8 src/lib/es2018.d.ts1-6 src/lib/es2019.full.d.ts1-5
Each rollup file references the previous version, forming a chain. When lib: ["es2018"] is set, the compiler transitively includes every prior version's declarations.
ECMAScript Version Dependency Chain
Each arrow represents a /// <reference lib="..." /> directive at the top of the rollup file. For example, es2017.d.ts begins with /// <reference lib="es2016" />.
Sources: src/lib/es2015.d.ts1-10 src/lib/es2017.d.ts1-8 src/lib/es2018.d.ts1-6
es5.d.tses5.d.ts is the base layer included by every other version. It is a single large file and is monolithic rather than split by feature.
The file opens with two references outside the ES version chain:
/// <reference lib="decorators" />
/// <reference lib="decorators.legacy" />
These pull in TypeScript's decorator-related declarations.
Declared at the top of es5.d.ts:
| Declaration | Description |
|---|---|
NaN, Infinity | Primitive global values |
eval(x) | Evaluates JavaScript code |
parseInt(string, radix?) | Parses a string as an integer |
parseFloat(string) | Parses a string as a float |
isNaN(number) | NaN check |
isFinite(number) | Finite check |
decodeURI(encodedURI) | URI decoding |
decodeURIComponent(encodedURIComponent) | URI component decoding |
encodeURI(uri) | URI encoding |
encodeURIComponent(uriComponent) | URI component encoding |
escape(string) | (deprecated) |
unescape(string) | (deprecated) |
Sources: src/lib/es5.d.ts8-80
Key interfaces in es5.d.ts
Sources: src/lib/es5.d.ts82-900
es5.d.ts defines the built-in TypeScript utility types that are available in every compilation:
| Utility Type | Purpose |
|---|---|
Partial<T> | All properties optional |
Required<T> | All properties required |
Readonly<T> | All properties readonly |
Pick<T, K> | Select subset of properties |
Omit<T, K> | Exclude subset of properties |
Record<K, T> | Map keys to values |
Exclude<T, U> | Remove types from union |
Extract<T, U> | Keep matching types from union |
NonNullable<T> | Remove null and undefined |
ReturnType<T> | Return type of a function |
InstanceType<T> | Instance type of a constructor |
Parameters<T> | Parameter types as a tuple |
ConstructorParameters<T> | Constructor parameter types |
ThisParameterType<T> | The this parameter type |
OmitThisParameter<T> | Remove this from function type |
Awaited<T> | Recursively unwrapped Promise type |
NoInfer<T> | Prevents type inference |
These types are declared via type aliases and use TypeScript-specific conditional type syntax. They appear near the end of es5.d.ts.
Sources: src/lib/es5.d.ts303-312
ES2015 uses the largest set of feature sub-files of any version. The rollup es2015.d.ts references nine sub-files plus es5:
ES2015 Feature File Breakdown
Sources: src/lib/es2015.d.ts1-10
es2015.core.d.tsAugments existing ES5 interfaces with new methods introduced in ES2015:
| Interface augmented | New members |
|---|---|
Array<T> | find, findIndex, fill, copyWithin |
ArrayConstructor | from, of |
String | codePointAt, includes, endsWith, normalize, repeat, startsWith, anchor, big, bold, etc. (deprecated HTML wrapper methods) |
StringConstructor | fromCodePoint, raw |
Math | clz32, imul, sign, log10, log2, log1p, expm1, cosh, sinh, tanh, acosh, asinh, atanh, hypot, trunc, fround, cbrt |
NumberConstructor | isFinite, isInteger, isNaN, isSafeInteger, EPSILON, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, parseFloat, parseInt |
ObjectConstructor | assign, getOwnPropertySymbols, is, setPrototypeOf |
RegExp | flags, sticky, unicode |
Function | name (readonly) |
Sources: src/lib/es2015.core.d.ts1-580
es2015.collection.d.tsIntroduces the keyed collection types:
| Interface | Description |
|---|---|
Map<K, V> | Key-value map with insertion order |
MapConstructor | Constructor for Map |
ReadonlyMap<K, V> | Read-only view of a Map |
WeakMap<K, V> | Map with weakly-held keys |
WeakMapConstructor | Constructor for WeakMap |
Set<T> | Unique value collection |
SetConstructor | Constructor for Set |
ReadonlySet<T> | Read-only view of a Set |
WeakSet<T> | Set with weakly-held values |
WeakSetConstructor | Constructor for WeakSet |
Sources: src/lib/es2015.collection.d.ts1-134
es2015.iterable.d.tsAdds the iterator protocol and makes built-in types iterable. Depends on es2015.symbol for Symbol.iterator.
Key declarations:
| Type | Description |
|---|---|
IteratorYieldResult<TYield> | { done?: false; value: TYield } |
IteratorReturnResult<TReturn> | { done: true; value: TReturn } |
IteratorResult<T, TReturn> | Union of yield and return results |
Iterator<T, TReturn, TNext> | Interface for iterator objects |
Iterable<T> | <FileRef file-url="https://github.com/microsoft/TypeScript/blob/0c2c7a35/Symbol.iterator" undefined file-path="Symbol.iterator">Hii</FileRef>: Iterator<T> |
IterableIterator<T> | Both iterable and iterator |
IteratorObject<T> | Runtime-produced iterators from Iterator.prototype |
ArrayIterator<T> | Iterators produced by Array, Map, Set |
BuiltinIteratorReturn | intrinsic — resolves to undefined or any depending on strictBuiltInIteratorReturn |
The BuiltinIteratorReturn type uses the intrinsic keyword, a TypeScript-internal mechanism:
Sources: src/lib/es2015.iterable.d.ts1-587
es2015.symbol.d.tsDeclares the SymbolConstructor interface with the Symbol function itself and its for and keyFor static methods.
Sources: src/lib/es2015.symbol.d.ts1-35
es2015.symbol.wellknown.d.tsAugments SymbolConstructor with the well-known symbols and augments affected interfaces:
| Symbol | Used by |
|---|---|
Symbol.hasInstance | instanceof |
Symbol.isConcatSpreadable | Array.prototype.concat |
Symbol.iterator | for...of |
Symbol.match | String.prototype.match |
Symbol.replace | String.prototype.replace |
Symbol.search | String.prototype.search |
Symbol.species | Derived object construction |
Symbol.split | String.prototype.split |
Symbol.toPrimitive | ToPrimitive abstract op |
Symbol.toStringTag | Object.prototype.toString |
Symbol.unscopables | with statement |
Sources: src/lib/es2015.symbol.wellknown.d.ts1-309
es2015.proxy.d.tsDeclares ProxyHandler<T>, ProxyConstructor, and var Proxy.
ProxyHandler<T> provides typed trap methods: apply, construct, defineProperty, deleteProperty, get, getOwnPropertyDescriptor, getPrototypeOf, has, isExtensible, ownKeys, preventExtensions, set, setPrototypeOf.
Sources: src/lib/es2015.proxy.d.ts1-110
es2015.reflect.d.tsDeclares the Reflect namespace with typed function overloads for all reflect operations, closely mirroring the ProxyHandler trap signatures.
Sources: src/lib/es2015.reflect.d.ts1-126
Starting from ES2016, each version file references the prior version and adds a small set of feature sub-files.
| Version | Rollup References | Key Additions |
|---|---|---|
| ES2016 | es2015 | es2016.array.include — Array.prototype.includes |
| ES2017 | es2016 | es2017.object (entries/values/fromEntries), es2017.string (padStart/padEnd), es2017.sharedmemory (SharedArrayBuffer, Atomics), es2017.typedarrays, es2017.arraybuffer, es2017.date, es2017.intl |
| ES2018 | es2017 | es2018.asynciterable, es2018.asyncgenerator, es2018.promise (finally), es2018.regexp (dotAll, named groups), es2018.intl |
| ES2019 | es2018 | es2019.array (flat, flatMap), es2019.object (fromEntries), es2019.string (trimStart/trimEnd), es2019.symbol (description) |
| ES2020 | es2019 | es2020.bigint (BigInt, BigInt64Array, BigUint64Array), es2020.promise (allSettled), es2020.string (matchAll), es2020.symbol.wellknown, es2020.intl, es2020.number, es2020.sharedmemory |
| ES2021 | es2020 | es2021.promise (any), es2021.string (replaceAll), es2021.weakref (WeakRef, FinalizationRegistry), es2021.intl |
| ES2022 | es2021 | es2022.array (at, findLast), es2022.error (cause), es2022.object (hasOwn), es2022.string (at), es2022.regexp (hasIndices), es2022.sharedmemory, es2022.intl |
| ES2023 | es2022 | es2023.array (toSorted, toReversed, with, findLast), es2023.collection (Map.groupBy, Object.groupBy), es2023.intl |
| ESNext | es2023 | Staging-area features; content changes as proposals advance |
Sources: src/lib/es2017.d.ts1-8 src/lib/es2018.d.ts1-6 src/lib/es2019.symbol.d.ts1-6 src/lib/es2020.bigint.d.ts1-125
es2019.symbol.d.ts ExampleThis is a small file that augments Symbol with one property:
es2020.bigint.d.ts ExampleDeclares:
BigIntToLocaleStringOptions — options interface for locale-specific BigInt formattingBigInt interface — toString, toLocaleString, valueOf, [Symbol.toStringTag]BigIntConstructor — asIntN, asUintN static methodsBigInt64Array and BigUint64Array — full typed array interfaces with all standard typed array methodsBigInt64ArrayConstructor / BigUint64ArrayConstructorSources: src/lib/es2020.bigint.d.ts1-416
full VariantsFiles suffixed with .full.d.ts (e.g., es2019.full.d.ts) bundle the ECMAScript declarations together with the DOM and WebWorker libraries. These are used as the default libs when you set target without explicitly specifying lib.
Full vs. Non-full Selection
Sources: src/lib/es2019.full.d.ts1-5
lib Compiler OptionThe compiler maps the lib option values to physical files. The mapping is maintained in src/compiler/commandLineParser.ts via a libEntries table. Each entry has a lib name (case-insensitive) and maps to a filename in the built lib/ directory.
Lib Name to File Mapping
When lib is not specified, TypeScript infers a default lib set from target:
target | Default lib (approximate) |
|---|---|
"es3" | es5, dom, scripthost |
"es5" | es5, dom, dom.iterable, scripthost |
"es2015" | es2015.full (includes es2015 + dom + dom.iterable) |
"es2017" | es2017.full |
"es2020" | es2020.full |
"esnext" | esnext.full |
When lib is specified explicitly, the defaults are entirely replaced — no automatic dom is added unless you include it yourself.
You can mix version rollups and individual feature libs:
This lets you target an older runtime while still using specific newer APIs (assuming a polyfill provides them at runtime).
The /// <reference lib="..." /> directive at the top of files is how the lib chain is assembled. The compiler resolves these directives during program creation (see Program and Compilation).
When processing a lib reference:
libEntries mapping..d.ts file in the lib directory.SourceFile with isDeclarationFile: true./// <reference lib="..." /> in that file are recursively resolved.This means that writing /// <reference lib="es2015.iterable" /> in a user file, or specifying "lib": ["es2015.iterable"] in tsconfig, produces exactly the same effect as if you had written /// <reference lib="es2015.symbol" /> first (because es2015.iterable.d.ts references es2015.symbol).
Triple-slash Reference Resolution Flow
Sources: src/lib/es2015.iterable.d.ts1-2 src/lib/es2015.symbol.wellknown.d.ts1-2
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.