Explain module augmentation use cases.

Module augmentation in TypeScript allows you to extend existing modules by adding new declarations to them. This powerful feature is crucial for integrating with JavaScript libraries, customizing type definitions, and enhancing global objects without modifying their original source files. It leverages TypeScript's declaration merging capabilities to provide a flexible way to enrich type information.

What is Module Augmentation?

Module augmentation is the process of adding new types, interfaces, classes, or functions to an existing module. This is typically done within a separate declaration file (e.g., my-types.d.ts) or an ambient module declaration, allowing you to extend a module's API or add custom properties without altering the original module's code. It's particularly useful when dealing with third-party libraries that might lack specific type definitions or when you need to extend global objects.

Common Use Cases

1. Extending Global Objects

When you need to add custom properties or methods to global objects like Window, NodeJS.Global, HTMLElement, or String, module augmentation is the go-to method. This is common in browser environments where you might attach custom properties to the window object for application-specific state or utility functions.

interface CustomWindow extends Window {
  myAppName?: string;
  globalConfig?: { apiUrl: string };
}

declare global {
  interface Window extends CustomWindow {}
}

// Now you can safely access these properties
window.myAppName = 'My Awesome App';
window.globalConfig = { apiUrl: 'https://api.example.com' };

2. Augmenting Third-Party Modules

This is arguably the most frequent use case. Many JavaScript libraries (especially older ones or those not strictly maintained with TypeScript in mind) might expose objects or functions that you want to add custom properties or methods to. For example, extending the Request object in Express.js or adding new fields to a library's configuration object.

// express-session.d.ts or similar declaration file
import 'express-session';

declare module 'express-session' {
  interface SessionData {
    userId?: string;
    isAdmin?: boolean;
  }
}

// In your application code
import express from 'express';
import session from 'express-session';

const app = express();
app.use(session({ secret: 'secret' }));

app.get('/login', (req, res) => {
  req.session.userId = 'user123';
  req.session.isAdmin = true;
  res.send('Logged in');
});

3. Adding Type Definitions for Untyped Modules

If you're using a JavaScript library that doesn't have @types/ definitions available, and you only need to define a small part of its API, you can use module augmentation to declare its types. This avoids having to create a full .d.ts file for the entire library.

// my-untyped-lib.d.ts
declare module 'untyped-library' {
  interface Options {
    format?: 'json' | 'xml';
    indent?: number;
  }

  function format(data: object, options?: Options): string;

  export = format;
}

// In your application code
import untypedFormat from 'untyped-library';

const myObject = { a: 1, b: { c: 'hello' } };
const formattedString = untypedFormat(myObject, { indent: 2 });

4. Customizing JSX Intrinsic Elements

When working with React, Preact, or other JSX frameworks, you might need to add custom attributes to standard HTML elements (e.g., data-test-id). Module augmentation allows you to extend JSX.IntrinsicElements to include these custom properties, providing type safety for your JSX components.

// custom-jsx.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> & {
      'data-test-id'?: string;
      'aria-label'?: string;
    };
    // You can extend other elements similarly
  }
}

// In your React component
const MyComponent = () => (
  <div data-test-id="my-div" aria-label="container">
    Hello
  </div>
);

5. Augmenting Modules with Dynamic Properties (e.g., Plugin Systems)

In systems where modules or objects dynamically gain properties through plugins or runtime configuration, module augmentation can be used to reflect these added properties in the type system. This is common in frameworks that use a plugin architecture where plugins extend core objects.

// my-framework.d.ts
declare module 'my-framework' {
  interface FrameworkApp {
    // Core properties
    version: string;
    // Placeholder for augmented properties
  }

  const app: FrameworkApp;
  export default app;
}

// my-framework-plugin-a.d.ts
import 'my-framework';

declare module 'my-framework' {
  interface FrameworkApp {
    pluginAFeature(): void;
  }
}

// my-framework-plugin-b.d.ts
import 'my-framework';

declare module 'my-framework' {
  interface FrameworkApp {
    pluginBState: { enabled: boolean };
  }
}

// In your application code
import app from 'my-framework';
// Assume plugins have been loaded at runtime

app.pluginAFeature();
console.log(app.pluginBState.enabled);

Considerations

• Location: For global augmentations (e.g., Window), use declare global {}. For module-specific augmentations, use declare module 'module-name' {} within a .d.ts file or a .ts file that also imports or exports something to make it a module.
• Export/Import Requirement: For a .ts file to be considered a 'module' and thus allow declare module '...' syntax, it must have at least one import or export statement. If it's a standalone augmentation file, it's often better to name it *.d.ts or add a dummy export {}.
• Declaration Merging: Module augmentation relies on declaration merging. Interfaces and type aliases can be merged, but type aliases can only merge if they are structural compatible with the original, whereas interface merges are more flexible.
• Clarity and Organization: While powerful, overuse or poorly organized augmentation can make understanding your project's types difficult. Keep augmentation files well-named and logically grouped.