Some of the unique concepts in TypeScript describe the shape of JavaScript objects at the type level.\nOne example that is especially unique to TypeScript is the concept of ‘declaration merging’.\nUnderstanding this concept will give you an advantage when working with existing JavaScript.\nIt also opens the door to more advanced abstraction concepts.
\nFor the purposes of this article, “declaration merging” means that the compiler merges two separate declarations declared with the same name into a single definition.\nThis merged definition has the features of both of the original declarations.\nAny number of declarations can be merged; it’s not limited to just two declarations.
\nIn TypeScript, a declaration creates entities in at least one of three groups: namespace, type, or value.\nNamespace-creating declarations create a namespace, which contains names that are accessed using a dotted notation.\nType-creating declarations do just that: they create a type that is visible with the declared shape and bound to the given name.\nLastly, value-creating declarations create values that are visible in the output JavaScript.
\n| Declaration Type | \nNamespace | \nType | \nValue | \n
|---|---|---|---|
| Namespace | \nX | \n\n | X | \n
| Class | \n\n | X | \nX | \n
| Enum | \n\n | X | \nX | \n
| Interface | \n\n | X | \n\n |
| Type Alias | \n\n | X | \n\n |
| Function | \n\n | \n | X | \n
| Variable | \n\n | \n | X | \n
Understanding what is created with each declaration will help you understand what is merged when you perform a declaration merge.
\nThe simplest, and perhaps most common, type of declaration merging is interface merging.\nAt the most basic level, the merge mechanically joins the members of both declarations into a single interface with the same name.
\n\ntsinterface Box {\n height: number;\n width: number;\n}\n\ninterface Box {\n scale: number;\n}\n\nlet box: Box = { height: 5, width: 6, scale: 10 };
Non-function members of the interfaces should be unique.\nIf they are not unique, they must be of the same type.\nThe compiler will issue an error if the interfaces both declare a non-function member of the same name, but of different types.
\nFor function members, each function member of the same name is treated as describing an overload of the same function.\nOf note, too, is that in the case of interface A merging with later interface A, the second interface will have a higher precedence than the first.
That is, in the example:
\n\ntsinterface Cloner {\n clone(animal: Animal): Animal;\n}\n\ninterface Cloner {\n clone(animal: Sheep): Sheep;\n}\n\ninterface Cloner {\n clone(animal: Dog): Dog;\n clone(animal: Cat): Cat;\n}
The three interfaces will merge to create a single declaration as so:
\n\ntsinterface Cloner {\n clone(animal: Dog): Dog;\n clone(animal: Cat): Cat;\n clone(animal: Sheep): Sheep;\n clone(animal: Animal): Animal;\n}
Notice that the elements of each group maintains the same order, but the groups themselves are merged with later overload sets ordered first.
\nOne exception to this rule is specialized signatures.\nIf a signature has a parameter whose type is a single string literal type (e.g. not a union of string literals), then it will be bubbled toward the top of its merged overload list.
\nFor instance, the following interfaces will merge together:
\n\ntsinterface Document {\n createElement(tagName: any): Element;\n}\ninterface Document {\n createElement(tagName: \"div\"): HTMLDivElement;\n createElement(tagName: \"span\"): HTMLSpanElement;\n}\ninterface Document {\n createElement(tagName: string): HTMLElement;\n createElement(tagName: \"canvas\"): HTMLCanvasElement;\n}
The resulting merged declaration of Document will be the following:
\ntsinterface Document {\n createElement(tagName: \"canvas\"): HTMLCanvasElement;\n createElement(tagName: \"div\"): HTMLDivElement;\n createElement(tagName: \"span\"): HTMLSpanElement;\n createElement(tagName: string): HTMLElement;\n createElement(tagName: any): Element;\n}
Similarly to interfaces, namespaces of the same name will also merge their members.\nSince namespaces create both a namespace and a value, we need to understand how both merge.
\nTo merge the namespaces, type definitions from exported interfaces declared in each namespace are themselves merged, forming a single namespace with merged interface definitions inside.
\nTo merge the namespace value, at each declaration site, if a namespace already exists with the given name, it is further extended by taking the existing namespace and adding the exported members of the second namespace to the first.
\nThe declaration merge of Animals in this example:
\ntsnamespace Animals {\n export class Zebra {}\n}\n\nnamespace Animals {\n export interface Legged {\n numberOfLegs: number;\n }\n export class Dog {}\n}
is equivalent to:
\n\ntsnamespace Animals {\n export interface Legged {\n numberOfLegs: number;\n }\n\n export class Zebra {}\n export class Dog {}\n}
This model of namespace merging is a helpful starting place, but we also need to understand what happens with non-exported members.\nNon-exported members are only visible in the original (un-merged) namespace. This means that after merging, merged members that came from other declarations cannot see non-exported members.
\nWe can see this more clearly in this example:
\n\ntsnamespace Animal {\n let haveMuscles = true;\n\n export function animalsHaveMuscles() {\n return haveMuscles;\n }\n}\n\nnamespace Animal {\n export function doAnimalsHaveMuscles() {\n return haveMuscles; // Error, because haveMuscles is not accessible here\n }\n}
Because haveMuscles is not exported, only the animalsHaveMuscles function that shares the same un-merged namespace can see the symbol.\nThe doAnimalsHaveMuscles function, even though it’s part of the merged Animal namespace can not see this un-exported member.
Namespaces are flexible enough to also merge with other types of declarations.\nTo do so, the namespace declaration must follow the declaration it will merge with. The resulting declaration has properties of both declaration types.\nTypeScript uses this capability to model some of the patterns in JavaScript as well as other programming languages.
\nThis gives the user a way of describing inner classes.
\n\ntsclass Album {\n label: Album.AlbumLabel;\n}\nnamespace Album {\n export class AlbumLabel {}\n}
The visibility rules for merged members is the same as described in the ‘Merging Namespaces’ section, so we must export the AlbumLabel class for the merged class to see it.\nThe end result is a class managed inside of another class.\nYou can also use namespaces to add more static members to an existing class.
In addition to the pattern of inner classes, you may also be familiar with the JavaScript practice of creating a function and then extending the function further by adding properties onto the function.\nTypeScript uses declaration merging to build up definitions like this in a type-safe way.
\n\ntsfunction buildLabel(name: string): string {\n return buildLabel.prefix + name + buildLabel.suffix;\n}\n\nnamespace buildLabel {\n export let suffix = \"\";\n export let prefix = \"Hello, \";\n}\n\nconsole.log(buildLabel(\"Sam Smith\"));
Similarly, namespaces can be used to extend enums with static members:
\n\ntsenum Color {\n red = 1,\n green = 2,\n blue = 4\n}\n\nnamespace Color {\n export function mixColor(colorName: string) {\n if (colorName == \"yellow\") {\n return Color.red + Color.green;\n } else if (colorName == \"white\") {\n return Color.red + Color.green + Color.blue;\n } else if (colorName == \"magenta\") {\n return Color.red + Color.blue;\n } else if (colorName == \"cyan\") {\n return Color.green + Color.blue;\n }\n }\n}
Not all merges are allowed in TypeScript.\nCurrently, classes can not merge with other classes or with variables.\nFor information on mimicking class merging, see the Mixins in TypeScript section.
\nAlthough JavaScript modules do not support merging, you can patch existing objects by importing and then updating them.\nLet’s look at a toy Observable example:
\n\nts// observable.ts\nexport class Observable<T> {\n // ... implementation left as an exercise for the reader ...\n}\n\n// map.ts\nimport { Observable } from \"./observable\";\nObservable.prototype.map = function(f) {\n // ... another exercise for the reader\n};
This works fine in TypeScript too, but the compiler doesn’t know about Observable.prototype.map.\nYou can use module augmentation to tell the compiler about it:
\nts// observable.ts\nexport class Observable<T> {\n // ... implementation left as an exercise for the reader ...\n}\n\n// map.ts\nimport { Observable } from \"./observable\";\ndeclare module \"./observable\" {\n interface Observable<T> {\n map<U>(f: (x: T) => U): Observable<U>;\n }\n}\nObservable.prototype.map = function(f) {\n // ... another exercise for the reader\n};\n\n// consumer.ts\nimport { Observable } from \"./observable\";\nimport \"./map\";\nlet o: Observable<number>;\no.map(x => x.toFixed());
The module name is resolved the same way as module specifiers in import/export.\nSee Modules for more information.\nThen the declarations in an augmentation are merged as if they were declared in the same file as the original.
However, there are two limitations to keep in mind:
\ndefault is a reserved word - see #14080 for details)You can also add declarations to the global scope from inside a module:
\n\nts// observable.ts\nexport class Observable<T> {\n // ... still no implementation ...\n}\n\ndeclare global {\n interface Array<T> {\n toObservable(): Observable<T>;\n }\n}\n\nArray.prototype.toObservable = function() {\n // ...\n};
Global augmentations have the same behavior and limits as module augmentations.
","headings":[{"value":"Introduction","depth":1},{"value":"Basic Concepts","depth":1},{"value":"Merging Interfaces","depth":1},{"value":"Merging Namespaces","depth":1},{"value":"Merging Namespaces with Classes, Functions, and Enums","depth":1},{"value":"Merging Namespaces with Classes","depth":2},{"value":"Disallowed Merges","depth":1},{"value":"Module Augmentation","depth":1},{"value":"Global augmentation","depth":2}],"frontmatter":{"permalink":"/docs/handbook/declaration-merging.html","title":"Declaration Merging"}}},"pageContext":{"slug":"/docs/handbook/declaration-merging.html","isOldHandbook":true}}}