Module Augmentation

A module augmentation reopens an existing module with declare module and adds declarations that merge with its original named exports. The augmentation changes TypeScript's view of the module; runtime behavior still requires an implementation, usually installed by importing a patch module.

declare module "module-specifier" {
  // declarations that patch existing named exports
}

The augmentation contributes merged type declarations to the named exports of an existing module; it does not itself produce a runtime value.

// observable.ts
export class Observable<T> {
  constructor(public value: T) {}
}

// map.ts
import { Observable } from "./observable";
declare module "./observable" {
  interface Observable<T> {
    map<U>(f: (x: T) => U): Observable<U>;
  }
}
Observable.prototype.map = function <T, U>(
  this: Observable<T>, f: (x: T) => U,
) {
  return new Observable(f(this.value));
};

// consumer.ts
import { Observable } from "./observable";
import "./map";
const result = new Observable(1).map(x => x.toFixed());
console.log(result.value);

The augmentation adds the map method to Observable's type, while the imported patch supplies its runtime implementation.