What is Module Augmentation

Imagine you're using a third-party library with a Vehicle class, which provides basic vehicle functionality. However, your project requires additional features not present in the original class. This is where module augmentation comes in handy.

Here's the original Vehicle class from the library:

// vehicle.ts (in a third-party library)
export class Vehicle {
  constructor(public make: string, public model: string) {}

  startEngine() {
    console.log('Engine started');
  }
}

You want to add a toggleHeadlights method and a headlightsOn property to this Vehicle class. Here's how you can use module augmentation to achieve this.

Implementing Module Augmentation

First, import the Vehicle class into your index.ts file:

// index.ts
import { Vehicle } from "./vehicle";

Now, declare a module with the same path as the imported module and extend the Vehicle class interface:

// index.ts
declare module "./vehicle" {
  interface Vehicle {
    headlightsOn: boolean;
    toggleHeadlights(): void;
  }
}

TypeScript will merge the original Vehicle class with the augmented interface, effectively adding the new properties and methods to the class.

Next, you need to provide the implementation for the toggleHeadlights method. This can be done by augmenting the prototype of the Vehicle class:

// index.ts
Vehicle.prototype.toggleHeadlights = function() {
  this.headlightsOn = !this.headlightsOn;
  console.log(`Headlights ${this.headlightsOn ? 'on' : 'off'}`);
};

With these changes, you can now instantiate a Vehicle and use both the original and the new augmented functionalities:

// index.ts
const myCar = new Vehicle('Tesla', 'Model S');

myCar.startEngine(); // Engine started
myCar.toggleHeadlights(); // Headlights on
console.log(`Are the headlights on? ${myCar.headlightsOn}`); // Are the headlights on? true

Why Not Just Declare Another Class?

Why didn't we declare a new class extending the Vehicle class? While that is a common approach, there are scenarios where you might not be able to extend a class directly, such as when the class is not exported or when you want to patch the class without creating a subclass. Module augmentation is a powerful tool for these situations.

This article is inspired by the post Module Augmentation in TypeScript