One of TypeScript’s core principles is that type checking focuses on the shape that values have.\nThis is sometimes called “duck typing” or “structural subtyping”.\nIn TypeScript, interfaces fill the role of naming these types, and are a powerful way of defining contracts within your code as well as contracts with code outside of your project.
\nThe easiest way to see how interfaces work is to start with a simple example:
\n\ntsfunction printLabel(labeledObj: { label: string }) {\n console.log(labeledObj.label);\n}\n\nlet myObj = { size: 10, label: \"Size 10 Object\" };\nprintLabel(myObj);
The type checker checks the call to printLabel.\nThe printLabel function has a single parameter that requires that the object passed in has a property called label of type string.\nNotice that our object actually has more properties than this, but the compiler only checks that at least the ones required are present and match the types required.\nThere are some cases where TypeScript isn’t as lenient, which we’ll cover in a bit.
We can write the same example again, this time using an interface to describe the requirement of having the label property that is a string:
\ntsinterface LabeledValue {\n label: string;\n}\n\nfunction printLabel(labeledObj: LabeledValue) {\n console.log(labeledObj.label);\n}\n\nlet myObj = { size: 10, label: \"Size 10 Object\" };\nprintLabel(myObj);
The interface LabeledValue is a name we can now use to describe the requirement in the previous example.\nIt still represents having a single property called label that is of type string.\nNotice we didn’t have to explicitly say that the object we pass to printLabel implements this interface like we might have to in other languages.\nHere, it’s only the shape that matters. If the object we pass to the function meets the requirements listed, then it’s allowed.
It’s worth pointing out that the type checker does not require that these properties come in any sort of order, only that the properties the interface requires are present and have the required type.
\nNot all properties of an interface may be required.\nSome exist under certain conditions or may not be there at all.\nThese optional properties are popular when creating patterns like “option bags” where you pass an object to a function that only has a couple of properties filled in.
\nHere’s an example of this pattern:
\n\ntsinterface SquareConfig {\n color?: string;\n width?: number;\n}\n\nfunction createSquare(config: SquareConfig): { color: string; area: number } {\n let newSquare = { color: \"white\", area: 100 };\n if (config.color) {\n newSquare.color = config.color;\n }\n if (config.width) {\n newSquare.area = config.width * config.width;\n }\n return newSquare;\n}\n\nlet mySquare = createSquare({ color: \"black\" });
Interfaces with optional properties are written similar to other interfaces, with each optional property denoted by a ? at the end of the property name in the declaration.
The advantage of optional properties is that you can describe these possibly available properties while still also preventing use of properties that are not part of the interface.\nFor example, had we mistyped the name of the color property in createSquare, we would get an error message letting us know:
\ntsinterface SquareConfig {\n color?: string;\n width?: number;\n}\n\nfunction createSquare(config: SquareConfig): { color: string; area: number } {\n let newSquare = { color: \"white\", area: 100 };\n if (config.clor) {\n // Error: Property 'clor' does not exist on type 'SquareConfig'\n newSquare.color = config.clor;\n }\n if (config.width) {\n newSquare.area = config.width * config.width;\n }\n return newSquare;\n}\n\nlet mySquare = createSquare({ color: \"black\" });
Some properties should only be modifiable when an object is first created.\nYou can specify this by putting readonly before the name of the property:
\ntsinterface Point {\n readonly x: number;\n readonly y: number;\n}
You can construct a Point by assigning an object literal.\nAfter the assignment, x and y can’t be changed.
\ntslet p1: Point = { x: 10, y: 20 };\np1.x = 5; // error!
TypeScript comes with a ReadonlyArray<T> type that is the same as Array<T> with all mutating methods removed, so you can make sure you don’t change your arrays after creation:
\ntslet a: number[] = [1, 2, 3, 4];\nlet ro: ReadonlyArray<number> = a;\nro[0] = 12; // error!\nro.push(5); // error!\nro.length = 100; // error!\na = ro; // error!
On the last line of the snippet you can see that even assigning the entire ReadonlyArray back to a normal array is illegal.\nYou can still override it with a type assertion, though:
\ntsa = ro as number[];
readonly vs constThe easiest way to remember whether to use readonly or const is to ask whether you’re using it on a variable or a property.\nVariables use const whereas properties use readonly.
In our first example using interfaces, TypeScript lets us pass { size: number; label: string; } to something that only expected a { label: string; }.\nWe also just learned about optional properties, and how they’re useful when describing so-called “option bags”.
However, combining the two naively would allow an error to sneak in. For example, taking our last example using createSquare:
\ntsinterface SquareConfig {\n color?: string;\n width?: number;\n}\n\nfunction createSquare(config: SquareConfig): { color: string; area: number } {\n // ...\n}\n\nlet mySquare = createSquare({ colour: \"red\", width: 100 });
Notice the given argument to createSquare is spelled colour instead of color.\nIn plain JavaScript, this sort of thing fails silently.
You could argue that this program is correctly typed, since the width properties are compatible, there’s no color property present, and the extra colour property is insignificant.
However, TypeScript takes the stance that there’s probably a bug in this code.\nObject literals get special treatment and undergo excess property checking when assigning them to other variables, or passing them as arguments.\nIf an object literal has any properties that the “target type” doesn’t have, you’ll get an error:
\n\nts// error: Object literal may only specify known properties, but 'colour' does not exist in type 'SquareConfig'. Did you mean to write 'color'?\nlet mySquare = createSquare({ colour: \"red\", width: 100 });
Getting around these checks is actually really simple.\nThe easiest method is to just use a type assertion:
\n\ntslet mySquare = createSquare({ width: 100, opacity: 0.5 } as SquareConfig);
However, a better approach might be to add a string index signature if you’re sure that the object can have some extra properties that are used in some special way.\nIf SquareConfig can have color and width properties with the above types, but could also have any number of other properties, then we could define it like so:
\ntsinterface SquareConfig {\n color?: string;\n width?: number;\n [propName: string]: any;\n}
We’ll discuss index signatures in a bit, but here we’re saying a SquareConfig can have any number of properties, and as long as they aren’t color or width, their types don’t matter.
One final way to get around these checks, which might be a bit surprising, is to assign the object to another variable:\nSince squareOptions won’t undergo excess property checks, the compiler won’t give you an error.
\ntslet squareOptions = { colour: \"red\", width: 100 };\nlet mySquare = createSquare(squareOptions);
The above workaround will work as long as you have a common property between squareOptions and SquareConfig.\nIn this example, it was the property width. It will however, fail if the variable does not have any common object property. For example:
\ntslet squareOptions = { colour: \"red\" };\nlet mySquare = createSquare(squareOptions);
Keep in mind that for simple code like above, you probably shouldn’t be trying to “get around” these checks.\nFor more complex object literals that have methods and hold state, you might need to keep these techniques in mind, but a majority of excess property errors are actually bugs.\nThat means if you’re running into excess property checking problems for something like option bags, you might need to revise some of your type declarations.\nIn this instance, if it’s okay to pass an object with both a color or colour property to createSquare, you should fix up the definition of SquareConfig to reflect that.
Interfaces are capable of describing the wide range of shapes that JavaScript objects can take.\nIn addition to describing an object with properties, interfaces are also capable of describing function types.
\nTo describe a function type with an interface, we give the interface a call signature.\nThis is like a function declaration with only the parameter list and return type given. Each parameter in the parameter list requires both name and type.
\n\ntsinterface SearchFunc {\n (source: string, subString: string): boolean;\n}
Once defined, we can use this function type interface like we would other interfaces.\nHere, we show how you can create a variable of a function type and assign it a function value of the same type.
\n\ntslet mySearch: SearchFunc;\nmySearch = function(source: string, subString: string) {\n let result = source.search(subString);\n return result > -1;\n};
For function types to correctly type check, the names of the parameters do not need to match.\nWe could have, for example, written the above example like this:
\n\ntslet mySearch: SearchFunc;\nmySearch = function(src: string, sub: string): boolean {\n let result = src.search(sub);\n return result > -1;\n};
Function parameters are checked one at a time, with the type in each corresponding parameter position checked against each other.\nIf you do not want to specify types at all, TypeScript’s contextual typing can infer the argument types since the function value is assigned directly to a variable of type SearchFunc.\nHere, also, the return type of our function expression is implied by the values it returns (here false and true).
\ntslet mySearch: SearchFunc;\nmySearch = function(src, sub) {\n let result = src.search(sub);\n return result > -1;\n};
Had the function expression returned numbers or strings, the type checker would have made an error that indicates return type doesn’t match the return type described in the SearchFunc interface.
\ntslet mySearch: SearchFunc;\n\n// error: Type '(src: string, sub: string) => string' is not assignable to type 'SearchFunc'.\n// Type 'string' is not assignable to type 'boolean'.\nmySearch = function(src, sub) {\n let result = src.search(sub);\n return \"string\";\n};
Similarly to how we can use interfaces to describe function types, we can also describe types that we can “index into” like a[10], or ageMap[\"daniel\"].\nIndexable types have an index signature that describes the types we can use to index into the object, along with the corresponding return types when indexing.\nLet’s take an example:
\ntsinterface StringArray {\n [index: number]: string;\n}\n\nlet myArray: StringArray;\nmyArray = [\"Bob\", \"Fred\"];\n\nlet myStr: string = myArray[0];
Above, we have a StringArray interface that has an index signature.\nThis index signature states that when a StringArray is indexed with a number, it will return a string.
There are two types of supported index signatures: string and number.\nIt is possible to support both types of indexers, but the type returned from a numeric indexer must be a subtype of the type returned from the string indexer.\nThis is because when indexing with a number, JavaScript will actually convert that to a string before indexing into an object.\nThat means that indexing with 100 (a number) is the same thing as indexing with \"100\" (a string), so the two need to be consistent.
\ntsclass Animal {\n name: string;\n}\nclass Dog extends Animal {\n breed: string;\n}\n\n// Error: indexing with a numeric string might get you a completely separate type of Animal!\ninterface NotOkay {\n [x: number]: Animal;\n [x: string]: Dog;\n}
While string index signatures are a powerful way to describe the “dictionary” pattern, they also enforce that all properties match their return type.\nThis is because a string index declares that obj.property is also available as obj[\"property\"].\nIn the following example, name’s type does not match the string index’s type, and the type checker gives an error:
\ntsinterface NumberDictionary {\n [index: string]: number;\n length: number; // ok, length is a number\n name: string; // error, the type of 'name' is not a subtype of the indexer\n}
However, properties of different types are acceptable if the index signature is a union of the property types:
\n\ntsinterface NumberOrStringDictionary {\n [index: string]: number | string;\n length: number; // ok, length is a number\n name: string; // ok, name is a string\n}
Finally, you can make index signatures readonly in order to prevent assignment to their indices:
\ntsinterface ReadonlyStringArray {\n readonly [index: number]: string;\n}\nlet myArray: ReadonlyStringArray = [\"Alice\", \"Bob\"];\nmyArray[2] = \"Mallory\"; // error!
You can’t set myArray[2] because the index signature is readonly.
One of the most common uses of interfaces in languages like C# and Java, that of explicitly enforcing that a class meets a particular contract, is also possible in TypeScript.
\n\ntsinterface ClockInterface {\n currentTime: Date;\n}\n\nclass Clock implements ClockInterface {\n currentTime: Date = new Date();\n constructor(h: number, m: number) {}\n}
You can also describe methods in an interface that are implemented in the class, as we do with setTime in the below example:
\ntsinterface ClockInterface {\n currentTime: Date;\n setTime(d: Date): void;\n}\n\nclass Clock implements ClockInterface {\n currentTime: Date = new Date();\n setTime(d: Date) {\n this.currentTime = d;\n }\n constructor(h: number, m: number) {}\n}
Interfaces describe the public side of the class, rather than both the public and private side.\nThis prohibits you from using them to check that a class also has particular types for the private side of the class instance.
\nWhen working with classes and interfaces, it helps to keep in mind that a class has two types: the type of the static side and the type of the instance side.\nYou may notice that if you create an interface with a construct signature and try to create a class that implements this interface you get an error:
\n\ntsinterface ClockConstructor {\n new (hour: number, minute: number);\n}\n\nclass Clock implements ClockConstructor {\n currentTime: Date;\n constructor(h: number, m: number) {}\n}
This is because when a class implements an interface, only the instance side of the class is checked.\nSince the constructor sits in the static side, it is not included in this check.
\nInstead, you would need to work with the static side of the class directly.\nIn this example, we define two interfaces, ClockConstructor for the constructor and ClockInterface for the instance methods.\nThen, for convenience, we define a constructor function createClock that creates instances of the type that is passed to it:
\ntsinterface ClockConstructor {\n new (hour: number, minute: number): ClockInterface;\n}\ninterface ClockInterface {\n tick(): void;\n}\n\nfunction createClock(\n ctor: ClockConstructor,\n hour: number,\n minute: number\n): ClockInterface {\n return new ctor(hour, minute);\n}\n\nclass DigitalClock implements ClockInterface {\n constructor(h: number, m: number) {}\n tick() {\n console.log(\"beep beep\");\n }\n}\nclass AnalogClock implements ClockInterface {\n constructor(h: number, m: number) {}\n tick() {\n console.log(\"tick tock\");\n }\n}\n\nlet digital = createClock(DigitalClock, 12, 17);\nlet analog = createClock(AnalogClock, 7, 32);
Because createClock’s first parameter is of type ClockConstructor, in createClock(AnalogClock, 7, 32), it checks that AnalogClock has the correct constructor signature.
Another simple way is to use class expressions:
\n\ntsinterface ClockConstructor {\n new (hour: number, minute: number);\n}\n\ninterface ClockInterface {\n tick();\n}\n\nconst Clock: ClockConstructor = class Clock implements ClockInterface {\n constructor(h: number, m: number) {}\n tick() {\n console.log(\"beep beep\");\n }\n};
Like classes, interfaces can extend each other.\nThis allows you to copy the members of one interface into another, which gives you more flexibility in how you separate your interfaces into reusable components.
\n\ntsinterface Shape {\n color: string;\n}\n\ninterface Square extends Shape {\n sideLength: number;\n}\n\nlet square = {} as Square;\nsquare.color = \"blue\";\nsquare.sideLength = 10;
An interface can extend multiple interfaces, creating a combination of all of the interfaces.
\n\ntsinterface Shape {\n color: string;\n}\n\ninterface PenStroke {\n penWidth: number;\n}\n\ninterface Square extends Shape, PenStroke {\n sideLength: number;\n}\n\nlet square = {} as Square;\nsquare.color = \"blue\";\nsquare.sideLength = 10;\nsquare.penWidth = 5.0;
As we mentioned earlier, interfaces can describe the rich types present in real world JavaScript.\nBecause of JavaScript’s dynamic and flexible nature, you may occasionally encounter an object that works as a combination of some of the types described above.
\nOne such example is an object that acts as both a function and an object, with additional properties:
\n\ntsinterface Counter {\n (start: number): string;\n interval: number;\n reset(): void;\n}\n\nfunction getCounter(): Counter {\n let counter = function(start: number) {} as Counter;\n counter.interval = 123;\n counter.reset = function() {};\n return counter;\n}\n\nlet c = getCounter();\nc(10);\nc.reset();\nc.interval = 5.0;
When interacting with 3rd-party JavaScript, you may need to use patterns like the above to fully describe the shape of the type.
\nWhen an interface type extends a class type it inherits the members of the class but not their implementations.\nIt is as if the interface had declared all of the members of the class without providing an implementation.\nInterfaces inherit even the private and protected members of a base class.\nThis means that when you create an interface that extends a class with private or protected members, that interface type can only be implemented by that class or a subclass of it.
\nThis is useful when you have a large inheritance hierarchy, but want to specify that your code works with only subclasses that have certain properties.\nThe subclasses don’t have to be related besides inheriting from the base class.\nFor example:
\n\ntsclass Control {\n private state: any;\n}\n\ninterface SelectableControl extends Control {\n select(): void;\n}\n\nclass Button extends Control implements SelectableControl {\n select() {}\n}\n\nclass TextBox extends Control {\n select() {}\n}\n\n// Error: Property 'state' is missing in type 'Image'.\nclass Image implements SelectableControl {\n private state: any;\n select() {}\n}\n\nclass Location {}
In the above example, SelectableControl contains all of the members of Control, including the private state property.\nSince state is a private member it is only possible for descendants of Control to implement SelectableControl.\nThis is because only descendants of Control will have a state private member that originates in the same declaration, which is a requirement for private members to be compatible.
Within the Control class it is possible to access the state private member through an instance of SelectableControl.\nEffectively, a SelectableControl acts like a Control that is known to have a select method.\nThe Button and TextBox classes are subtypes of SelectableControl (because they both inherit from Control and have a select method), but the Image and Location classes are not.