7.2 Declaration Merging

Interfaces are “open-ended” and interface declarations with the same qualified name relative to a common root (as defined in section 2.3) contribute to a single interface.

When a generic interface has multiple declarations, all declarations must have identical type parameter lists, i.e. identical type parameter names with identical constraints in identical order.

In an interface with multiple declarations, the extends clauses are merged into a single set of base types and the bodies of the interface declarations are merged into a single object type. Declaration merging produces a declaration order that corresponds to prepending the members of each interface declaration, in the order the members are written, to the combined list of members in the order of the interface declarations. Thus, members declared in the last interface declaration will appear first in the declaration order of the merged type.

For example, a sequence of declarations in this order:

  1. interface Document {  
  2.     createElement(tagName: any): Element;  
  3. }
  5. interface Document {  
  6.     createElement(tagName: string): HTMLElement;  
  7. }
  9. interface Document {  
  10.     createElement(tagName: "div"): HTMLDivElement;   
  11.     createElement(tagName: "span"): HTMLSpanElement;  
  12.     createElement(tagName: "canvas"): HTMLCanvasElement;  
  13. }

is equivalent to the following single declaration:

  1. interface Document {  
  2.     createElement(tagName: "div"): HTMLDivElement;   
  3.     createElement(tagName: "span"): HTMLSpanElement;  
  4.     createElement(tagName: "canvas"): HTMLCanvasElement;  
  5.     createElement(tagName: string): HTMLElement;  
  6.     createElement(tagName: any): Element;  
  7. }

Note that the members of the last interface declaration appear first in the merged declaration. Also note that the relative order of members declared in the same interface body is preserved.

TODO: Document class and interface declaration merging.