TypeScript Declaration Merging

TypeScript Declaration Merging: Interface & Namespace Extension

Declaration merging is a compiler feature where two or more separate declarations with the same name are automatically combined into a single unified definition.

Declaration Merging Architecture

flowchart LR
    A["interface User { name: string; }"] --> C["Merged User Interface"]
    B["interface User { email: string; }"] --> C
    C --> D["User contains both name AND email properties!"]

Practical Code Example

// Interface Merging across different sections/files
interface UserSession {
  userId: string;
  loginTime: Date;
}

// Second declaration of same interface (merges automatically!)
interface UserSession {
  ipAddress: string;
  roles: string[];
}

const currentSession: UserSession = {
  userId: "usr_550",
  loginTime: new Date(),
  ipAddress: "192.168.1.1",
  roles: ["admin", "developer"]
};

// Namespace & Function Merging (Attaching utility functions to a function)
function buildRequest(url: string): string {
  return `GET ${url}`;
}

namespace buildRequest {
  export const defaultTimeout = 5000;
  export function post(url: string): string {
    return `POST ${url}`;
  }
}

console.log(buildRequest("https://api.kodersolution.com"));
console.log(buildRequest.post("https://api.kodersolution.com"));
console.log(`Timeout: ${buildRequest.defaultTimeout}ms`);

Best Practices & Gotchas

• Use Interface Merging for Library Augmentation: Extend window properties or Express request objects without modifying library source files.
• Type Merging Rules: Non-function properties must be unique or have the exact same type; conflicting property types will trigger a compiler error.
• Classes Cannot Merge with Other Classes: Declaration merging works for interfaces, namespaces, and functions, but not class declarations.

Self-Check Challenge

Declare an interface Window with property customAppId: string to perform global window declaration merging.