How does TypeScript handle declaration merging internally?

Declaration merging is a powerful feature in TypeScript that allows the compiler to combine two or more separate declarations with the same name into a single, unified definition. This process happens during compilation, enabling greater flexibility and extensibility, particularly with ambient declarations and augmenting existing types without explicit inheritance.

What is Declaration Merging?

Declaration merging is TypeScript's way of combining multiple declarations of the same entity (like an interface, namespace, or function) into a single, unified declaration. This mechanism is crucial for enabling modularity, enhancing existing libraries (e.g., through ambient declarations), and allowing incremental definition of types across different files or even within the same file.

Internal Mechanisms of Declaration Merging

At its core, TypeScript's compiler (specifically the ts.Program and ts.Checker components) processes source files and builds an Abstract Syntax Tree (AST). During the semantic analysis phase, the compiler identifies declarations. When it encounters multiple declarations with the same name in the same scope, it doesn't treat them as redeclarations (which would be an error in many languages) but rather as contributions to a single logical entity.

The key internal mechanism relies on the Symbol Table. Each unique name in a scope (module, global, block) is associated with a ts.Symbol. When the compiler encounters a new declaration, it first checks if a symbol with that name already exists in the current scope. If it does, instead of creating a new symbol, it associates the new declaration with the *existing* symbol. This symbol then accumulates all declarations associated with that name. When type checking needs to resolve the type of that name, it consults this unified symbol, which represents the merged definition. This ensures that all parts of a merged declaration are treated as one logical unit.

• Interfaces: Members from all declarations are combined.
• Namespaces (Modules): Members and inner declarations (like classes, functions, variables) are combined.
• Functions: Overloads are combined, creating a single function with multiple signature possibilities.
• Classes with Namespaces: A namespace can extend a class by adding static members.
• Enums with Namespaces: A namespace can add static members to an enum.

How Different Kinds of Declarations Merge

Interfaces

When multiple interfaces with the same name are declared in the same scope, their members are merged into a single interface definition. If members have the same name, they must be of the same type. If they are function members, they are treated as overloads, with later declarations appearing earlier in the merged list of overloads for resolution purposes (last in, first out for overload resolution).

Namespaces (Modules)

Similar to interfaces, multiple namespace declarations with the same name will have their exports merged. All exported members (interfaces, classes, functions, variables, other namespaces) from each declaration become part of the single merged namespace. This allows for splitting a large namespace definition across multiple files or augmenting an existing namespace with additional functionality.

Functions

When multiple function declarations with the same name are encountered, TypeScript treats them as function overloads. The signatures are collected, and the implementation of the *last* declaration provides the actual executable code. This is why you typically have a single implementation signature that is compatible with all preceding overload signatures.

Classes with Namespaces

A namespace can merge with a class, provided the namespace declaration immediately follows the class declaration in the same file. The namespace can add static members (methods, properties) to the class. It effectively augments the static side of the class. The type of the class constructor function is also enhanced with the members from the namespace, but instance members are not affected.

Enums with Namespaces

Similar to classes, a namespace can merge with an enum. This allows adding static members to the enum itself. For instance, you could add helper functions or properties directly to the enum object, which are then accessible via MyEnum.helperMethod(), extending its utility.

Compiler Passes and Resolution

The merging process occurs primarily during the early semantic analysis phase, where the compiler constructs and populates its symbol table. Later, during type checking, when a type reference needs to be resolved, the compiler looks up the merged symbol. This symbol contains all the accumulated declarations, allowing the type checker to apply the full, combined definition seamlessly.

// Interface merging
interface Box {
    height: number;
    width: number;
}

interface Box {
    depth: number;
}

let box: Box = { height: 10, width: 20, depth: 30 }; // Merged: { height: number, width: number, depth: number }

// Namespace merging
namespace Utilities {
    export function log(message: string) {
        console.log(message);
    }
}

namespace Utilities {
    export function error(message: string) {
        console.error(message);
    }
}

Utilities.log("Hello");
Utilities.error("Error occurred"); // Merged: Utilities now has both log and error

// Function merging (overloads)
function greet(name: string): string;
function greet(name: string, age: number): string;
function greet(name: string, age?: number): string {
    if (age) {
        return `Hello ${name}, you are ${age} years old.`;
    }
    return `Hello ${name}.`;
}

console.log(greet("Alice"));
console.log(greet("Bob", 30));

// Class and Namespace merging
class MyClass {
    instanceProp: string = "hello";
}

namespace MyClass {
    export const staticProp: number = 123;
    export function staticMethod(): string {
        return "Static method called";
    }
}

console.log(MyClass.staticProp);
console.log(MyClass.staticMethod());
let obj = new MyClass();
console.log(obj.instanceProp);

Declaration merging is a cornerstone of TypeScript's design, enabling powerful patterns like augmenting global objects, extending module definitions, and providing flexible API designs without requiring explicit inheritance or composition boilerplate for certain scenarios. Understanding its internal mechanism, particularly the role of the Symbol Table, clarifies how TypeScript achieves this seamless type combination.