Enums allow us to define a set of named numeric constants.
An enum can be defined using the enum keyword.
enum Direction {
Up = 1,
Down,
Left,
Right
}
The body of an enum consists of zero or more enum members. Enum members have numeric value associated with them and can be either constant or computed. An enum member is considered constant if:
0.+, -, ~ unary operators applied to constant enum expression+, -, *, /, %, <<, >>, >>>, &, |, ^ binary operators with constant enum expressions as operands
It is a compile time error for constant enum expressions to be evaluated to NaN or Infinity.In all other cases enum member is considered computed.
enum FileAccess {
// constant members
None,
Read = 1 << 1,
Write = 1 << 2,
ReadWrite = Read | Write,
// computed member
G = "123".length
}
Enums are real objects that exist at runtime. One reason is the ability to maintain a reverse mapping from enum values to enum names.
enum Enum {
A
}
let a = Enum.A;
let nameOfA = Enum[a]; // "A"
is compiled to:
var Enum;
(function (Enum) {
Enum[Enum["A"] = 0] = "A";
})(Enum || (Enum = {}));
var a = Enum.A;
var nameOfA = Enum[a]; // "A"
In generated code an enum is compiled into an object that stores both forward (name -> value) and reverse (value -> name) mappings.
References to enum members are always emitted as property accesses and never inlined.
In lots of cases this is a perfectly valid solution.
However sometimes requirements are tighter.
To avoid paying the cost of extra generated code and additional indirection when accessing enum values it is possible to use const enums.
Const enums are defined using the const modifier that precedes the enum keyword.
const enum Enum {
A = 1,
B = A * 2
}
Const enums can only use constant enum expressions and unlike regular enums they are completely removed during compilation. Const enum members are inlined at use sites. This is possible since const enums cannot have computed members.
const enum Directions {
Up,
Down,
Left,
Right
}
let directions = [Directions.Up, Directions.Down, Directions.Left, Directions.Right]
in generated code will become
var directions = [0 /* Up */, 1 /* Down */, 2 /* Left */, 3 /* Right */];
Ambient enums are used to describe the shape of already existing enum types.
declare enum Enum {
A = 1,
B,
C = 2
}
One important difference between ambient and non-ambient enums is that, in regular enums, members that don’t have an initializer are considered constant members. For non-const ambient enums member that does not have initializer is considered computed.
In this section, we will cover type inference in TypeScript. Namely, we’ll discuss where and how types are inferred.
In TypeScript, there are several places where type inference is used to provide type information when there is no explicit type annotation. For example, in this code
let x = 3;
The type of the x variable is inferred to be number.
This kind of inference takes place when initializing variables and members, setting parameter default values, and determining function return types.
In most cases, type inference is straightforward. In the following sections, we’ll explore some of the nuances in how types are inferred.
When a type inference is made from several expressions, the types of those expressions are used to calculate a “best common type”. For example,
let x = [0, 1, null];
To infer the type of x in the example above, we must consider the type of each array element.
Here we are given two choices for the type of the array: number and null.
The best common type algorithm considers each candidate type, and picks the type that is compatible with all the other candidates.
Because the best common type has to be chosen from the provided candidate types, there are some cases where types share a common structure, but no one type is the super type of all candidate types. For example:
let zoo = [new Rhino(), new Elephant(), new Snake()];
Ideally, we may want zoo to be inferred as an Animal[], but because there is no object that is strictly of type Animal in the array, we make no inference about the array element type.
To correct this, instead explicitly provide the type when no one type is a super type of all other candidates:
let zoo: Animal[] = [new Rhino(), new Elephant(), new Snake()];
When no best common type is found, the resulting inference is the union array type, (Rhino | Elephant | Snake)[].
Type inference also works in “the other direction” in some cases in TypeScript. This is known as “contextual typing”. Contextual typing occurs when the type of an expression is implied by its location. For example:
window.onmousedown = function(mouseEvent) {
console.log(mouseEvent.button); //<- Error
};
For the code above to give the type error, the TypeScript type checker used the type of the Window.onmousedown function to infer the type of the function expression on the right hand side of the assignment.
When it did so, it was able to infer the type of the mouseEvent parameter.
If this function expression were not in a contextually typed position, the mouseEvent parameter would have type any, and no error would have been issued.
If the contextually typed expression contains explicit type information, the contextual type is ignored. Had we written the above example:
window.onmousedown = function(mouseEvent: any) {
console.log(mouseEvent.button); //<- Now, no error is given
};
The function expression with an explicit type annotation on the parameter will override the contextual type. Once it does so, no error is given as no contextual type applies.
Contextual typing applies in many cases. Common cases include arguments to function calls, right hand sides of assignments, type assertions, members of object and array literals, and return statements. The contextual type also acts as a candidate type in best common type. For example:
function createZoo(): Animal[] {
return [new Rhino(), new Elephant(), new Snake()];
}
In this example, best common type has a set of four candidates: Animal, Rhino, Elephant, and Snake.
Of these, Animal can be chosen by the best common type algorithm.
Type compatibility in TypeScript is based on structural subtyping. Structural typing is a way of relating types based solely on their members. This is in contrast with nominal typing. Consider the following code:
interface Named {
name: string;
}
class Person {
name: string;
}
let p: Named;
// OK, because of structural typing
p = new Person();
In nominally-typed languages like C# or Java, the equivalent code would be an error because the Person class does not explicitly describe itself as being an implementor of the Named interface.
TypeScript’s structural type system was designed based on how JavaScript code is typically written. Because JavaScript widely uses anonymous objects like function expressions and object literals, it’s much more natural to represent the kinds of relationships found in JavaScript libraries with a structural type system instead of a nominal one.
TypeScript’s type system allows certain operations that can’t be known at compile-time to be safe. When a type system has this property, it is said to not be “sound”. The places where TypeScript allows unsound behavior were carefully considered, and throughout this document we’ll explain where these happen and the motivating scenarios behind them.
The basic rule for TypeScript’s structural type system is that x is compatible with y if y has at least the same members as x. For example:
interface Named {
name: string;
}
let x: Named;
// y's inferred type is { name: string; location: string; }
let y = { name: "Alice", location: "Seattle" };
x = y;
To check whether y can be assigned to x, the compiler checks each property of x to find a corresponding compatible property in y.
In this case, y must have a member called name that is a string. It does, so the assignment is allowed.
The same rule for assignment is used when checking function call arguments:
function greet(n: Named) {
alert("Hello, " + n.name);
}
greet(y); // OK
Note that y has an extra location property, but this does not create an error.
Only members of the target type (Named in this case) are considered when checking for compatibility.
This comparison process proceeds recursively, exploring the type of each member and sub-member.
While comparing primitive types and object types is relatively straightforward, the question of what kinds of functions should be considered compatible is a bit more involved. Let’s start with a basic example of two functions that differ only in their parameter lists:
let x = (a: number) => 0;
let y = (b: number, s: string) => 0;
y = x; // OK
x = y; // Error
To check if x is assignable to y, we first look at the parameter list.
Each parameter in x must have a corresponding parameter in y with a compatible type.
Note that the names of the parameters are not considered, only their types.
In this case, every parameter of x has a corresponding compatible parameter in y, so the assignment is allowed.
The second assignment is an error, because y has a required second parameter that ‘x’ does not have, so the assignment is disallowed.
You may be wondering why we allow ‘discarding’ parameters like in the example y = x.
The reason for this assignment to be allowed is that ignoring extra function parameters is actually quite common in JavaScript.
For example, Array#forEach provides three parameters to the callback function: the array element, its index, and the containing array.
Nevertheless, it’s very useful to provide a callback that only uses the first parameter:
let items = [1, 2, 3];
// Don't force these extra parameters
items.forEach((item, index, array) => console.log(item));
// Should be OK!
items.forEach(item => console.log(item));
Now let’s look at how return types are treated, using two functions that differ only by their return type:
let x = () => ({name: "Alice"});
let y = () => ({name: "Alice", location: "Seattle"});
x = y; // OK
y = x; // Error because x() lacks a location property
The type system enforces that the source function’s return type be a subtype of the target type’s return type.
When comparing the types of function parameters, assignment succeeds if either the source parameter is assignable to the target parameter, or vice versa. This is unsound because a caller might end up being given a function that takes a more specialized type, but invokes the function with a less specialized type. In practice, this sort of error is rare, and allowing this enables many common JavaScript patterns. A brief example:
enum EventType { Mouse, Keyboard }
interface Event { timestamp: number; }
interface MouseEvent extends Event { x: number; y: number }
interface KeyEvent extends Event { keyCode: number }
function listenEvent(eventType: EventType, handler: (n: Event) => void) {
/* ... */
}
// Unsound, but useful and common
listenEvent(EventType.Mouse, (e: MouseEvent) => console.log(e.x + "," + e.y));
// Undesirable alternatives in presence of soundness
listenEvent(EventType.Mouse, (e: Event) => console.log((<MouseEvent>e).x + "," + (<MouseEvent>e).y));
listenEvent(EventType.Mouse, <(e: Event) => void>((e: MouseEvent) => console.log(e.x + "," + e.y)));
// Still disallowed (clear error). Type safety enforced for wholly incompatible types
listenEvent(EventType.Mouse, (e: number) => console.log(e));
When comparing functions for compatibility, optional and required parameters are interchangeable. Extra optional parameters of the source type are not an error, and optional parameters of the target type without corresponding parameters in the source type are not an error.
When a function has a rest parameter, it is treated as if it were an infinite series of optional parameters.
This is unsound from a type system perspective, but from a runtime point of view the idea of an optional parameter is generally not well-enforced since passing undefined in that position is equivalent for most functions.
The motivating example is the common pattern of a function that takes a callback and invokes it with some predictable (to the programmer) but unknown (to the type system) number of arguments:
function invokeLater(args: any[], callback: (...args: any[]) => void) {
/* ... Invoke callback with 'args' ... */
}
// Unsound - invokeLater "might" provide any number of arguments
invokeLater([1, 2], (x, y) => console.log(x + ", " + y));
// Confusing (x and y are actually required) and undiscoverable
invokeLater([1, 2], (x?, y?) => console.log(x + ", " + y));
When a function has overloads, each overload in the source type must be matched by a compatible signature on the target type. This ensures that the target function can be called in all the same situations as the source function.
Enums are compatible with numbers, and numbers are compatible with enums. Enum values from different enum types are considered incompatible. For example,
enum Status { Ready, Waiting };
enum Color { Red, Blue, Green };
let status = Status.Ready;
status = Color.Green; //error
Classes work similarly to object literal types and interfaces with one exception: they have both a static and an instance type. When comparing two objects of a class type, only members of the instance are compared. Static members and constructors do not affect compatibility.
class Animal {
feet: number;
constructor(name: string, numFeet: number) { }
}
class Size {
feet: number;
constructor(numFeet: number) { }
}
let a: Animal;
let s: Size;
a = s; //OK
s = a; //OK
Private and protected members in a class affect their compatibility. When an instance of a class is checked for compatibility, if the target type contains a private member, then the source type must also contain a private member that originated from the same class. Likewise, the same applies for an instance with a protected member. This allows a class to be assignment compatible with its super class, but not with classes from a different inheritance hierarchy which otherwise have the same shape.
Because TypeScript is a structural type system, type parameters only affect the resulting type when consumed as part of the type of a member. For example,
interface Empty<T> {
}
let x: Empty<number>;
let y: Empty<string>;
x = y; // okay, y matches structure of x
In the above, x and y are compatible because their structures do not use the type argument in a differentiating way.
Changing this example by adding a member to Empty<T> shows how this works:
interface NotEmpty<T> {
data: T;
}
let x: NotEmpty<number>;
let y: NotEmpty<string>;
x = y; // error, x and y are not compatible
In this way, a generic type that has its type arguments specified acts just like a non-generic type.
For generic types that do not have their type arguments specified, compatibility is checked by specifying any in place of all unspecified type arguments.
The resulting types are then checked for compatibility, just as in the non-generic case.
For example,
let identity = function<T>(x: T): T {
// ...
}
let reverse = function<U>(y: U): U {
// ...
}
identity = reverse; // Okay because (x: any)=>any matches (y: any)=>any
So far, we’ve used ‘compatible’, which is not a term defined in the language spec.
In TypeScript, there are two kinds of compatibility: subtype and assignment.
These differ only in that assignment extends subtype compatibility with rules to allow assignment to and from any and to and from enum with corresponding numeric values.
Different places in the language use one of the two compatibility mechanisms, depending on the situation.
For practical purposes, type compatibility is dictated by assignment compatibility even in the cases of the implements and extends clauses.
For more information, see the TypeScript spec.
An intersection type combines multiple types into one.
This allows you to add together existing types to get a single type that has all the features you need.
For example, Person & Serializable & Loggable is a Person and Serializable and Loggable.
That means an object of this type will have all members of all three types.
You will mostly see intersection types used for mixins and other concepts that don’t fit in the classic object-oriented mold. (There are a lot of these in JavaScript!) Here’s a simple example that shows how to create a mixin:
function extend<T, U>(first: T, second: U): T & U {
let result = <T & U>{};
for (let id in first) {
(<any>result)[id] = (<any>first)[id];
}
for (let id in second) {
if (!result.hasOwnProperty(id)) {
(<any>result)[id] = (<any>second)[id];
}
}
return result;
}
class Person {
constructor(public name: string) { }
}
interface Loggable {
log(): void;
}
class ConsoleLogger implements Loggable {
log() {
// ...
}
}
var jim = extend(new Person("Jim"), new ConsoleLogger());
var n = jim.name;
jim.log();
Union types are closely related to intersection types, but they are used very differently.
Occasionally, you’ll run into a library that expects a parameter to be either a number or a string.
For instance, take the following function:
/**
* Takes a string and adds "padding" to the left.
* If 'padding' is a string, then 'padding' is appended to the left side.
* If 'padding' is a number, then that number of spaces is added to the left side.
*/
function padLeft(value: string, padding: any) {
if (typeof padding === "number") {
return Array(padding + 1).join(" ") + value;
}
if (typeof padding === "string") {
return padding + value;
}
throw new Error(`Expected string or number, got '${padding}'.`);
}
padLeft("Hello world", 4); // returns " Hello world"
The problem with padLeft is that its padding parameter is typed as any.
That means that we can call it with an argument that’s neither a number nor a string, but TypeScript will be okay with it.
let indentedString = padLeft("Hello world", true); // passes at compile time, fails at runtime.
In traditional object-oriented code, we might abstract over the two types by creating a hierarchy of types.
While this is much more explicit, it’s also a little bit overkill.
One of the nice things about the original version of padLeft was that we were able to just pass in primitives.
That meant that usage was simple and concise.
This new approach also wouldn’t help if we were just trying to use a function that already exists elsewhere.
Instead of any, we can use a union type for the padding parameter:
/**
* Takes a string and adds "padding" to the left.
* If 'padding' is a string, then 'padding' is appended to the left side.
* If 'padding' is a number, then that number of spaces is added to the left side.
*/
function padLeft(value: string, padding: string | number) {
// ...
}
let indentedString = padLeft("Hello world", true); // errors during compilation
A union type describes a value that can be one of several types.
We use the vertical bar (|) to separate each type, so number | string | boolean is the type of a value that can be a number, a string, or a boolean.
If we have a value that has a union type, we can only access members that are common to all types in the union.
interface Bird {
fly();
layEggs();
}
interface Fish {
swim();
layEggs();
}
function getSmallPet(): Fish | Bird {
// ...
}
let pet = getSmallPet();
pet.layEggs(); // okay
pet.swim(); // errors
Union types can be a bit tricky here, but it just takes a bit of intuition to get used to.
If a value has the type A | B, we only know for certain that it has members that both A and B have.
In this example, Bird has a member named fly.
We can’t be sure whether a variable typed as Bird | Fish has a fly method.
If the variable is really a Fish at runtime, then calling pet.fly() will fail.
Union types are useful for modeling situations when values can overlap in the types they can take on.
What happens when we need to know specifically whether we have a Fish?
A common idiom in JavaScript to differentiate between two possible values is to check for the presence of a member.
As we mentioned, you can only access members that are guaranteed to be in all the constituents of a union type.
let pet = getSmallPet();
// Each of these property accesses will cause an error
if (pet.swim) {
pet.swim();
}
else if (pet.fly) {
pet.fly();
}
To get the same code working, we’ll need to use a type assertion:
let pet = getSmallPet();
if ((<Fish>pet).swim) {
(<Fish>pet).swim();
}
else {
(<Bird>pet).fly();
}
Notice that we had to use type assertions several times.
It would be much better if once we performed the check, we could know the type of pet within each branch.
It just so happens that TypeScript has something called a type guard. A type guard is some expression that performs a runtime check that guarantees the type in some scope. To define a type guard, we simply need to define a function whose return type is a type predicate:
function isFish(pet: Fish | Bird): pet is Fish {
return (<Fish>pet).swim !== undefined;
}
pet is Fish is our type predicate in this example.
A predicate takes the form parameterName is Type, where parameterName must be the name of a parameter from the current function signature.
Any time isFish is called with some variable, TypeScript will narrow that variable to that specific type if the original type is compatible.
// Both calls to 'swim' and 'fly' are now okay.
if (isFish(pet)) {
pet.swim();
}
else {
pet.fly();
}
Notice that TypeScript not only knows that pet is a Fish in the if branch;
it also knows that in the else branch, you don’t have a Fish, so you must have a Bird.
typeof type guardsLet’s go back and write the code for the version of padLeft that uses union types.
We could write it with type predicates as follows:
function isNumber(x: any): x is number {
return typeof x === "number";
}
function isString(x: any): x is string {
return typeof x === "string";
}
function padLeft(value: string, padding: string | number) {
if (isNumber(padding)) {
return Array(padding + 1).join(" ") + value;
}
if (isString(padding)) {
return padding + value;
}
throw new Error(`Expected string or number, got '${padding}'.`);
}
However, having to define a function to figure out if a type is a primitive is kind of a pain.
Luckily, you don’t need to abstract typeof x === "number" into its own function because TypeScript will recognize it as a type guard on its own.
That means we could just write these checks inline.
function padLeft(value: string, padding: string | number) {
if (typeof padding === "number") {
return Array(padding + 1).join(" ") + value;
}
if (typeof padding === "string") {
return padding + value;
}
throw new Error(`Expected string or number, got '${padding}'.`);
}
These typeof type guards are recognized in two different forms: typeof v === "typename" and typeof v !== "typename", where "typename" must be "number", "string", "boolean", or "symbol".
While TypeScript won’t stop you from comparing to other strings, the language won’t recognize those expressions as type guards.
instanceof type guardsIf you’ve read about typeof type guards and are familiar with the instanceof operator in JavaScript, you probably have some idea of what this section is about.
instanceof type guards are a way of narrowing types using their constructor function.
For instance, let’s borrow our industrial string-padder example from earlier:
interface Padder {
getPaddingString(): string
}
class SpaceRepeatingPadder implements Padder {
constructor(private numSpaces: number) { }
getPaddingString() {
return Array(this.numSpaces + 1).join(" ");
}
}
class StringPadder implements Padder {
constructor(private value: string) { }
getPaddingString() {
return this.value;
}
}
function getRandomPadder() {
return Math.random() < 0.5 ?
new SpaceRepeatingPadder(4) :
new StringPadder(" ");
}
// Type is 'SpaceRepeatingPadder | StringPadder'
let padder: Padder = getRandomPadder();
if (padder instanceof SpaceRepeatingPadder) {
padder; // type narrowed to 'SpaceRepeatingPadder'
}
if (padder instanceof StringPadder) {
padder; // type narrowed to 'StringPadder'
}
The right side of the instanceof needs to be a constructor function, and TypeScript will narrow down to:
prototype property if its type is not anyin that order.
TypeScript has two special types, null and undefined, that have the values null and undefined respectively.
We mentioned these briefly in the Basic Types section.
By default, the type checker considers null and undefined assignable to anything.
Effectively, null and undefined are valid values of every type.
That means it’s not possible to stop them from being assigned to any type, even when you would like to prevent it.
The inventor of null, Tony Hoare, calls this his “billion dollar mistake”.
The --strictNullChecks flag fixes this: when you declare a variable, it doesn’t automatically include null or undefined.
You can include them explicitly using a union type:
let s = "foo";
s = null; // error, 'null' is not assignable to 'string'
let sn: string | null = "bar";
sn = null; // ok
sn = undefined; // error, 'undefined' is not assignable to 'string | null'
Note that TypeScript treats null and undefined differently in order to match JavaScript semantics.
string | null is a different type than string | undefined and string | undefined | null.
With --strictNullChecks, an optional parameter automatically adds | undefined:
function f(x: number, y?: number) {
return x + (y || 0);
}
f(1, 2);
f(1);
f(1, undefined);
f(1, null); // error, 'null' is not assignable to 'number | undefined'
The same is true for optional properties:
class C {
a: number;
b?: number;
}
let c = new C();
c.a = 12;
c.a = undefined; // error, 'undefined' is not assignable to 'number'
c.b = 13;
c.b = undefined; // ok
c.b = null; // error, 'null' is not assignable to 'number | undefined'
Since nullable types are implemented with a union, you need to use a type guard to get rid of the null.
Fortunately, this is the same code you’d write in JavaScript:
function f(sn: string | null): string {
if (sn == null) {
return "default";
}
else {
return sn;
}
}
The null elimination is pretty obvious here, but you can use terser operators too:
function f(sn: string | null): string {
return sn || "default";
}
In cases where the compiler can’t eliminate null or undefined, you can use the type assertion operator to manually remove them.
The syntax is postfix !: identifier! removes null and undefined from the type of identifier:
function broken(name: string | null): string {
function postfix(epithet: string) {
return name.charAt(0) + '. the ' + epithet; // error, 'name' is possibly null
}
name = name || "Bob";
return postfix("great");
}
function fixed(name: string | null): string {
function postfix(epithet: string) {
return name!.charAt(0) + '. the ' + epithet; // ok
}
name = name || "Bob";
return postfix("great");
}
The example uses a nested function here because the compiler can’t eliminate nulls inside a nested function (except immediately-invoked function expressions).
That’s because it can’t track all calls to the nested function, especially if you return it from the outer function.
Without knowing where the function is called, it can’t know what the type of name will be at the time the body executes.
Type aliases create a new name for a type. Type aliases are sometimes similar to interfaces, but can name primitives, unions, tuples, and any other types that you’d otherwise have to write by hand.
type Name = string;
type NameResolver = () => string;
type NameOrResolver = Name | NameResolver;
function getName(n: NameOrResolver): Name {
if (typeof n === "string") {
return n;
}
else {
return n();
}
}
Aliasing doesn’t actually create a new type - it creates a new name to refer to that type. Aliasing a primitive is not terribly useful, though it can be used as a form of documentation.
Just like interfaces, type aliases can also be generic - we can just add type parameters and use them on the right side of the alias declaration:
type Container<T> = { value: T };
We can also have a type alias refer to itself in a property:
type Tree<T> = {
value: T;
left: Tree<T>;
right: Tree<T>;
}
Together with intersection types, we can make some pretty mind-bending types:
type LinkedList<T> = T & { next: LinkedList<T> };
interface Person {
name: string;
}
var people: LinkedList<Person>;
var s = people.name;
var s = people.next.name;
var s = people.next.next.name;
var s = people.next.next.next.name;
However, it’s not possible for a type alias to appear anywhere else on the right side of the declaration:
type Yikes = Array<Yikes>; // error
As we mentioned, type aliases can act sort of like interfaces; however, there are some subtle differences.
One difference is that interfaces create a new name that is used everywhere.
Type aliases don’t create a new name — for instance, error messages won’t use the alias name.
In the code below, hovering over interfaced in an editor will show that it returns an Interface, but will show that aliased returns object literal type.
type Alias = { num: number }
interface Interface {
num: number;
}
declare function aliased(arg: Alias): Alias;
declare function interfaced(arg: Interface): Interface;
A second more important difference is that type aliases cannot be extended or implemented from (nor can they extend/implement other types). Because an ideal property of software is being open to extension, you should always use an interface over a type alias if possible.
On the other hand, if you can’t express some shape with an interface and you need to use a union or tuple type, type aliases are usually the way to go.
String literal types allow you to specify the exact value a string must have. In practice string literal types combine nicely with union types, type guards, and type aliases. You can use these features together to get enum-like behavior with strings.
type Easing = "ease-in" | "ease-out" | "ease-in-out";
class UIElement {
animate(dx: number, dy: number, easing: Easing) {
if (easing === "ease-in") {
// ...
}
else if (easing === "ease-out") {
}
else if (easing === "ease-in-out") {
}
else {
// error! should not pass null or undefined.
}
}
}
let button = new UIElement();
button.animate(0, 0, "ease-in");
button.animate(0, 0, "uneasy"); // error: "uneasy" is not allowed here
You can pass any of the three allowed strings, but any other string will give the error
Argument of type '"uneasy"' is not assignable to parameter of type '"ease-in" | "ease-out" | "ease-in-out"'
String literal types can be used in the same way to distinguish overloads:
function createElement(tagName: "img"): HTMLImageElement;
function createElement(tagName: "input"): HTMLInputElement;
// ... more overloads ...
function createElement(tagName: string): Element {
// ... code goes here ...
}
You can combine string literal types, union types, type guards, and type aliases to build an advanced pattern called discriminated unions, also known as tagged unions or algebraic data types. Discriminated unions are useful in functional programming. Some languages automatically discriminate unions for you; TypeScript instead builds on JavaScript patterns as they exist today. There are three ingredients:
interface Square {
kind: "square";
size: number;
}
interface Rectangle {
kind: "rectangle";
width: number;
height: number;
}
interface Circle {
kind: "circle";
radius: number;
}
First we declare the interfaces we will union.
Each interface has a kind property with a different string literal type.
The kind property is called the discriminant or tag.
The other properties are specific to each interface.
Notice that the interfaces are currently unrelated.
Let’s put them into a union:
type Shape = Square | Rectangle | Circle;
Now let’s use the discriminated union:
function area(s: Shape) {
switch (s.kind) {
case "square": return s.size * s.size;
case "rectangle": return s.height * s.width;
case "circle": return Math.PI * s.radius ** 2;
}
}
We would like the compiler to tell us when we don’t cover all variants of the discriminated union.
For example, if we add Triangle to Shape, we need to update area as well:
type Shape = Square | Rectangle | Circle | Triangle;
function area(s: Shape) {
switch (s.kind) {
case "square": return s.size * s.size;
case "rectangle": return s.height * s.width;
case "circle": return Math.PI * s.radius ** 2;
}
// should error here - we didn't handle case "triangle"
}
There are two ways to do this.
The first is to turn on --strictNullChecks and specify a return type:
function area(s: Shape): number { // error: returns number | undefined
switch (s.kind) {
case "square": return s.size * s.size;
case "rectangle": return s.height * s.width;
case "circle": return Math.PI * s.radius ** 2;
}
}
Because the switch is no longer exhaustive, TypeScript is aware that the function could sometimes return undefined.
If you have an explicit return type number, then you will get an error that the return type is actually number | undefined.
However, this method is quite subtle and, besides, --strictNullChecks does not always work with old code.
The second method uses the never type that the compiler uses to check for exhaustiveness:
function assertNever(x: never): never {
throw new Error("Unexpected object: " + x);
}
function area(s: Shape) {
switch (s.kind) {
case "square": return s.size * s.size;
case "rectangle": return s.height * s.width;
case "circle": return Math.PI * s.radius ** 2;
default: return assertNever(s); // error here if there are missing cases
}
}
Here, assertNever checks that s is of type never — the type that’s left after all other cases have been removed.
If you forget a case, then s will have a real type and you will get a type error.
This method requires you to define an extra function, but it’s much more obvious when you forget it.
this typesA polymorphic this type represents a type that is the subtype of the containing class or interface.
This is called F-bounded polymorphism.
This makes hierarchical fluent interfaces much easier to express, for example.
Take a simple calculator that returns this after each operation:
class BasicCalculator {
public constructor(protected value: number = 0) { }
public currentValue(): number {
return this.value;
}
public add(operand: number): this {
this.value += operand;
return this;
}
public multiply(operand: number): this {
this.value *= operand;
return this;
}
// ... other operations go here ...
}
let v = new BasicCalculator(2)
.multiply(5)
.add(1)
.currentValue();
Since the class uses this types, you can extend it and the new class can use the old methods with no changes.
class ScientificCalculator extends BasicCalculator {
public constructor(value = 0) {
super(value);
}
public sin() {
this.value = Math.sin(this.value);
return this;
}
// ... other operations go here ...
}
let v = new ScientificCalculator(2)
.multiply(5)
.sin()
.add(1)
.currentValue();
Without this types, ScientificCalculator would not have been able to extend BasicCalculator and keep the fluent interface.
multiply would have returned BasicCalculator, which doesn’t have the sin method.
However, with this types, multiply returns this, which is ScientificCalculator here.
With index types, you can get the compiler to check code that uses dynamic property names. For example, a common Javascript pattern is to pick a subset of properties from an object:
function pluck(o, names) {
return names.map(n => o[n]);
}
Here’s how you would write and use this function in TypeScript, using the index type query and indexed access operators:
function pluck<T, K extends keyof T>(o: T, names: K[]): T[K][] {
return names.map(n => o[n]);
}
interface Person {
name: string;
age: number;
}
let person: Person = {
name: 'Jarid',
age: 35
};
let strings: string[] = pluck(person, ['name']); // ok, string[]
The compiler checks that name is actually a property on Person.
The example introduces a couple of new type operators.
First is keyof T, the index type query operator.
For any type T, keyof T is the union of known, public property names of T.
For example:
let personProps: keyof Person; // 'name' | 'age'
keyof Person is completely interchangeable with 'name' | 'age'.
The difference is that if you add another property to Person, say address: string, then keyof Person will automatically update to be 'name' | 'age' | 'address'.
And you can use keyof in generic contexts like pluck, where you can’t possibly know the property names ahead of time.
That means the compiler will check that you pass the right set of property names to pluck:
pluck(person, ['age', 'unknown']); // error, 'unknown' is not in 'name' | 'age'
The second operator is T[K], the indexed access operator.
Here, the type syntax reflects the expression syntax.
That means that person['name'] has the type Person['name'] — which in our example is just string.
However, just like index type queries, you can use T[K] in a generic context, which is where its real power comes to life.
You just have to make sure that the type variable K extends keyof T.
Here’s another example with a function named getProperty.
function getProperty<T, K extends keyof T>(o: T, name: K): T[K] {
return o[name]; // o[name] is of type T[K]
}
In getProperty, o: T and name: K, so that means o[name]: T[K].
Once you return the T[K] result, the compiler will instantiate the actual type of the key, so the return type of getProperty will vary according to which property you request.
let name: string = getProperty(person, 'name');
let age: number = getProperty(person, 'age');
let unknown = getProperty(person, 'unknown'); // error, 'unknown' is not in 'name' | 'age'
keyof and T[K] interact with string index signatures.
If you have a type with a string index signature, keyof T will just be string.
And T[string] is just the type of the index signature:
interface Map<T> {
[key: string]: T;
}
let keys: keyof Map<number>; // string
let value: Map<number>['foo']; // number
A common task is to take an existing type and make each of its properties optional:
interface PersonPartial {
name?: string;
age?: number;
}
Or we might want a readonly version:
interface PersonReadonly {
readonly name: string;
readonly age: number;
}
This happens often enough in Javascript that TypeScript provides a way to create new types based on old types — mapped types.
In a mapped type, the new type transforms each property in the old type in the same way.
For example, you can make all properties of a type readonly or optional.
Here are a couple of examples:
type Readonly<T> = {
readonly [P in keyof T]: T[P];
}
type Partial<T> = {
[P in keyof T]?: T[P];
}
And to use it:
type PersonPartial = Partial<Person>;
type ReadonlyPerson = Readonly<Person>;
Let’s take a look at the simplest mapped type and its parts:
type Keys = 'option1' | 'option2';
type Flags = { [K in Keys]: boolean };
The syntax resembles the syntax for index signatures with a for .. in inside.
There are three parts:
K, which gets bound to each property in turn.Keys, which contains the names of properties to iterate over.In this simple example, Keys is a hard-coded list of property names and the property type is always boolean, so this mapped type is equivalent to writing:
type Flags = {
option1: boolean;
option2: boolean;
}
Real applications, however, look like Readonly or Partial above.
They’re based on some existing type, and they transform the fields in some way.
That’s where keyof and indexed access types come in:
type NullablePerson = { [P in keyof Person]: Person[P] | null }
type PartialPerson = { [P in keyof Person]?: Person[P] }
But it’s more useful to have a general version.
type Nullable<T> = { [P in keyof T]: T[P] | null }
type Partial<T> = { [P in keyof T]?: T[P] }
In these examples, the properties list is keyof T and the resulting type is some variant of T[P].
This is a good template for any general use of mapped types.
That’s because this kind of transformation is homomorphic, which means that the mapping applies only to properties of T and no others.
The compiler knows that it can copy all the existing property modifiers before adding any new ones.
For example, if Person.name were readonly, Partial<Person>.name would be readonly and optional.
Here’s one more example, in which T[P] is wrapped in a Proxy<T> class:
type Proxy<T> = {
get(): T;
set(value: T): void;
}
type Proxify<T> = {
[P in keyof T]: Proxy<T[P]>;
}
function proxify<T>(o: T): Proxify<T> {
// ... wrap proxies ...
}
let proxyProps = proxify(props);
Note that Readonly<T> and Partial<T> are so useful, they are included in TypeScript’s standard library along with Pick and Record:
type Pick<T, K extends keyof T> = {
[P in K]: T[P];
}
type Record<K extends string, T> = {
[P in K]: T;
}
Readonly, Partial and Pick are homomorphic whereas Record is not.
One clue that Record is not homomorphic is that it doesn’t take an input type to copy properties from:
type ThreeStringProps = Record<'prop1' | 'prop2' | 'prop3', string>
Non-homomorphic types are essentially creating new properties, so they can’t copy property modifiers from anywhere.
Now that you know how to wrap the properties of a type, the next thing you’ll want to do is unwrap them. Fortunately, that’s pretty easy:
function unproxify<T>(t: Proxify<T>): T {
let result = {} as T;
for (const k in t) {
result[k] = t[k].get();
}
return result;
}
let originalProps = unproxify(proxyProps);
Note that this unwrapping inference only works on homomorphic mapped types. If the mapped type is not homomorphic you’ll have to give an explicit type parameter to your unwrapping function.
Starting with ECMAScript 2015, symbol is a primitive data type, just like number and string.
symbol values are created by calling the Symbol constructor.
let sym1 = Symbol();
let sym2 = Symbol("key"); // optional string key
Symbols are immutable, and unique.
let sym2 = Symbol("key");
let sym3 = Symbol("key");
sym2 === sym3; // false, symbols are unique
Just like strings, symbols can be used as keys for object properties.
let sym = Symbol();
let obj = {
[sym]: "value"
};
console.log(obj[sym]); // "value"
Symbols can also be combined with computed property declarations to declare object properties and class members.
const getClassNameSymbol = Symbol();
class C {
[getClassNameSymbol](){
return "C";
}
}
let c = new C();
let className = c[getClassNameSymbol](); // "C"
In addition to user-defined symbols, there are well-known built-in symbols. Built-in symbols are used to represent internal language behaviors.
Here is a list of well-known symbols:
Symbol.hasInstanceA method that determines if a constructor object recognizes an object as one of the constructor’s instances. Called by the semantics of the instanceof operator.
Symbol.isConcatSpreadableA Boolean value indicating that an object should be flatten to its array elements by Array.prototype.concat.
Symbol.iteratorA method that returns the default iterator for an object. Called by the semantics of the for-of statement.
Symbol.matchA regular expression method that matches the regular expression against a string. Called by the String.prototype.match method.
Symbol.replaceA regular expression method that replaces matched substrings of a string. Called by the String.prototype.replace method.
Symbol.searchA regular expression method that returns the index within a string that matches the regular expression. Called by the String.prototype.search method.
Symbol.speciesA function valued property that is the constructor function that is used to create derived objects.
Symbol.splitA regular expression method that splits a string at the indices that match the regular expression.
Called by the String.prototype.split method.
Symbol.toPrimitiveA method that converts an object to a corresponding primitive value.
Called by the ToPrimitive abstract operation.
Symbol.toStringTagA String value that is used in the creation of the default string description of an object.
Called by the built-in method Object.prototype.toString.
Symbol.unscopablesAn Object whose own property names are property names that are excluded from the ‘with’ environment bindings of the associated objects.
An object is deemed iterable if it has an implementation for the Symbol.iterator property.
Some built-in types like Array, Map, Set, String, Int32Array, Uint32Array, etc. have their Symbol.iterator property already implemented.
Symbol.iterator function on an object is responsible for returning the list of values to iterate on.
for..of statementsfor..of loops over an iterable object, invoking the Symbol.iterator property on the object.
Here is a simple for..of loop on an array:
let someArray = [1, "string", false];
for (let entry of someArray) {
console.log(entry); // 1, "string", false
}
for..of vs. for..in statementsBoth for..of and for..in statements iterate over lists; the values iterated on are different though, for..in returns a list of keys on the object being iterated, whereas for..of returns a list of values of the numeric properties of the object being iterated.
Here is an example that demonstrates this distinction:
let list = [4, 5, 6];
for (let i in list) {
console.log(i); // "0", "1", "2",
}
for (let i of list) {
console.log(i); // "4", "5", "6"
}
Another distinction is that for..in operates on any object; it serves as a way to inspect properties on this object.
for..of on the other hand, is mainly interested in values of iterable objects. Built-in objects like Map and Set implement Symbol.iterator property allowing access to stored values.
let pets = new Set(["Cat", "Dog", "Hamster"]);
pets["species"] = "mammals";
for (let pet in pets) {
console.log(pet); // "species"
}
for (let pet of pets) {
console.log(pet); // "Cat", "Dog", "Hamster"
}
When targeting an ES5 or ES3, iterators are only allowed on values of Array type.
It is an error to use for..of loops on non-Array values, even if these non-Array values implement the Symbol.iterator property.
The compiler will generate a simple for loop for a for..of loop, for instance:
let numbers = [1, 2, 3];
for (let num of numbers) {
console.log(num);
}
will be generated as:
var numbers = [1, 2, 3];
for (var _i = 0; _i < numbers.length; _i++) {
var num = numbers[_i];
console.log(num);
}
When targeting an ECMAScipt 2015-compliant engine, the compiler will generate for..of loops to target the built-in iterator implementation in the engine.
A note about terminology: It’s important to note that in TypeScript 1.5, the nomenclature has changed. “Internal modules” are now “namespaces”. “External modules” are now simply “modules”, as to align with ECMAScript 2015’s terminology, (namely that
module X {is equivalent to the now-preferrednamespace X {).
Starting with ECMAScript 2015, JavaScript has a concept of modules. TypeScript shares this concept.
Modules are executed within their own scope, not in the global scope; this means that variables, functions, classes, etc. declared in a module are not visible outside the module unless they are explicitly exported using one of the export forms.
Conversely, to consume a variable, function, class, interface, etc. exported from a different module, it has to be imported using one of the import forms.
Modules are declarative; the relationships between modules are specified in terms of imports and exports at the file level.
Modules import one another using a module loader. At runtime the module loader is responsible for locating and executing all dependencies of a module before executing it. Well-known modules loaders used in JavaScript are the CommonJS module loader for Node.js and require.js for Web applications.
In TypeScript, just as in ECMAScript 2015, any file containing a top-level import or export is considered a module.
Any declaration (such as a variable, function, class, type alias, or interface) can be exported by adding the export keyword.
export interface StringValidator {
isAcceptable(s: string): boolean;
}
export const numberRegexp = /^[0-9]+$/;
export class ZipCodeValidator implements StringValidator {
isAcceptable(s: string) {
return s.length === 5 && numberRegexp.test(s);
}
}
Export statements are handy when exports need to be renamed for consumers, so the above example can be written as:
class ZipCodeValidator implements StringValidator {
isAcceptable(s: string) {
return s.length === 5 && numberRegexp.test(s);
}
}
export { ZipCodeValidator };
export { ZipCodeValidator as mainValidator };
Often modules extend other modules, and partially expose some of their features. A re-export does not import it locally, or introduce a local variable.
export class ParseIntBasedZipCodeValidator {
isAcceptable(s: string) {
return s.length === 5 && parseInt(s).toString() === s;
}
}
// Export original validator but rename it
export {ZipCodeValidator as RegExpBasedZipCodeValidator} from "./ZipCodeValidator";
Optionally, a module can wrap one or more modules and combine all their exports using export * from "module" syntax.
export * from "./StringValidator"; // exports interface 'StringValidator'
export * from "./LettersOnlyValidator"; // exports class 'LettersOnlyValidator'
export * from "./ZipCodeValidator"; // exports class 'ZipCodeValidator'
Importing is just about as easy as exporting from a module.
Importing an exported declaration is done through using one of the import forms below:
import { ZipCodeValidator } from "./ZipCodeValidator";
let myValidator = new ZipCodeValidator();
imports can also be renamed
import { ZipCodeValidator as ZCV } from "./ZipCodeValidator";
let myValidator = new ZCV();
import * as validator from "./ZipCodeValidator";
let myValidator = new validator.ZipCodeValidator();
Though not recommended practice, some modules set up some global state that can be used by other modules. These modules may not have any exports, or the consumer is not interested in any of their exports. To import these modules, use:
import "./my-module.js";
Each module can optionally export a default export.
Default exports are marked with the keyword default; and there can only be one default export per module.
default exports are imported using a different import form.
default exports are really handy.
For instance, a library like JQuery might have a default export of jQuery or $, which we’d probably also import under the name $ or jQuery.
declare let $: JQuery;
export default $;
import $ from "JQuery";
$("button.continue").html( "Next Step..." );
Classes and function declarations can be authored directly as default exports. Default export class and function declaration names are optional.
export default class ZipCodeValidator {
static numberRegexp = /^[0-9]+$/;
isAcceptable(s: string) {
return s.length === 5 && ZipCodeValidator.numberRegexp.test(s);
}
}
import validator from "./ZipCodeValidator";
let myValidator = new validator();
or
const numberRegexp = /^[0-9]+$/;
export default function (s: string) {
return s.length === 5 && numberRegexp.test(s);
}
import validate from "./StaticZipCodeValidator";
let strings = ["Hello", "98052", "101"];
// Use function validate
strings.forEach(s => {
console.log(`"${s}" ${validate(s) ? " matches" : " does not match"}`);
});
default exports can also be just values:
export default "123";
import num from "./OneTwoThree";
console.log(num); // "123"
export = and import = require()Both CommonJS and AMD generally have the concept of an exports object which contains all exports from a module.
They also support replacing the exports object with a custom single object.
Default exports are meant to act as a replacement for this behavior; however, the two are incompatible.
TypeScript supports export = to model the traditional CommonJS and AMD workflow.
The export = syntax specifies a single object that is exported from the module.
This can be a class, interface, namespace, function, or enum.
When importing a module using export =, TypeScript-specific import module = require("module") must be used to import the module.
let numberRegexp = /^[0-9]+$/;
class ZipCodeValidator {
isAcceptable(s: string) {
return s.length === 5 && numberRegexp.test(s);
}
}
export = ZipCodeValidator;
import zip = require("./ZipCodeValidator");
// Some samples to try
let strings = ["Hello", "98052", "101"];
// Validators to use
let validator = new zip();
// Show whether each string passed each validator
strings.forEach(s => {
console.log(`"${ s }" - ${ validator.isAcceptable(s) ? "matches" : "does not match" }`);
});
Depending on the module target specified during compilation, the compiler will generate appropriate code for Node.js (CommonJS), require.js (AMD), isomorphic (UMD), SystemJS, or ECMAScript 2015 native modules (ES6) module-loading systems.
For more information on what the define, require and register calls in the generated code do, consult the documentation for each module loader.
This simple example shows how the names used during importing and exporting get translated into the module loading code.
import m = require("mod");
export let t = m.something + 1;
define(["require", "exports", "./mod"], function (require, exports, mod_1) {
exports.t = mod_1.something + 1;
});
var mod_1 = require("./mod");
exports.t = mod_1.something + 1;
(function (factory) {
if (typeof module === "object" && typeof module.exports === "object") {
var v = factory(require, exports); if (v !== undefined) module.exports = v;
}
else if (typeof define === "function" && define.amd) {
define(["require", "exports", "./mod"], factory);
}
})(function (require, exports) {
var mod_1 = require("./mod");
exports.t = mod_1.something + 1;
});
System.register(["./mod"], function(exports_1) {
var mod_1;
var t;
return {
setters:[
function (mod_1_1) {
mod_1 = mod_1_1;
}],
execute: function() {
exports_1("t", t = mod_1.something + 1);
}
}
});
import { something } from "./mod";
export var t = something + 1;
Below, we’ve consolidated the Validator implementations used in previous examples to only export a single named export from each module.
To compile, we must specify a module target on the command line. For Node.js, use --module commonjs;
for require.js, use --module amd. For example:
tsc --module commonjs Test.ts
When compiled, each module will become a separate .js file.
As with reference tags, the compiler will follow import statements to compile dependent files.
export interface StringValidator {
isAcceptable(s: string): boolean;
}
import { StringValidator } from "./Validation";
const lettersRegexp = /^[A-Za-z]+$/;
export class LettersOnlyValidator implements StringValidator {
isAcceptable(s: string) {
return lettersRegexp.test(s);
}
}
import { StringValidator } from "./Validation";
const numberRegexp = /^[0-9]+$/;
export class ZipCodeValidator implements StringValidator {
isAcceptable(s: string) {
return s.length === 5 && numberRegexp.test(s);
}
}
import { StringValidator } from "./Validation";
import { ZipCodeValidator } from "./ZipCodeValidator";
import { LettersOnlyValidator } from "./LettersOnlyValidator";
// Some samples to try
let strings = ["Hello", "98052", "101"];
// Validators to use
let validators: { [s: string]: StringValidator; } = {};
validators["ZIP code"] = new ZipCodeValidator();
validators["Letters only"] = new LettersOnlyValidator();
// Show whether each string passed each validator
strings.forEach(s => {
for (let name in validators) {
console.log(`"${ s }" - ${ validators[name].isAcceptable(s) ? "matches" : "does not match" } ${ name }`);
}
});
In some cases, you may want to only load a module under some conditions. In TypeScript, we can use the pattern shown below to implement this and other advanced loading scenarios to directly invoke the module loaders without losing type safety.
The compiler detects whether each module is used in the emitted JavaScript.
If a module identifier is only ever used as part of a type annotations and never as an expression, then no require call is emitted for that module.
This elision of unused references is a good performance optimization, and also allows for optional loading of those modules.
The core idea of the pattern is that the import id = require("...") statement gives us access to the types exposed by the module.
The module loader is invoked (through require) dynamically, as shown in the if blocks below.
This leverages the reference-elision optimization so that the module is only loaded when needed.
For this pattern to work, it’s important that the symbol defined via an import is only used in type positions (i.e. never in a position that would be emitted into the JavaScript).
To maintain type safety, we can use the typeof keyword.
The typeof keyword, when used in a type position, produces the type of a value, in this case the type of the module.
declare function require(moduleName: string): any;
import { ZipCodeValidator as Zip } from "./ZipCodeValidator";
if (needZipValidation) {
let ZipCodeValidator: typeof Zip = require("./ZipCodeValidator");
let validator = new ZipCodeValidator();
if (validator.isAcceptable("...")) { /* ... */ }
}
declare function require(moduleNames: string[], onLoad: (...args: any[]) => void): void;
import * as Zip from "./ZipCodeValidator";
if (needZipValidation) {
require(["./ZipCodeValidator"], (ZipCodeValidator: typeof Zip) => {
let validator = new ZipCodeValidator.ZipCodeValidator();
if (validator.isAcceptable("...")) { /* ... */ }
});
}
declare const System: any;
import { ZipCodeValidator as Zip } from "./ZipCodeValidator";
if (needZipValidation) {
System.import("./ZipCodeValidator").then((ZipCodeValidator: typeof Zip) => {
var x = new ZipCodeValidator();
if (x.isAcceptable("...")) { /* ... */ }
});
}
To describe the shape of libraries not written in TypeScript, we need to declare the API that the library exposes.
We call declarations that don’t define an implementation “ambient”.
Typically, these are defined in .d.ts files.
If you’re familiar with C/C++, you can think of these as .h files.
Let’s look at a few examples.
In Node.js, most tasks are accomplished by loading one or more modules.
We could define each module in its own .d.ts file with top-level export declarations, but it’s more convenient to write them as one larger .d.ts file.
To do so, we use a construct similar to ambient namespaces, but we use the module keyword and the quoted name of the module which will be available to a later import.
For example:
declare module "url" {
export interface Url {
protocol?: string;
hostname?: string;
pathname?: string;
}
export function parse(urlStr: string, parseQueryString?, slashesDenoteHost?): Url;
}
declare module "path" {
export function normalize(p: string): string;
export function join(...paths: any[]): string;
export var sep: string;
}
Now we can /// <reference> node.d.ts and then load the modules using import url = require("url"); or import * as URL from "url".
/// <reference path="node.d.ts"/>
import * as URL from "url";
let myUrl = URL.parse("http://www.typescriptlang.org");
If you don’t want to take the time to write out declarations before using a new module, you can use a shorthand declaration to get started quickly.
declare module "hot-new-module";
All imports from a shorthand module will have the any type.
import x, {y} from "hot-new-module";
x(y);
Some module loaders such as SystemJS and AMD allow non-JavaScript content to be imported. These typically use a prefix or suffix to indicate the special loading semantics. Wildcard module declarations can be used to cover these cases.
declare module "*!text" {
const content: string;
export default content;
}
// Some do it the other way around.
declare module "json!*" {
const value: any;
export default value;
}
Now you can import things that match "*!text" or "json!*".
import fileContent from "./xyz.txt!text";
import data from "json!http://example.com/data.json";
console.log(data, fileContent);
Some libraries are designed to be used in many module loaders, or with no module loading (global variables). These are known as UMD or Isomorphic modules. These libraries can be accessed through either an import or a global variable. For example:
export const isPrime(x: number): boolean;
export as namespace mathLib;
The library can then be used as an import within modules:
import { isPrime } from "math-lib";
isPrime(2);
mathLib.isPrime(2); // ERROR: can't use the global definition from inside a module
It can also be used as a global variable, but only inside of a script. (A script is a file with no imports or exports.)
mathLib.isPrime(2);
Consumers of your module should have as little friction as possible when using things that you export. Adding too many levels of nesting tends to be cumbersome, so think carefully about how you want to structure things.
Exporting a namespace from your module is an example of adding too many layers of nesting. While namespaces sometime have their uses, they add an extra level of indirection when using modules. This can quickly become a pain point for users, and is usually unnecessary.
Static methods on an exported class have a similar problem - the class itself adds a layer of nesting. Unless it increases expressivity or intent in a clearly useful way, consider simply exporting a helper function.
class or function, use export defaultJust as “exporting near the top-level” reduces friction on your module’s consumers, so does introducing a default export. If a module’s primary purpose is to house one specific export, then you should consider exporting it as a default export. This makes both importing and actually using the import a little easier. For example:
export default class SomeType {
constructor() { ... }
}
export default function getThing() { return "thing"; }
import t from "./MyClass";
import f from "./MyFunc";
let x = new t();
console.log(f());
This is optimal for consumers. They can name your type whatever they want (t in this case) and don’t have to do any excessive dotting to find your objects.
export class SomeType { /* ... */ }
export function someFunc() { /* ... */ }
Conversely when importing:
import { SomeType, someFunc } from "./MyThings";
let x = new SomeType();
let y = someFunc();
export class Dog { ... }
export class Cat { ... }
export class Tree { ... }
export class Flower { ... }
import * as myLargeModule from "./MyLargeModule.ts";
let x = new myLargeModule.Dog();
Often you will need to extend functionality on a module. A common JS pattern is to augment the original object with extensions, similar to how JQuery extensions work. As we’ve mentioned before, modules do not merge like global namespace objects would. The recommended solution is to not mutate the original object, but rather export a new entity that provides the new functionality.
Consider a simple calculator implementation defined in module Calculator.ts.
The module also exports a helper function to test the calculator functionality by passing a list of input strings and writing the result at the end.
export class Calculator {
private current = 0;
private memory = 0;
private operator: string;
protected processDigit(digit: string, currentValue: number) {
if (digit >= "0" && digit <= "9") {
return currentValue * 10 + (digit.charCodeAt(0) - "0".charCodeAt(0));
}
}
protected processOperator(operator: string) {
if (["+", "-", "*", "/"].indexOf(operator) >= 0) {
return operator;
}
}
protected evaluateOperator(operator: string, left: number, right: number): number {
switch (this.operator) {
case "+": return left + right;
case "-": return left - right;
case "*": return left * right;
case "/": return left / right;
}
}
private evaluate() {
if (this.operator) {
this.memory = this.evaluateOperator(this.operator, this.memory, this.current);
}
else {
this.memory = this.current;
}
this.current = 0;
}
public handelChar(char: string) {
if (char === "=") {
this.evaluate();
return;
}
else {
let value = this.processDigit(char, this.current);
if (value !== undefined) {
this.current = value;
return;
}
else {
let value = this.processOperator(char);
if (value !== undefined) {
this.evaluate();
this.operator = value;
return;
}
}
}
throw new Error(`Unsupported input: '${char}'`);
}
public getResult() {
return this.memory;
}
}
export function test(c: Calculator, input: string) {
for (let i = 0; i < input.length; i++) {
c.handelChar(input[i]);
}
console.log(`result of '${input}' is '${c.getResult()}'`);
}
Here is a simple test for the calculator using the exposed test function.
import { Calculator, test } from "./Calculator";
let c = new Calculator();
test(c, "1+2*33/11="); // prints 9
Now to extend this to add support for input with numbers in bases other than 10, let’s create ProgrammerCalculator.ts
import { Calculator } from "./Calculator";
class ProgrammerCalculator extends Calculator {
static digits = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "A", "B", "C", "D", "E", "F"];
constructor(public base: number) {
super();
if (base <= 0 || base > ProgrammerCalculator.digits.length) {
throw new Error("base has to be within 0 to 16 inclusive.");
}
}
protected processDigit(digit: string, currentValue: number) {
if (ProgrammerCalculator.digits.indexOf(digit) >= 0) {
return currentValue * this.base + ProgrammerCalculator.digits.indexOf(digit);
}
}
}
// Export the new extended calculator as Calculator
export { ProgrammerCalculator as Calculator };
// Also, export the helper function
export { test } from "./Calculator";
The new module ProgrammerCalculator exports an API shape similar to that of the original Calculator module, but does not augment any objects in the original module.
Here is a test for our ProgrammerCalculator class:
import { Calculator, test } from "./ProgrammerCalculator";
let c = new Calculator(2);
test(c, "001+010="); // prints 3
When first moving to a module-based organization, a common tendency is to wrap exports in an additional layer of namespaces. Modules have their own scope, and only exported declarations are visible from outside the module. With this in mind, namespace provide very little, if any, value when working with modules.
On the organization front, namespaces are handy for grouping together logically-related objects and types in the global scope. For example, in C#, you’re going to find all the collection types in System.Collections. By organizing our types into hierarchical namespaces, we provide a good “discovery” experience for users of those types. Modules, on the other hand, are already present in a file system, necessarily. We have to resolve them by path and filename, so there’s a logical organization scheme for us to use. We can have a /collections/generic/ folder with a list module in it.
Namespaces are important to avoid naming collisions in the global scope.
For example, you might have My.Application.Customer.AddForm and My.Application.Order.AddForm – two types with the same name, but a different namespace.
This, however, is not an issue with modules.
Within a module, there’s no plausible reason to have two objects with the same name.
From the consumption side, the consumer of any given module gets to pick the name that they will use to refer to the module, so accidental naming conflicts are impossible.
For more discussion about modules and namespaces see Namespaces and Modules.
All of the following are red flags for module structuring. Double-check that you’re not trying to namespace your external modules if any of these apply to your files:
export namespace Foo { ... } (remove Foo and move everything ‘up’ a level)export class or export function (consider using export default)export namespace Foo { at top-level (don’t think that these are going to combine into one Foo!)A note about terminology: It’s important to note that in TypeScript 1.5, the nomenclature has changed. “Internal modules” are now “namespaces”. “External modules” are now simply “modules”, as to align with ECMAScript 2015’s terminology, (namely that
module X {is equivalent to the now-preferrednamespace X {).
This post outlines the various ways to organize your code using namespaces (previously “internal modules”) in TypeScript.
As we alluded in our note about terminology, “internal modules” are now referred to as “namespaces”.
Additionally, anywhere the module keyword was used when declaring an internal module, the namespace keyword can and should be used instead.
This avoids confusing new users by overloading them with similarly named terms.
Let’s start with the program we’ll be using as our example throughout this page. We’ve written a small set of simplistic string validators, as you might write to check a user’s input on a form in a webpage or check the format of an externally-provided data file.
interface StringValidator {
isAcceptable(s: string): boolean;
}
let lettersRegexp = /^[A-Za-z]+$/;
let numberRegexp = /^[0-9]+$/;
class LettersOnlyValidator implements StringValidator {
isAcceptable(s: string) {
return lettersRegexp.test(s);
}
}
class ZipCodeValidator implements StringValidator {
isAcceptable(s: string) {
return s.length === 5 && numberRegexp.test(s);
}
}
// Some samples to try
let strings = ["Hello", "98052", "101"];
// Validators to use
let validators: { [s: string]: StringValidator; } = {};
validators["ZIP code"] = new ZipCodeValidator();
validators["Letters only"] = new LettersOnlyValidator();
// Show whether each string passed each validator
for (let s of strings) {
for (let name in validators) {
let isMatch = validators[name].isAcceptable(s);
console.log(`'${ s }' ${ isMatch ? "matches" : "does not match" } '${ name }'.`);
}
}
As we add more validators, we’re going to want to have some kind of organization scheme so that we can keep track of our types and not worry about name collisions with other objects. Instead of putting lots of different names into the global namespace, let’s wrap up our objects into a namespace.
In this example, we’ll move all validator-related entities into a namespace called Validation.
Because we want the interfaces and classes here to be visible outside the namespace, we preface them with export.
Conversely, the variables lettersRegexp and numberRegexp are implementation details, so they are left unexported and will not be visible to code outside the namespace.
In the test code at the bottom of the file, we now need to qualify the names of the types when used outside the namespace, e.g. Validation.LettersOnlyValidator.
namespace Validation {
export interface StringValidator {
isAcceptable(s: string): boolean;
}
const lettersRegexp = /^[A-Za-z]+$/;
const numberRegexp = /^[0-9]+$/;
export class LettersOnlyValidator implements StringValidator {
isAcceptable(s: string) {
return lettersRegexp.test(s);
}
}
export class ZipCodeValidator implements StringValidator {
isAcceptable(s: string) {
return s.length === 5 && numberRegexp.test(s);
}
}
}
// Some samples to try
let strings = ["Hello", "98052", "101"];
// Validators to use
let validators: { [s: string]: Validation.StringValidator; } = {};
validators["ZIP code"] = new Validation.ZipCodeValidator();
validators["Letters only"] = new Validation.LettersOnlyValidator();
// Show whether each string passed each validator
for (let s of strings) {
for (let name in validators) {
console.log(`"${ s }" - ${ validators[name].isAcceptable(s) ? "matches" : "does not match" } ${ name }`);
}
}
As our application grows, we’ll want to split the code across multiple files to make it easier to maintain.
Here, we’ll split our Validation namespace across many files.
Even though the files are separate, they can each contribute to the same namespace and can be consumed as if they were all defined in one place.
Because there are dependencies between files, we’ll add reference tags to tell the compiler about the relationships between the files.
Our test code is otherwise unchanged.
namespace Validation {
export interface StringValidator {
isAcceptable(s: string): boolean;
}
}
/// <reference path="Validation.ts" />
namespace Validation {
const lettersRegexp = /^[A-Za-z]+$/;
export class LettersOnlyValidator implements StringValidator {
isAcceptable(s: string) {
return lettersRegexp.test(s);
}
}
}
/// <reference path="Validation.ts" />
namespace Validation {
const numberRegexp = /^[0-9]+$/;
export class ZipCodeValidator implements StringValidator {
isAcceptable(s: string) {
return s.length === 5 && numberRegexp.test(s);
}
}
}
/// <reference path="Validation.ts" />
/// <reference path="LettersOnlyValidator.ts" />
/// <reference path="ZipCodeValidator.ts" />
// Some samples to try
let strings = ["Hello", "98052", "101"];
// Validators to use
let validators: { [s: string]: Validation.StringValidator; } = {};
validators["ZIP code"] = new Validation.ZipCodeValidator();
validators["Letters only"] = new Validation.LettersOnlyValidator();
// Show whether each string passed each validator
for (let s of strings) {
for (let name in validators) {
console.log(""" + s + "" " + (validators[name].isAcceptable(s) ? " matches " : " does not match ") + name);
}
}
Once there are multiple files involved, we’ll need to make sure all of the compiled code gets loaded. There are two ways of doing this.
First, we can use concatenated output using the --outFile flag to compile all of the input files into a single JavaScript output file:
tsc --outFile sample.js Test.ts
The compiler will automatically order the output file based on the reference tags present in the files. You can also specify each file individually:
tsc --outFile sample.js Validation.ts LettersOnlyValidator.ts ZipCodeValidator.ts Test.ts
Alternatively, we can use per-file compilation (the default) to emit one JavaScript file for each input file.
If multiple JS files get produced, we’ll need to use <script> tags on our webpage to load each emitted file in the appropriate order, for example:
<script src="Validation.js" type="text/javascript" />
<script src="LettersOnlyValidator.js" type="text/javascript" />
<script src="ZipCodeValidator.js" type="text/javascript" />
<script src="Test.js" type="text/javascript" />
Another way that you can simplify working with of namespaces is to use import q = x.y.z to create shorter names for commonly-used objects.
Not to be confused with the import x = require("name") syntax used to load modules, this syntax simply creates an alias for the specified symbol.
You can use these sorts of imports (commonly referred to as aliases) for any kind of identifier, including objects created from module imports.
namespace Shapes {
export namespace Polygons {
export class Triangle { }
export class Square { }
}
}
import polygons = Shapes.Polygons;
let sq = new polygons.Square(); // Same as 'new Shapes.Polygons.Square()'
Notice that we don’t use the require keyword; instead we assign directly from the qualified name of the symbol we’re importing.
This is similar to using var, but also works on the type and namespace meanings of the imported symbol.
Importantly, for values, import is a distinct reference from the original symbol, so changes to an aliased var will not be reflected in the original variable.
To describe the shape of libraries not written in TypeScript, we need to declare the API that the library exposes. Because most JavaScript libraries expose only a few top-level objects, namespaces are a good way to represent them.
We call declarations that don’t define an implementation “ambient”.
Typically these are defined in .d.ts files.
If you’re familiar with C/C++, you can think of these as .h files.
Let’s look at a few examples.
The popular library D3 defines its functionality in a global object called d3.
Because this library is loaded through a <script> tag (instead of a module loader), its declaration uses namespaces to define its shape.
For the TypeScript compiler to see this shape, we use an ambient namespace declaration.
For example, we could begin writing it as follows:
declare namespace D3 {
export interface Selectors {
select: {
(selector: string): Selection;
(element: EventTarget): Selection;
};
}
export interface Event {
x: number;
y: number;
}
export interface Base extends Selectors {
event: Event;
}
}
declare var d3: D3.Base;
A note about terminology: It’s important to note that in TypeScript 1.5, the nomenclature has changed. “Internal modules” are now “namespaces”. “External modules” are now simply “modules”, as to align with ECMAScript 2015’s terminology, (namely that
module X {is equivalent to the now-preferrednamespace X {).
This post outlines the various ways to organize your code using namespaces and modules in TypeScript. We’ll also go over some advanced topics of how to use namespaces and modules, and address some common pitfalls when using them in TypeScript.
See the Modules documentation for more information about modules. See the Namespaces documentation for more information about namespaces.
Namespaces are simply named JavaScript objects in the global namespace.
This makes namespaces a very simple construct to use.
They can span multiple files, and can be concatenated using --outFile.
Namespaces can be a good way to structure your code in a Web Application, with all dependencies included as <script> tags in your HTML page.
Just like all global namespace pollution, it can be hard to identify component dependencies, especially in a large application.
Just like namespaces, modules can contain both code and declarations. The main difference is that modules declare their dependencies.
Modules also have a dependency on a module loader (such as CommonJs/Require.js). For a small JS application this might not be optimal, but for larger applications, the cost comes with long term modularity and maintainability benefits. Modules provide for better code reuse, stronger isolation and better tooling support for bundling.
It is also worth noting that, for Node.js applications, modules are the default and the recommended approach to structure your code.
Starting with ECMAScript 2015, modules are native part of the language, and should be supported by all compliant engine implementations. Thus, for new projects modules would be the recommended code organization mechanism.
In this section we’ll describe various common pitfalls in using namespaces and modules, and how to avoid them.
/// <reference>-ing a moduleA common mistake is to try to use the /// <reference ... /> syntax to refer to a module file, rather than using an import statement.
To understand the distinction, we first need to understand how compiler can locate the type information for a module based on the path of an import (e.g. the ... in import x from "...";, import x = require("...");, etc.) path.
The compiler will try to find a .ts, .tsx, and then a .d.ts with the appropriate path.
If a specific file could not be found, then the compiler will look for an ambient module declaration.
Recall that these need to be declared in a .d.ts file.
myModules.d.ts
// In a .d.ts file or .ts file that is not a module:
declare module "SomeModule" {
export function fn(): string;
}
myOtherModule.ts
/// <reference path="myModules.d.ts" />
import * as m from "SomeModule";
The reference tag here allows us to locate the declaration file that contains the declaration for the ambient module.
This is how the node.d.ts file that several of the TypeScript samples use is consumed.
If you’re converting a program from namespaces to modules, it can be easy to end up with a file that looks like this:
shapes.ts
export namespace Shapes {
export class Triangle { /* ... */ }
export class Square { /* ... */ }
}
The top-level module here Shapes wraps up Triangle and Square for no reason.
This is confusing and annoying for consumers of your module:
shapeConsumer.ts
import * as shapes from "./shapes";
let t = new shapes.Shapes.Triangle(); // shapes.Shapes?
A key feature of modules in TypeScript is that two different modules will never contribute names to the same scope. Because the consumer of a module decides what name to assign it, there’s no need to proactively wrap up the exported symbols in a namespace.
To reiterate why you shouldn’t try to namespace your module contents, the general idea of namespacing is to provide logical grouping of constructs and to prevent name collisions. Because the module file itself is already a logical grouping, and its top-level name is defined by the code that imports it, it’s unnecessary to use an additional module layer for exported objects.
Here’s a revised example:
shapes.ts
export class Triangle { /* ... */ }
export class Square { /* ... */ }
shapeConsumer.ts
import * as shapes from "./shapes";
let t = new shapes.Triangle();
Just as there is a one-to-one correspondence between JS files and modules, TypeScript has a one-to-one correspondence between module source files and their emitted JS files.
One effect of this is that it’s not possible to concatenate multiple module source files depending on the module system you target.
For instance, you can’t use the outFile option while targeting commonjs or umd, but with TypeScript 1.8 and later, it’s possible to use outFile when targeting amd or system.
This section assumes some basic knowledge about modules. Please see the Modules documentation for more information.
Module resolution is the process the compiler uses to figure out what an import refers to.
Consider an import statement like import { a } from "moduleA";
in order to check any use of a, the compiler needs to know exactly what it represents, and will need to check its definition moduleA.
At this point, the compiler will ask “what’s the shape of moduleA?”
While this sounds straightforward, moduleA could be defined in one of your own .ts/.tsx files, or in a .d.ts that your code depends on.
First, the compiler will try to locate a file that represents the imported module.
To do so the compiler follows one of two different strategies: Classic or Node.
These strategies tell the compiler where to look for moduleA.
If that didn’t work and if the module name is non-relative (and in the case of "moduleA", it is), then the compiler will attempt to locate an ambient module declaration.
We’ll cover non-relative imports next.
Finally, if the compiler could not resolve the module, it will log an error.
In this case, the error would be something like error TS2307: Cannot find module 'moduleA'.
Module imports are resolved differently based on whether the module reference is relative or non-relative.
A relative import is one that starts with /, ./ or ../.
Some examples include:
import Entry from "./components/Entry";import { DefaultHeaders } from "../constants/http";import "/mod";Any other import is considered non-relative. Some examples include:
import * as $ from "jquery";import { Component } from "@angular/core";A relative import is resolved relative to the importing file and cannot resolve to an ambient module declaration. You should use relative imports for your own modules that are guaranteed to maintain their relative location at runtime.
A non-relative import can be resolved relative to baseUrl, or through path mapping, which we’ll cover below.
They can also resolve to ambient module declarations.
Use non-relative paths when importing any of your external dependencies.
There are two possible module resolution strategies: Node and Classic.
You can use the --moduleResolution flag to specify the module resolution strategy.
If not specified, the default is Classic for --module AMD | System | ES2015 or Node otherwise.
This used to be TypeScript’s default resolution strategy. Nowadays, this strategy is mainly present for backward compatibility.
A relative import will be resolved relative to the importing file.
So import { b } from "./moduleB" in source file /root/src/folder/A.ts would result in the following lookups:
/root/src/folder/moduleB.ts/root/src/folder/moduleB.d.tsFor non-relative module imports, however, the compiler walks up the directory tree starting with the directory containing the importing file, trying to locate a matching definition file.
For example:
A non-relative import to moduleB such as import { b } from "moduleB", in a source file /root/src/folder/A.ts, would result in attempting the following locations for locating "moduleB":
/root/src/folder/moduleB.ts/root/src/folder/moduleB.d.ts/root/src/moduleB.ts/root/src/moduleB.d.ts/root/moduleB.ts/root/moduleB.d.ts/moduleB.ts/moduleB.d.tsThis resolution strategy attempts to mimic the Node.js module resolution mechanism at runtime. The full Node.js resolution algorithm is outlined in Node.js module documentation.
To understand what steps the TS compiler will follow, it is important to shed some light on Node.js modules.
Traditionally, imports in Node.js are performed by calling a function named require.
The behavior Node.js takes will differ depending on if require is given a relative path or a non-relative path.
Relative paths are fairly straightforward.
As an example, let’s consider a file located at /root/src/moduleA.js, which contains the import var x = require("./moduleB");
Node.js resolves that import in the following order:
As the file named /root/src/moduleB.js, if it exists.
As the folder /root/src/moduleB if it contains a file named package.json that specifies a "main" module.
In our example, if Node.js found the file /root/src/moduleB/package.json containing { "main": "lib/mainModule.js" }, then Node.js will refer to /root/src/moduleB/lib/mainModule.js.
As the folder /root/src/moduleB if it contains a file named index.js.
That file is implicitly considered that folder’s “main” module.
You can read more about this in Node.js documentation on file modules and folder modules.
However, resolution for a non-relative module name is performed differently.
Node will look for your modules in special folders named node_modules.
A node_modules folder can be on the same level as the current file, or higher up in the directory chain.
Node will walk up the directory chain, looking through each node_modules until it finds the module you tried to load.
Following up our example above, consider if /root/src/moduleA.js instead used a non-relative path and had the import var x = require("moduleB");.
Node would then try to resolve moduleB to each of the locations until one worked.
/root/src/node_modules/moduleB.js/root/src/node_modules/moduleB/package.json (if it specifies a "main" property)/root/src/node_modules/moduleB/index.js
/root/node_modules/moduleB.js/root/node_modules/moduleB/package.json (if it specifies a "main" property)/root/node_modules/moduleB/index.js
/node_modules/moduleB.js/node_modules/moduleB/package.json (if it specifies a "main" property)/node_modules/moduleB/index.jsNotice that Node.js jumped up a directory in steps (4) and (7).
You can read more about the process in Node.js documentation on loading modules from node_modules.
TypeScript will mimic the Node.js run-time resolution strategy in order to locate definition files for modules at compile-time.
To accomplish this, TypeScript overlays the TypeScript source file extensions (.ts, .tsx, and .d.ts) over the Node’s resolution logic.
TypeScript will also use a field in package.json named "types" to mirror the purpose of "main" - the compiler will use it to find the “main” definition file to consult.
For example, an import statement like import { b } from "./moduleB" in /root/src/moduleA.ts would result in attempting the following locations for locating "./moduleB":
/root/src/moduleB.ts/root/src/moduleB.tsx/root/src/moduleB.d.ts/root/src/moduleB/package.json (if it specifies a "types" property)/root/src/moduleB/index.ts/root/src/moduleB/index.tsx/root/src/moduleB/index.d.tsRecall that Node.js looked for a file named moduleB.js, then an applicable package.json, and then for an index.js.
Similarly a non-relative import will follow the Node.js resolution logic, first looking up a file, then looking up an applicable folder.
So import { b } from "moduleB" in source file /root/src/moduleA.ts would result in the following lookups:
/root/src/node_modules/moduleB.ts/root/src/node_modules/moduleB.tsx/root/src/node_modules/moduleB.d.ts/root/src/node_modules/moduleB/package.json (if it specifies a "types" property)/root/src/node_modules/moduleB/index.ts/root/src/node_modules/moduleB/index.tsx/root/src/node_modules/moduleB/index.d.ts
/root/node_modules/moduleB.ts/root/node_modules/moduleB.tsx/root/node_modules/moduleB.d.ts/root/node_modules/moduleB/package.json (if it specifies a "types" property)/root/node_modules/moduleB/index.ts/root/node_modules/moduleB/index.tsx/root/node_modules/moduleB/index.d.ts
/node_modules/moduleB.ts/node_modules/moduleB.tsx/node_modules/moduleB.d.ts/node_modules/moduleB/package.json (if it specifies a "types" property)/node_modules/moduleB/index.ts/node_modules/moduleB/index.tsx/node_modules/moduleB/index.d.tsDon’t be intimidated by the number of steps here - TypeScript is still only jumping up directories twice at steps (8) and (15). This is really no more complex than what Node.js itself is doing.
A project source layout sometimes does not match that of the output.
Usually a set of build steps result in generating the final output.
These include compiling .ts files into .js, and copying dependencies from different source locations to a single output location.
The net result is that modules at runtime may have different names than the source files containing their definitions.
Or module paths in the final output may not match their corresponding source file paths at compile time.
The TypeScript compiler has a set of additional flags to inform the compiler of transformations that are expected to happen to the sources to generate the final output.
It is important to note that the compiler will not perform any of these transformations; it just uses these pieces of information to guide the process of resolving a module import to its definition file.
Using a baseUrl is a common practice in applications using AMD module loaders where modules are “deployed” to a single folder at run-time.
The sources of these modules can live in different directories, but a build script will put them all together.
Setting baseUrl informs the compiler where to find modules.
All module imports with non-relative names are assumed to be relative to the baseUrl.
Value of baseUrl is determined as either:
Note that relative module imports are not impacted by setting the baseUrl, as they are always resolved relative to their importing files.
You can find more documentation on baseUrl in RequireJS and SystemJS documentation.
Sometimes modules are not directly located under baseUrl.
For instance, an import to a module "jquery" would be translated at runtime to "node_modules/jquery/dist/jquery.slim.min.js".
Loaders use a mapping configuration to map module names to files at run-time, see RequireJs documentation and SystemJS documentation.
The TypeScript compiler supports the declaration of such mappings using "paths" property in tsconfig.json files.
Here is an example for how to specify the "paths" property for jquery.
{
"compilerOptions": {
"baseUrl": ".", // This must be specified if "paths" is.
"paths": {
"jquery": ["node_modules/jquery/dist/jquery"] // This mapping is relative to "baseUrl"
}
}
}
Please notice that "paths" are resolved relative to "baseUrl".
When setting "baseUrl" to another value than ".", i.e. the directory of tsconfig.json, the mappings must be changed accordingly.
Say, you set "baseUrl": "./src" in the above example, then jquery should be mapped to "../node_modules/jquery/dist/jquery".
Using "paths" also allows for more sophisticated mappings including multiple fall back locations.
Consider a project configuration where only some modules are available in one location, and the rest are in another.
A build step would put them all together in one place.
The project layout may look like:
projectRoot
├── folder1
│ ├── file1.ts (imports 'folder1/file2' and 'folder2/file3')
│ └── file2.ts
├── generated
│ ├── folder1
│ └── folder2
│ └── file3.ts
└── tsconfig.json
The corresponding tsconfig.json would look like:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"*": [
"*",
"generated/*"
]
}
}
}
This tells the compiler for any module import that matches the pattern "*" (i.e. all values), to look in two locations:
"*": meaning the same name unchanged, so map <moduleName> => <baseUrl>/<moduleName>"generated/*" meaning the module name with an appended prefix “generated”, so map <moduleName> => <baseUrl>/generated/<moduleName>Following this logic, the compiler will attempt to resolve the two imports as such:
folder1/file2projectRoot/folder1/file2.ts.folder2/file3projectRoot/folder2/file3.ts.generated/folder2/file3projectRoot/generated/folder2/file3.ts.rootDirsSometimes the project sources from multiple directories at compile time are all combined to generate a single output directory. This can be viewed as a set of source directories create a “virtual” directory.
Using ‘rootDirs’, you can inform the compiler of the roots making up this “virtual” directory; and thus the compiler can resolve relative modules imports within these “virtual” directories as if were merged together in one directory.
For example consider this project structure:
src
└── views
└── view1.ts (imports './template1')
└── view2.ts
generated
└── templates
└── views
└── template1.ts (imports './view2')
Files in src/views are user code for some UI controls.
Files in generated/templates are UI template binding code auto-generated by a template generator as part of the build.
A build step will copy the files in /src/views and /generated/templates/views to the same directory in the output.
At run-time, a view can expect its template to exist next to it, and thus should import it using a relative name as "./template".
To specify this relationship to the compiler, use"rootDirs".
"rootDirs" specify a list of roots whose contents are expected to merge at run-time.
So following our example, the tsconfig.json file should look like:
{
"compilerOptions": {
"rootDirs": [
"src/views",
"generated/templates/views"
]
}
}
Every time the compiler sees a relative module import in a subfolder of one of the rootDirs, it will attempt to look for this import in each of the entries of rootDirs.
The flexibility of rootDirs is not limited to specifying a list of physical source directories that are logically merged. The supplied array may include any number of ad hoc, arbitrary directory names, regardless of whether they exist or not. This allows the compiler to capture sophisticated bundling and runtime features such as conditional inclusion and project specific loader plugins in a in a type safe way.
Consider an internationalization scenario where a build tool automatically generates locale specific bundles by interpolating a special path token, say #{locale}, as part of a relative module path such as ./#{locale}/messages. In this hypothetical setup the tool enumerates supported locales, mapping the abstracted path into ./zh/messages, ./de/messages, and so forth.
Assume that each of these modules exports an array of strings. For example ./zh/messages might contain:
export default [
"您好吗",
"很高兴认识你"
];
By leveraging rootDirs we can inform the compiler of this mapping and thereby allow it to safely resolve ./#{locale}/messages, even though the directory will never exist. For example, with the following tsconfig.json:
{
"compilerOptions": {
"rootDirs": [
"src/zh",
"src/de",
"src/#{locale}"
]
}
}
The compiler will now resolve import messages from './#{locale}/messages' to import messages from './zh/messages' for tooling purposes, allowing development in a locale agnostic manner without compromising design time support.
As discussed earlier, the compiler can visit files outside the current folder when resolving a module.
This can be hard when diagnosing why a module is not resolved, or is resolved to an incorrect definition.
Enabling the compiler module resolution tracing using --traceResolution provides insight in what happened during the module resolution process.
Let’s say we have a sample application that uses the typescript module.
app.ts has an import like import * as ts from "typescript".
│ tsconfig.json
├───node_modules
│ └───typescript
│ └───lib
│ typescript.d.ts
└───src
app.ts
Invoking the compiler with --traceResolution
tsc --traceResolution
Results in an output such as:
======== Resolving module 'typescript' from 'src/app.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module 'typescript' from 'node_modules' folder.
File 'src/node_modules/typescript.ts' does not exist.
File 'src/node_modules/typescript.tsx' does not exist.
File 'src/node_modules/typescript.d.ts' does not exist.
File 'src/node_modules/typescript/package.json' does not exist.
File 'node_modules/typescript.ts' does not exist.
File 'node_modules/typescript.tsx' does not exist.
File 'node_modules/typescript.d.ts' does not exist.
Found 'package.json' at 'node_modules/typescript/package.json'.
'package.json' has 'types' field './lib/typescript.d.ts' that references 'node_modules/typescript/lib/typescript.d.ts'.
File 'node_modules/typescript/lib/typescript.d.ts' exist - use it as a module resolution result.
======== Module name 'typescript' was successfully resolved to 'node_modules/typescript/lib/typescript.d.ts'. ========
======== Resolving module ‘typescript’ from ‘src/app.ts’. ========
Module resolution kind is not specified, using ‘NodeJs’.
‘package.json’ has ‘types’ field ‘./lib/typescript.d.ts’ that references ‘node_modules/typescript/lib/typescript.d.ts’.
======== Module name ‘typescript’ was successfully resolved to ‘node_modules/typescript/lib/typescript.d.ts’. ========
--noResolveNormally the compiler will attempt to resolve all module imports before it starts the compilation process.
Every time it successfully resolves an import to a file, the file is added to the set of files the compiler will process later on.
The --noResolve compiler options instructs the compiler not to “add” any files to the compilation that were not passed on the command line.
It will still try to resolve the module to files, but if the file is not specified, it will not be included.
For instance:
import * as A from "moduleA" // OK, 'moduleA' passed on the command-line
import * as B from "moduleB" // Error TS2307: Cannot find module 'moduleB'.
tsc app.ts moduleA.ts --noResolve
Compiling app.ts using --noResolve should result in:
moduleA as it was passed on the command-line.moduleB as it was not passed.tsconfig.json turns a folder into a “project”.
Without specifying any “exclude” or “files” entries, all files in the folder containing the tsconfig.json and all its sub-directories are included in your compilation.
If you want to exclude some of the files use “exclude”, if you would rather specify all the files instead of letting the compiler look them up, use “files”.
That was tsconfig.json automatic inclusion.
That does not embed module resolution as discussed above.
If the compiler identified a file as a target of a module import, it will be included in the compilation regardless if it was excluded in the previous steps.
So to exclude a file from the compilation, you need to exclude it and all files that have an import or /// <reference path="..." /> directive to it.
Some of the unique concepts in TypeScript describe the shape of JavaScript objects at the type level. One example that is especially unique to TypeScript is the concept of ‘declaration merging’. Understanding this concept will give you an advantage when working with existing JavaScript. It also opens the door to more advanced abstraction concepts.
For the purposes of this article, “declaration merging” means that the compiler merges two separate declarations declared with the same name into a single definition. This merged definition has the features of both of the original declarations. Any number of declarations can be merged; it’s not limited to just two declarations.
In TypeScript, a declaration creates entities in at least one of three groups: namespace, type, or value. Namespace-creating declarations create a namespace, which contains names that are accessed using a dotted notation. Type-creating declarations do just that: they create a type that is visible with the declared shape and bound to the given name. Lastly, value-creating declarations create values that are visible in the output JavaScript.
| Declaration Type | Namespace | Type | Value |
|---|---|---|---|
| Namespace | X | X | |
| Class | X | X | |
| Enum | X | X | |
| Interface | X | ||
| Type Alias | X | ||
| Function | X | ||
| Variable | X |
Understanding what is created with each declaration will help you understand what is merged when you perform a declaration merge.
The simplest, and perhaps most common, type of declaration merging is interface merging. At the most basic level, the merge mechanically joins the members of both declarations into a single interface with the same name.
interface Box {
height: number;
width: number;
}
interface Box {
scale: number;
}
let box: Box = {height: 5, width: 6, scale: 10};
Non-function members of the interfaces must be unique. The compiler will issue an error if the interfaces both declare a non-function member of the same name.
For function members, each function member of the same name is treated as describing an overload of the same function.
Of 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:
interface Cloner {
clone(animal: Animal): Animal;
}
interface Cloner {
clone(animal: Sheep): Sheep;
}
interface Cloner {
clone(animal: Dog): Dog;
clone(animal: Cat): Cat;
}
The three interfaces will merge to create a single declaration as so:
interface Cloner {
clone(animal: Dog): Dog;
clone(animal: Cat): Cat;
clone(animal: Sheep): Sheep;
clone(animal: Animal): Animal;
}
Notice that the elements of each group maintains the same order, but the groups themselves are merged with later overload sets ordered first.
One exception to this rule is specialized signatures. If 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.
For instance, the following interfaces will merge together:
interface Document {
createElement(tagName: any): Element;
}
interface Document {
createElement(tagName: "div"): HTMLDivElement;
createElement(tagName: "span"): HTMLSpanElement;
}
interface Document {
createElement(tagName: string): HTMLElement;
createElement(tagName: "canvas"): HTMLCanvasElement;
}
The resulting merged declaration of Document will be the following:
interface Document {
createElement(tagName: "canvas"): HTMLCanvasElement;
createElement(tagName: "div"): HTMLDivElement;
createElement(tagName: "span"): HTMLSpanElement;
createElement(tagName: string): HTMLElement;
createElement(tagName: any): Element;
}
Similarly to interfaces, namespaces of the same name will also merge their members. Since namespaces create both a namespace and a value, we need to understand how both merge.
To merge the namespaces, type definitions from exported interfaces declared in each namespace are themselves merged, forming a single namespace with merged interface definitions inside.
To 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.
The declaration merge of Animals in this example:
namespace Animals {
export class Zebra { }
}
namespace Animals {
export interface Legged { numberOfLegs: number; }
export class Dog { }
}
is equivalent to:
namespace Animals {
export interface Legged { numberOfLegs: number; }
export class Zebra { }
export class Dog { }
}
This model of namespace merging is a helpful starting place, but we also need to understand what happens with non-exported members. Non-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.
We can see this more clearly in this example:
namespace Animal {
let haveMuscles = true;
export function animalsHaveMuscles() {
return haveMuscles;
}
}
namespace Animal {
export function doAnimalsHaveMuscles() {
return haveMuscles; // <-- error, haveMuscles is not visible here
}
}
Because haveMuscles is not exported, only the animalsHaveMuscles function that shares the same un-merged namespace can see the symbol.
The 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. To do so, the namespace declaration must follow the declaration it will merge with. The resulting declaration has properties of both declaration types. TypeScript uses this capability to model some of the patterns in JavaScript as well as other programming languages.
This gives the user a way of describing inner classes.
class Album {
label: Album.AlbumLabel;
}
namespace Album {
export class AlbumLabel { }
}
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.
The end result is a class managed inside of another class.
You 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 JavaScript practice of creating a function and then extending the function further by adding properties onto the function. TypeScript uses declaration merging to build up definitions like this in a type-safe way.
function buildLabel(name: string): string {
return buildLabel.prefix + name + buildLabel.suffix;
}
namespace buildLabel {
export let suffix = "";
export let prefix = "Hello, ";
}
alert(buildLabel("Sam Smith"));
Similarly, namespaces can be used to extend enums with static members:
enum Color {
red = 1,
green = 2,
blue = 4
}
namespace Color {
export function mixColor(colorName: string) {
if (colorName == "yellow") {
return Color.red + Color.green;
}
else if (colorName == "white") {
return Color.red + Color.green + Color.blue;
}
else if (colorName == "magenta") {
return Color.red + Color.blue;
}
else if (colorName == "cyan") {
return Color.green + Color.blue;
}
}
}
Not all merges are allowed in TypeScript. Currently, classes can not merge with other classes or with variables. For information on mimicking class merging, see the Mixins in TypeScript section.
Although JavaScript modules do not support merging, you can patch existing objects by importing and then updating them. Let’s look at a toy Observable example:
// observable.js
export class Observable<T> {
// ... implementation left as an exercise for the reader ...
}
// map.js
import { Observable } from "./observable";
Observable.prototype.map = function (f) {
// ... another exercise for the reader
}
This works fine in TypeScript too, but the compiler doesn’t know about Observable.prototype.map.
You can use module augmentation to tell the compiler about it:
// observable.ts stays the same
// map.ts
import { Observable } from "./observable";
declare module "./observable" {
interface Observable<T> {
map<U>(f: (x: T) => U): Observable<U>;
}
}
Observable.prototype.map = function (f) {
// ... another exercise for the reader
}
// consumer.ts
import { Observable } from "./observable";
import "./map";
let o: Observable<number>;
o.map(x => x.toFixed());
The module name is resolved the same way as module specifiers in import/export.
See Modules for more information.
Then the declarations in an augmentation are merged as if they were declared in the same file as the original.
However, you can’t declare new top-level declarations in the augmentation – just patches to existing declarations.
You can also add declarations to the global scope from inside a module:
// observable.ts
export class Observable<T> {
// ... still no implementation ...
}
declare global {
interface Array<T> {
toObservable(): Observable<T>;
}
}
Array.prototype.toObservable = function () {
// ...
}
Global augmentations have the same behavior and limits as module augmentations.
JSX is an embeddable XML-like syntax. It is meant to be transformed into valid JavaScript, though the semantics of that transformation are implementation-specific. JSX came to popularity with the React framework, but has since seen other applications as well. TypeScript supports embedding, type checking, and compiling JSX directly into JavaScript.
In order to use JSX you must do two things.
.tsx extensionjsx optionTypeScript ships with three JSX modes: preserve, react, and react-native.
These modes only affect the emit stage - type checking is unaffected.
The preserve mode will keep the JSX as part of the output to be further consumed by another transform step (e.g. Babel).
Additionally the output will have a .jsx file extension.
The react mode will emit React.createElement, does not need to go through a JSX transformation before use, and the output will have a .js file extension.
The react-native mode is the equivalent of preserve in that it keeps all JSX, but the output will instead have a .js file extension.
| Mode | Input | Output | Output File Extension |
|---|---|---|---|
preserve |
<div /> |
<div /> |
.jsx |
react |
<div /> |
React.createElement("div") |
.js |
react-native |
<div /> |
<div /> |
.js |
You can specify this mode using either the --jsx command line flag or the corresponding option in your tsconfig.json file.
Note: The identifier
Reactis hard-coded, so you must make React available with an uppercase R.
as operatorRecall how to write a type assertion:
var foo = <foo>bar;
Here we are asserting the variable bar to have the type foo.
Since TypeScript also uses angle brackets for type assertions, JSX’s syntax introduces certain parsing difficulties. As a result, TypeScript disallows angle bracket type assertions in .tsx files.
To make up for this loss of functionality in .tsx files, a new type assertion operator has been added: as.
The above example can easily be rewritten with the as operator.
var foo = bar as foo;
The as operator is available in both .ts and .tsx files, and is identical in behavior to the other type assertion style.
In order to understand type checking with JSX, you must first understand the difference between intrinsic elements and value-based elements.
Given a JSX expression <expr />, expr may either refer to something intrinsic to the environment (e.g. a div or span in a DOM environment) or to a custom component that you’ve created.
This is important for two reasons:
React.createElement("div")), whereas a component you’ve created is not (React.createElement(MyComponent)).TypeScript uses the same convention that React does for distinguishing between these. An intrinsic element always begins with a lowercase letter, and a value-based element always begins with an uppercase letter.
Intrinsic elements are looked up on the special interface JSX.IntrinsicElements.
By default, if this interface is not specified, then anything goes and intrinsic elements will not be type checked.
However, if this interface is present, then the name of the intrinsic element is looked up as a property on the JSX.IntrinsicElements interface.
For example:
declare namespace JSX {
interface IntrinsicElements {
foo: any
}
}
<foo />; // ok
<bar />; // error
In the above example, <foo /> will work fine but <bar /> will result in an error since it has not been specified on JSX.IntrinsicElements.
Note: You can also specify a catch-all string indexer on
JSX.IntrinsicElementsas follows:declare namespace JSX { interface IntrinsicElements { [elemName: string]: any; } }
Value based elements are simply looked up by identifiers that are in scope.
import MyComponent from "./myComponent";
<MyComponent />; // ok
<SomeOtherComponent />; // error
It is possible to limit the type of a value-based element. However, for this we must introduce two new terms: the element class type and the element instance type.
Given <Expr />, the element class type is the type of Expr.
So in the example above, if MyComponent was an ES6 class the class type would be that class.
If MyComponent was a factory function, the class type would be that function.
Once the class type is established, the instance type is determined by the union of the return types of the class type’s call signatures and construct signatures. So again, in the case of an ES6 class, the instance type would be the type of an instance of that class, and in the case of a factory function, it would be the type of the value returned from the function.
class MyComponent {
render() {}
}
// use a construct signature
var myComponent = new MyComponent();
// element class type => MyComponent
// element instance type => { render: () => void }
function MyFactoryFunction() {
return {
render: () => {
}
}
}
// use a call signature
var myComponent = MyFactoryFunction();
// element class type => FactoryFunction
// element instance type => { render: () => void }
The element instance type is interesting because it must be assignable to JSX.ElementClass or it will result in an error.
By default JSX.ElementClass is {}, but it can be augmented to limit the use of JSX to only those types that conform to the proper interface.
declare namespace JSX {
interface ElementClass {
render: any;
}
}
class MyComponent {
render() {}
}
function MyFactoryFunction() {
return { render: () => {} }
}
<MyComponent />; // ok
<MyFactoryFunction />; // ok
class NotAValidComponent {}
function NotAValidFactoryFunction() {
return {};
}
<NotAValidComponent />; // error
<NotAValidFactoryFunction />; // error
The first step to type checking attributes is to determine the element attributes type. This is slightly different between intrinsic and value-based elements.
For intrinsic elements, it is the type of the property on JSX.IntrinsicElements
declare namespace JSX {
interface IntrinsicElements {
foo: { bar?: boolean }
}
}
// element attributes type for 'foo' is '{bar?: boolean}'
<foo bar />;
For value-based elements, it is a bit more complex.
It is determined by the type of a property on the element instance type that was previously determined.
Which property to use is determined by JSX.ElementAttributesProperty.
It should be declared with a single property.
The name of that property is then used.
declare namespace JSX {
interface ElementAttributesProperty {
props; // specify the property name to use
}
}
class MyComponent {
// specify the property on the element instance type
props: {
foo?: string;
}
}
// element attributes type for 'MyComponent' is '{foo?: string}'
<MyComponent foo="bar" />
The element attribute type is used to type check the attributes in the JSX. Optional and required properties are supported.
declare namespace JSX {
interface IntrinsicElements {
foo: { requiredProp: string; optionalProp?: number }
}
}
<foo requiredProp="bar" />; // ok
<foo requiredProp="bar" optionalProp={0} />; // ok
<foo />; // error, requiredProp is missing
<foo requiredProp={0} />; // error, requiredProp should be a string
<foo requiredProp="bar" unknownProp />; // error, unknownProp does not exist
<foo requiredProp="bar" some-unknown-prop />; // ok, because 'some-unknown-prop' is not a valid identifier
Note: If an attribute name is not a valid JS identifier (like a
data-*attribute), it is not considered to be an error if it is not found in the element attributes type.
The spread operator also works:
var props = { requiredProp: "bar" };
<foo {...props} />; // ok
var badProps = {};
<foo {...badProps} />; // error
By default the result of a JSX expression is typed as any.
You can customize the type by specifying the JSX.Element interface.
However, it is not possible to retrieve type information about the element, attributes or children of the JSX from this interface.
It is a black box.
JSX allows you to embed expressions between tags by surrounding the expressions with curly braces ({ }).
var a = <div>
{["foo", "bar"].map(i => <span>{i / 2}</span>)}
</div>
The above code will result in an error since you cannot divide a string by a number.
The output, when using the preserve option, looks like:
var a = <div>
{["foo", "bar"].map(function (i) { return <span>{i / 2}</span>; })}
</div>
To use JSX with React you should use the React typings.
These typings define the JSX namespace appropriately for use with React.
/// <reference path="react.d.ts" />
interface Props {
foo: string;
}
class MyComponent extends React.Component<Props, {}> {
render() {
return <span>{this.props.foo}</span>
}
}
<MyComponent foo="bar" />; // ok
<MyComponent foo={0} />; // error
With the introduction of Classes in TypeScript and ES6, there now exist certain scenarios that require additional features to support annotating or modifying classes and class members. Decorators provide a way to add both annotations and a meta-programming syntax for class declarations and members. Decorators are a stage 2 proposal for JavaScript and are available as an experimental feature of TypeScript.
NOTE Decorators are an experimental feature that may change in future releases.
To enable experimental support for decorators, you must enable the experimentalDecorators compiler option either on the command line or in your tsconfig.json:
Command Line:
tsc --target ES5 --experimentalDecorators
tsconfig.json:
{
"compilerOptions": {
"target": "ES5",
"experimentalDecorators": true
}
}
A Decorator is a special kind of declaration that can be attached to a class declaration, method, accessor, property, or parameter.
Decorators use the form @expression, where expression must evaluate to a function that will be called at runtime with information about the decorated declaration.
For example, given the decorator @sealed we might write the sealed function as follows:
function sealed(target) {
// do something with 'target' ...
}
NOTE You can see a more detailed example of a decorator in Class Decorators, below.
If we want to customize how a decorator is applied to a declaration, we can write a decorator factory. A Decorator Factory is simply a function that returns the expression that will be called by the decorator at runtime.
We can write a decorator factory in the following fashion:
function color(value: string) { // this is the decorator factory
return function (target) { // this is the decorator
// do something with 'target' and 'value'...
}
}
NOTE You can see a more detailed example of a decorator factory in Method Decorators, below.
Multiple decorators can be applied to a declaration, as in the following examples:
On a single line:
@f @g x
On multiple lines:
@f
@g
x
When multiple decorators apply to a single declaration, their evaluation is similar to function composition in mathematics. In this model, when composing functions f and g, the resulting composite (f ∘ g)(x) is equivalent to f(g(x)).
As such, the following steps are performed when evaluating multiple decorators on a single declaration in TypeScript:
If we were to use decorator factories, we can observe this evaluation order with the following example:
function f() {
console.log("f(): evaluated");
return function (target, propertyKey: string, descriptor: PropertyDescriptor) {
console.log("f(): called");
}
}
function g() {
console.log("g(): evaluated");
return function (target, propertyKey: string, descriptor: PropertyDescriptor) {
console.log("g(): called");
}
}
class C {
@f()
@g()
method() {}
}
Which would print this output to the console:
f(): evaluated
g(): evaluated
g(): called
f(): called
There is a well defined order to how decorators applied to various declarations inside of a class are applied:
A Class Decorator is declared just before a class declaration.
The class decorator is applied to the constructor of the class and can be used to observe, modify, or replace a class definition.
A class decorator cannot be used in a declaration file, or in any other ambient context (such as on a declare class).
The expression for the class decorator will be called as a function at runtime, with the constructor of the decorated class as its only argument.
If the class decorator returns a value, it will replace the class declaration with the provided constructor function.
NOTE Should you chose to return a new constructor function, you must take care to maintain the original prototype. The logic that applies decorators at runtime will not do this for you.
The following is an example of a class decorator (@sealed) applied to the Greeter class:
@sealed
class Greeter {
greeting: string;
constructor(message: string) {
this.greeting = message;
}
greet() {
return "Hello, " + this.greeting;
}
}
We can define the @sealed decorator using the following function declaration:
function sealed(constructor: Function) {
Object.seal(constructor);
Object.seal(constructor.prototype);
}
When @sealed is executed, it will seal both the constructor and its prototype.
Next we have an example of how to override the constructor.
function classDecorator<T extends {new(...args:any[]):{}}>(constructor:T) {
return class extends constructor {
newProperty = "new property";
hello = "override";
}
}
@classDecorator
class Greeter {
property = "property";
hello: string;
constructor(m: string) {
this.hello = m;
}
}
console.log(new Greeter("world"));
A Method Decorator is declared just before a method declaration.
The decorator is applied to the Property Descriptor for the method, and can be used to observe, modify, or replace a method definition.
A method decorator cannot be used in a declaration file, on an overload, or in any other ambient context (such as in a declare class).
The expression for the method decorator will be called as a function at runtime, with the following three arguments:
NOTE The Property Descriptor will be
undefinedif your script target is less thanES5.
If the method decorator returns a value, it will be used as the Property Descriptor for the method.
NOTE The return value is ignored if your script target is less than
ES5.
The following is an example of a method decorator (@enumerable) applied to a method on the Greeter class:
class Greeter {
greeting: string;
constructor(message: string) {
this.greeting = message;
}
@enumerable(false)
greet() {
return "Hello, " + this.greeting;
}
}
We can define the @enumerable decorator using the following function declaration:
function enumerable(value: boolean) {
return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
descriptor.enumerable = value;
};
}
The @enumerable(false) decorator here is a decorator factory.
When the @enumerable(false) decorator is called, it modifies the enumerable property of the property descriptor.
An Accessor Decorator is declared just before an accessor declaration.
The accessor decorator is applied to the Property Descriptor for the accessor and can be used to observe, modify, or replace an accessor’s definitions.
An accessor decorator cannot be used in a declaration file, or in any other ambient context (such as in a declare class).
NOTE TypeScript disallows decorating both the
getandsetaccessor for a single member. Instead, all decorators for the member must be applied to the first accessor specified in document order. This is because decorators apply to a Property Descriptor, which combines both thegetandsetaccessor, not each declaration separately.
The expression for the accessor decorator will be called as a function at runtime, with the following three arguments:
NOTE The Property Descriptor will be
undefinedif your script target is less thanES5.
If the accessor decorator returns a value, it will be used as the Property Descriptor for the member.
NOTE The return value is ignored if your script target is less than
ES5.
The following is an example of an accessor decorator (@configurable) applied to a member of the Point class:
class Point {
private _x: number;
private _y: number;
constructor(x: number, y: number) {
this._x = x;
this._y = y;
}
@configurable(false)
get x() { return this._x; }
@configurable(false)
get y() { return this._y; }
}
We can define the @configurable decorator using the following function declaration:
function configurable(value: boolean) {
return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
descriptor.configurable = value;
};
}
A Property Decorator is declared just before a property declaration.
A property decorator cannot be used in a declaration file, or in any other ambient context (such as in a declare class).
The expression for the property decorator will be called as a function at runtime, with the following two arguments:
NOTE A Property Descriptor is not provided as an argument to a property decorator due to how property decorators are initialized in TypeScript. This is because there is currently no mechanism to describe an instance property when defining members of a prototype, and no way to observe or modify the initializer for a property. The return value is ignored too. As such, a property decorator can only be used to observe that a property of a specific name has been declared for a class.
We can use this information to record metadata about the property, as in the following example:
class Greeter {
@format("Hello, %s")
greeting: string;
constructor(message: string) {
this.greeting = message;
}
greet() {
let formatString = getFormat(this, "greeting");
return formatString.replace("%s", this.greeting);
}
}
We can then define the @format decorator and getFormat functions using the following function declarations:
import "reflect-metadata";
const formatMetadataKey = Symbol("format");
function format(formatString: string) {
return Reflect.metadata(formatMetadataKey, formatString);
}
function getFormat(target: any, propertyKey: string) {
return Reflect.getMetadata(formatMetadataKey, target, propertyKey);
}
The @format("Hello, %s") decorator here is a decorator factory.
When @format("Hello, %s") is called, it adds a metadata entry for the property using the Reflect.metadata function from the reflect-metadata library.
When getFormat is called, it reads the metadata value for the format.
NOTE This example requires the
reflect-metadatalibrary. See Metadata for more information about thereflect-metadatalibrary.
A Parameter Decorator is declared just before a parameter declaration.
The parameter decorator is applied to the function for a class constructor or method declaration.
A parameter decorator cannot be used in a declaration file, an overload, or in any other ambient context (such as in a declare class).
The expression for the parameter decorator will be called as a function at runtime, with the following three arguments:
NOTE A parameter decorator can only be used to observe that a parameter has been declared on a method.
The return value of the parameter decorator is ignored.
The following is an example of a parameter decorator (@required) applied to parameter of a member of the Greeter class:
class Greeter {
greeting: string;
constructor(message: string) {
this.greeting = message;
}
@validate
greet(@required name: string) {
return "Hello " + name + ", " + this.greeting;
}
}
We can then define the @required and @validate decorators using the following function declarations:
import "reflect-metadata";
const requiredMetadataKey = Symbol("required");
function required(target: Object, propertyKey: string | symbol, parameterIndex: number) {
let existingRequiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
existingRequiredParameters.push(parameterIndex);
Reflect.defineMetadata(requiredMetadataKey, existingRequiredParameters, target, propertyKey);
}
function validate(target: any, propertyName: string, descriptor: TypedPropertyDescriptor<Function>) {
let method = descriptor.value;
descriptor.value = function () {
let requiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyName);
if (requiredParameters) {
for (let parameterIndex of requiredParameters) {
if (parameterIndex >= arguments.length || arguments[parameterIndex] === undefined) {
throw new Error("Missing required argument.");
}
}
}
return method.apply(this, arguments);
}
}
The @required decorator adds a metadata entry that marks the parameter as required.
The @validate decorator then wraps the existing greet method in a function that validates the arguments before invoking the original method.
NOTE This example requires the
reflect-metadatalibrary. See Metadata for more information about thereflect-metadatalibrary.
Some examples use the reflect-metadata library which adds a polyfill for an experimental metadata API.
This library is not yet part of the ECMAScript (JavaScript) standard.
However, once decorators are officially adopted as part of the ECMAScript standard these extensions will be proposed for adoption.
You can install this library via npm:
npm i reflect-metadata --save
TypeScript includes experimental support for emitting certain types of metadata for declarations that have decorators.
To enable this experimental support, you must set the emitDecoratorMetadata compiler option either on the command line or in your tsconfig.json:
Command Line:
tsc --target ES5 --experimentalDecorators --emitDecoratorMetadata
tsconfig.json:
{
"compilerOptions": {
"target": "ES5",
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
When enabled, as long as the reflect-metadata library has been imported, additional design-time type information will be exposed at runtime.
We can see this in action in the following example:
import "reflect-metadata";
class Point {
x: number;
y: number;
}
class Line {
private _p0: Point;
private _p1: Point;
@validate
set p0(value: Point) { this._p0 = value; }
get p0() { return this._p0; }
@validate
set p1(value: Point) { this._p1 = value; }
get p1() { return this._p1; }
}
function validate<T>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) {
let set = descriptor.set;
descriptor.set = function (value: T) {
let type = Reflect.getMetadata("design:type", target, propertyKey);
if (!(value instanceof type)) {
throw new TypeError("Invalid type.");
}
set(value);
}
}
The TypeScript compiler will inject design-time type information using the @Reflect.metadata decorator.
You could consider it the equivalent of the following TypeScript:
class Line {
private _p0: Point;
private _p1: Point;
@validate
@Reflect.metadata("design:type", Point)
set p0(value: Point) { this._p0 = value; }
get p0() { return this._p0; }
@validate
@Reflect.metadata("design:type", Point)
set p1(value: Point) { this._p1 = value; }
get p1() { return this._p1; }
}
NOTE Decorator metadata is an experimental feature and may introduce breaking changes in future releases.
Along with traditional OO hierarchies, another popular way of building up classes from reusable components is to build them by combining simpler partial classes. You may be familiar with the idea of mixins or traits for languages like Scala, and the pattern has also reached some popularity in the JavaScript community.
In the code below, we show how you can model mixins in TypeScript. After the code, we’ll break down how it works.
// Disposable Mixin
class Disposable {
isDisposed: boolean;
dispose() {
this.isDisposed = true;
}
}
// Activatable Mixin
class Activatable {
isActive: boolean;
activate() {
this.isActive = true;
}
deactivate() {
this.isActive = false;
}
}
class SmartObject implements Disposable, Activatable {
constructor() {
setInterval(() => console.log(this.isActive + " : " + this.isDisposed), 500);
}
interact() {
this.activate();
}
// Disposable
isDisposed: boolean = false;
dispose: () => void;
// Activatable
isActive: boolean = false;
activate: () => void;
deactivate: () => void;
}
applyMixins(SmartObject, [Disposable, Activatable]);
let smartObj = new SmartObject();
setTimeout(() => smartObj.interact(), 1000);
////////////////////////////////////////
// In your runtime library somewhere
////////////////////////////////////////
function applyMixins(derivedCtor: any, baseCtors: any[]) {
baseCtors.forEach(baseCtor => {
Object.getOwnPropertyNames(baseCtor.prototype).forEach(name => {
derivedCtor.prototype[name] = baseCtor.prototype[name];
});
});
}
The code sample starts with the two classes that will act as our mixins. You can see each one is focused on a particular activity or capability. We’ll later mix these together to form a new class from both capabilities.
// Disposable Mixin
class Disposable {
isDisposed: boolean;
dispose() {
this.isDisposed = true;
}
}
// Activatable Mixin
class Activatable {
isActive: boolean;
activate() {
this.isActive = true;
}
deactivate() {
this.isActive = false;
}
}
Next, we’ll create the class that will handle the combination of the two mixins. Let’s look at this in more detail to see how it does this:
class SmartObject implements Disposable, Activatable {
The first thing you may notice in the above is that instead of using extends, we use implements.
This treats the classes as interfaces, and only uses the types behind Disposable and Activatable rather than the implementation.
This means that we’ll have to provide the implementation in class.
Except, that’s exactly what we want to avoid by using mixins.
To satisfy this requirement, we create stand-in properties and their types for the members that will come from our mixins. This satisfies the compiler that these members will be available at runtime. This lets us still get the benefit of the mixins, albeit with some bookkeeping overhead.
// Disposable
isDisposed: boolean = false;
dispose: () => void;
// Activatable
isActive: boolean = false;
activate: () => void;
deactivate: () => void;
Finally, we mix our mixins into the class, creating the full implementation.
applyMixins(SmartObject, [Disposable, Activatable]);
Lastly, we create a helper function that will do the mixing for us. This will run through the properties of each of the mixins and copy them over to the target of the mixins, filling out the stand-in properties with their implementations.
function applyMixins(derivedCtor: any, baseCtors: any[]) {
baseCtors.forEach(baseCtor => {
Object.getOwnPropertyNames(baseCtor.prototype).forEach(name => {
derivedCtor.prototype[name] = baseCtor.prototype[name];
});
});
}
Triple-slash directives are single-line comments containing a single XML tag. The contents of the comment are used as compiler directives.
Triple-slash directives are only valid at the top of their containing file. A triple-slash directive can only be preceded by single or multi-line comments, including other triple-slash directives. If they are encountered following a statement or a declaration they are treated as regular single-line comments, and hold no special meaning.
/// <reference path="..." />The /// <reference path="..." /> directive is the most common of this group.
It serves as a declaration of dependency between files.
Triple-slash references instruct the compiler to include additional files in the compilation process.
They also serve as a method to order the output when using --out or --outFile.
Files are emitted to the output file location in the same order as the input after preprocessing pass.
The compiler performs a preprocessing pass on input files to resolve all triple-slash reference directives. During this process, additional files are added to the compilation.
The process starts with a set of root files;
these are the file names specified on the command-line or in the "files" list in the tsconfig.json file.
These root files are preprocessed in the same order they are specified.
Before a file is added to the list, all triple-slash references in it are processed, and their targets included.
Triple-slash references are resolved in a depth first manner, in the order they have been seen in the file.
A triple-slash reference path is resolved relative to the containing file, if unrooted.
It is an error to reference a file that does not exist. It is an error for a file to have a triple-slash reference to itself.
--noResolveIf the compiler flag --noResolve is specified, triple-slash references are ignored; they neither result in adding new files, nor change the order of the files provided.
/// <reference types="..." />Similar to a /// <reference path="..." /> directive, this directive serves as a declaration of dependency;
a /// <reference types="..." />, however, declares a dependency on an @types package.
Including /// <reference types="node" /> in a declaration file declares that this file uses names declared in @types/node/index.d.ts;
and thus, this package needs to be included in the compilation along with the declaration file.
The process of resolving these @types package names are similar to process of resolving module names in an import statement.
An easy way to think of triple-slash-reference-types directives as an import for declaration packages.
Use these directives only when you’re authoring a d.ts file by hand.
For declaration files generated during compilation, the compiler will automatically add /// <reference types="..." /> for you;
A /// <reference types="..." /> in a generated declaration file is added if and only if the resulting file uses any declarations from the referenced @types package.
For declaring a dependency on an @types package in a .ts file, use --types on the command line or in your tsconfig.json instead.
See using @types, typeRoots and types in tsconfig.json files for more details.
/// <reference no-default-lib="true"/>This directive marks a file as a default library.
You will see this comment at the top of lib.d.ts and its different variants.
This directive instructs the compiler to not include the default library (i.e. lib.d.ts) in the compilation.
The impact here is similar to passing --noLib on the command line.
Also note that when passing --skipDefaultLibCheck, the compiler will only skip checking files with /// <reference no-default-lib="true"/>.
/// <amd-module />By default AMD modules are generated anonymous.
This can lead to problems when other tools are used to process the resulting modules, such as bundlers (e.g. r.js).
The amd-module directive allows passing an optional module name to the compiler:
///<amd-module name="NamedModule"/>
export class C {
}
Will result in assigning the name NamedModule to the module as part of calling the AMD define:
define("NamedModule", ["require", "exports"], function (require, exports) {
var C = (function () {
function C() {
}
return C;
})();
exports.C = C;
});
/// <amd-dependency />Note: this directive has been deprecated. Use
import "moduleName";statements instead.
/// <amd-dependency path="x" /> informs the compiler about a non-TS module dependency that needs to be injected in the resulting module’s require call.
The amd-dependency directive can also have an optional name property; this allows passing an optional name for an amd-dependency:
/// <amd-dependency path="legacy/moduleA" name="moduleA"/>
declare var moduleA:MyType
moduleA.callStuff()
Generated JS code:
define(["require", "exports", "legacy/moduleA"], function (require, exports, moduleA) {
moduleA.callStuff()
});