Structuring modules to give the exact API shape you want can be tricky.\nFor example, we might want a module that can be invoked with or without new to produce different types,\nhas a variety of named types exposed in a hierarchy,\nand has some properties on the module object as well.
By reading this guide, you’ll have the tools to write complex definition files that expose a friendly API surface.\nThis guide focuses on module (or UMD) libraries because the options here are more varied.
\nYou can fully understand how to make any shape of definition\nby understanding some key concepts of how TypeScript works.
\nIf you’re reading this guide, you probably already roughly know what a type in TypeScript is.\nTo be more explicit, though, a type is introduced with:
\ntype sn = number | string;)interface I { x: number[]; })class C { })enum E { A, B, C })import declaration which refers to a typeEach of these declaration forms creates a new type name.
\nAs with types, you probably already understand what a value is.\nValues are runtime names that we can reference in expressions.\nFor example let x = 5; creates a value called x.
Again, being explicit, the following things create values:
\nlet, const, and var declarationsnamespace or module declaration which contains a valueenum declarationclass declarationimport declaration which refers to a valuefunction declarationTypes can exist in namespaces.\nFor example, if we have the declaration let x: A.B.C,\nwe say that the type C comes from the A.B namespace.
This distinction is subtle and important — here, A.B is not necessarily a type or a value.
Given a name A, we might find up to three different meanings for A: a type, a value or a namespace.\nHow the name is interpreted depends on the context in which it is used.\nFor example, in the declaration let m: A.A = A;,\nA is used first as a namespace, then as a type name, then as a value.\nThese meanings might end up referring to entirely different declarations!
This may seem confusing, but it’s actually very convenient as long as we don’t excessively overload things.\nLet’s look at some useful aspects of this combining behavior.
\nAstute readers will notice that, for example, class appeared in both the type and value lists.\nThe declaration class C { } creates two things:\na type C which refers to the instance shape of the class,\nand a value C which refers to the constructor function of the class.\nEnum declarations behave similarly.
Let’s say we wrote a module file foo.d.ts:
\ntsexport var SomeVar: { a: SomeType };\nexport interface SomeType {\n count: number;\n}
Then consumed it:
\n\ntsimport * as foo from './foo';\nlet x: foo.SomeType = foo.SomeVar.a;\nconsole.log(x.count);
This works well enough, but we might imagine that SomeType and SomeVar were very closely related\nsuch that you’d like them to have the same name.\nWe can use combining to present these two different objects (the value and the type) under the same name Bar:
\ntsexport var Bar: { a: Bar };\nexport interface Bar {\n count: number;\n}
This presents a very good opportunity for destructuring in the consuming code:
\n\ntsimport { Bar } from './foo';\nlet x: Bar = Bar.a;\nconsole.log(x.count);
Again, we’ve used Bar as both a type and a value here.\nNote that we didn’t have to declare the Bar value as being of the Bar type — they’re independent.
Some kinds of declarations can be combined across multiple declarations.\nFor example, class C { } and interface C { } can co-exist and both contribute properties to the C types.
This is legal as long as it does not create a conflict.\nA general rule of thumb is that values always conflict with other values of the same name unless they are declared as namespaces,\ntypes will conflict if they are declared with a type alias declaration (type s = string),\nand namespaces never conflict.
Let’s see how this can be used.
\ninterfaceWe can add additional members to an interface with another interface declaration:
\ntsinterface Foo {\n x: number;\n}\n// ... elsewhere ...\ninterface Foo {\n y: number;\n}\nlet a: Foo = ...;\nconsole.log(a.x + a.y); // OK
This also works with classes:
\n\ntsclass Foo {\n x: number;\n}\n// ... elsewhere ...\ninterface Foo {\n y: number;\n}\nlet a: Foo = ...;\nconsole.log(a.x + a.y); // OK
Note that we cannot add to type aliases (type s = string;) using an interface.
namespaceA namespace declaration can be used to add new types, values, and namespaces in any way which does not create a conflict.
For example, we can add a static member to a class:
\n\ntsclass C {\n}\n// ... elsewhere ...\nnamespace C {\n export let x: number;\n}\nlet y = C.x; // OK
Note that in this example, we added a value to the static side of C (its constructor function).\nThis is because we added a value, and the container for all values is another value\n(types are contained by namespaces, and namespaces are contained by other namespaces).
We could also add a namespaced type to a class:
\n\ntsclass C {\n}\n// ... elsewhere ...\nnamespace C {\n export interface D { }\n}\nlet y: C.D; // OK
In this example, there wasn’t a namespace C until we wrote the namespace declaration for it.\nThe meaning C as a namespace doesn’t conflict with the value or type meanings of C created by the class.
Finally, we could perform many different merges using namespace declarations.\nThis isn’t a particularly realistic example, but shows all sorts of interesting behavior:
\ntsnamespace X {\n export interface Y { }\n export class Z { }\n}\n\n// ... elsewhere ...\nnamespace X {\n export var Y: number;\n export namespace Z {\n export class C { }\n }\n}\ntype X = string;
In this example, the first block creates the following name meanings:
\nX (because the namespace declaration contains a value, Z)X (because the namespace declaration contains a type, Y)Y in the X namespaceZ in the X namespace (the instance shape of the class)Z that is a property of the X value (the constructor function of the class)The second block creates the following name meanings:
\nY (of type number) that is a property of the X valueZZ that is a property of the X valueC in the X.Z namespaceC that is a property of the X.Z valueXexport = or importAn important rule is that export and import declarations export or import all meanings of their targets.