Global Type Augmentation

Global augmentation extends the TypeScript description of global objects from within a module. It is appropriate for a global property that really exists, but it must match runtime setup. Keep augmentations narrow so they do not conceal missing dependencies.

Reading the code: export {} makes this file a module. declare global adds the method to Array's type description; assigning to Array.prototype supplies the runtime implementation. One call returns 10 and the empty array returns undefined.

Keep the boundary clear: Augmenting a global interface without installing the corresponding runtime behavior causes missing-method errors.

Save the code as global-type-augmentation.ts. The result below was captured after compiling this exact example with strict TypeScript checking and executing the emitted JavaScript in Node.js.

TypeScript code

export {};
declare global { interface Array<T> { firstOrUndefined(): T | undefined } }
Array.prototype.firstOrUndefined = function <T>(this: T[]): T | undefined { return this[0]; };
console.log([10, 20].firstOrUndefined());
console.log([].firstOrUndefined());

Verified output

10
undefined

Build: npx tsc --strict --target es2022 --module commonjs --lib es2022,dom,esnext.disposable global-type-augmentation.ts; run: node global-type-augmentation.js. The exact filename may be changed freely. When a multi-file project exists, prefer its tsconfig.json and build scripts.

export {} makes this file a module. declare global adds the method to Array's type description; assigning to Array.prototype supplies the runtime implementation. One call returns 10 and the empty array returns undefined.

The output shown above comes from the initialized values in this program. Replacing a type annotation alone does not transform a JavaScript value.

Augmenting a global interface without installing the corresponding runtime behavior causes missing-method errors.

Check both the TypeScript diagnostic and the emitted JavaScript behavior. A program can compile correctly and still need runtime validation or error handling.

Add lastOrUndefined() using an augmentation and a matching Array.prototype implementation.

Before running your change, write down the type you expect TypeScript to infer and the output you expect JavaScript to print. Then check both predictions.

Global augmentation extends the TypeScript description of global objects from within a module.

Try the practice change and re-run the exact program to test your understanding.