{"id":253,"date":"2013-01-24T13:00:00","date_gmt":"2013-01-24T13:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/typescript\/2013\/01\/24\/walkthrough-interfaces\/"},"modified":"2019-02-20T10:46:45","modified_gmt":"2019-02-20T17:46:45","slug":"walkthrough-interfaces","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/typescript\/walkthrough-interfaces\/","title":{"rendered":"Walkthrough: Interfaces"},"content":{"rendered":"

When we talk about a type<\/span> in TypeScript, we mean a collection of things that you can do with a variable (or expression). You might be able to read or write a given property, call a function, use the expression as a constructor, or index into the object. Some objects (like Date<\/span><\/tt>) in JavaScript can do nearly all of those! In TypeScript, interfaces<\/span> are the most flexible way of describing types.<\/p>\n

You’ll see interfaces used to describe existing JavaScript APIs, create shorthand names for commonly-used types, constrain class implementations, describe array types, and more. While they don’t generate any code (and thus have no runtime cost!), they are often the key point of contact between any two pieces of TypeScript code, especially when working with existing JavaScript code or built-in JavaScript objects.<\/p>\n

The only job of an interface in TypeScript is to describe a type<\/span>. While class<\/span><\/tt> and function<\/span><\/tt> deal with implementation, interface<\/span><\/tt> helps us keep our programs error-free by providing information about the shape of the data we work with. Because the type information is erased from a TypeScript program during compilation, we can freely add type data using interfaces without worrying about the runtime overhead.<\/p>\n

While that sounds like a simple, one-purpose task, interfaces role in describing types becomes manifest in a large variety of ways. Let’s look at some of them and how they can be used in TypeScript programs.<\/p>\n

<\/a><\/p>\n

Basics<\/h2>\n

To define an interface in TypeScript, use the interface<\/span><\/tt> keyword:<\/p>\n

interface<\/span> Greetable<\/span> {
    greet(message: string<\/span>): void<\/span>;
}<\/pre>\n
This defines a type, Greetable<\/span><\/tt>, that has a member function called greet<\/span><\/tt> that takes a string argument. You can use this type in all the usual positions; for example in a parameter type annotation. Here we use that type annotation to get type safety on the g<\/span><\/tt> parameter:<\/p>\n
function<\/span> helloEnglish(g: Greetable) {
    g.greet('Hello there!'); \/\/ OK<\/span>
    g.greet(42); \/\/ Not OK -- 42 is not a string<\/span>
    g.greep('Hi'); \/\/ Not OK -- 'greep' is not a member of 'Greetable'<\/span>
}<\/pre>\n
When this code compiles, you won’t see any mention of Greetable<\/span><\/tt> in the JavaScript code. Interfaces are only a compile-time construct and have no effect on the generated code.<\/p>\n
Interfaces: TypeScript’s Swiss Army Knife<\/h2>\n
Interfaces get to play a lot of roles in TypeScript code. We’ll go into more detail on these after a quick overview.<\/p>\n
<\/a><\/p>\n
Describing an Object<\/h4>\n
Many JavaScript functions take a “settings object”. For example, jQuery’s $.ajax<\/span><\/tt> takes an object that can have up to several dozen members that control its behavior, but you’re only likely to pass a few of those in any given instance. TypeScript interfaces allow optional properties to help you use these sorts of objects correctly.<\/p>\n
<\/a><\/p>\n
Describing an Indexable Object<\/h4>\n
JavaScript freely mixes members (foo.x<\/span><\/tt>) with indexers (foo['x']<\/span><\/tt>), but most programmers use one or the other as a semantic hint about what kind of access is taking place. TypeScript interfaces can be used to represent what the expected type of an indexing operation is.<\/p>\n
<\/a><\/p>\n
Ensuring Class Instance Shape<\/h4>\n
Often, you’ll want to make sure that a class you’re writing matches some existing surface area. This is how interfaces are used in more traditional OOP languages like C# and Java, and we’ll see that TypeScript interfaces behave very similarly when used in this role.<\/p>\n
<\/a><\/p>\n
Ensuring the Static Shape of a Class or Constructor Object<\/h4>\n
Interfaces normally describe the shape of an instance<\/span> of a class, but we can also use them to describe the static shape of the class (including its constructor function). We’ll cover this in a later post.<\/p>\n
<\/a><\/p>\n
Describing an Object<\/h2>\n
You can also use interfaces to define the shape of objects that will typically be expressed in an object literal. Here’s an example:<\/p>\n
<\/a><\/p>\n
Describing Simple Types<\/h4>\n
interface<\/span> ButtonSettings<\/span> {
    text: string<\/span>;
    size?: { width: number<\/span>; height: number<\/span>; };
    color?: string<\/span>;
}

function<\/span> createButton(settings: ButtonSettings<\/span>) { ... }<\/pre>\n
Note the use of the ?<\/span><\/tt> symbol after some of the names. This marks a member as being optional<\/span>. This lets callers of createButton<\/span><\/tt> supply only the members they care about, while maintaining the constraint that the required parts of the object are present:<\/p>\n
createButton({ text: 'Submit' }); \/\/ OK<\/span>
createButton({ text: 'Submit', size: { width: 70, height: 30 }}); \/\/ OK<\/span>
createButton({ text: 'Submit', color: 43<\/span>); \/\/ Not OK: 43 isn't a string<\/span>
createButton({ text: 'Submit', size: { width: 70 }<\/span>); \/\/ Not OK: size needs a height as well<\/span>
createButton({ color: 'Blue'}<\/span>); \/\/ Not OK: 'text' member is required<\/span><\/pre>\n
You typically won’t use optional members when defining interfaces that are going to be implemented by classes.<\/p>\n
Here’s another example that shows an interesting feature of types in TypeScript:<\/p>\n
interface<\/span> Point<\/span> {
    x: number<\/span>;
    y: number<\/span>;
}

function<\/span> getQuadrant(pt: Point<\/span>) { ... }

var<\/span> pt = { x: 0, y: -1 };
getQuadrant(pt); \/\/ OK: pt has members x and y of type number<\/span><\/pre>\n
Note that we didn’t annotate pt<\/span><\/tt> in any way to indicate that it’s of type Point<\/span><\/tt>. We don’t need to, because type checking in TypeScript is structural<\/span>: types are considered identical if they have the same surface area. Because pt<\/span><\/tt> has at least the same members as Point<\/span><\/tt>, it’s suitable for use wherever a Point<\/span><\/tt> is expected.<\/p>\n
<\/a><\/p>\n
Describing External Types<\/h4>\n
Interfaces are also used to describe code that is present at runtime, but not implemented in the current TypeScript project. For example, if you open the lib.d.ts<\/span><\/tt> file that all TypeScript projects implicitly reference, you’ll see an interface declaration for Number<\/span><\/tt>:<\/p>\n
interface<\/span> Number<\/span> {
    toString(radix?: number<\/span>): string<\/span>;
    toFixed(fractionDigits?: number<\/span>): string<\/span>;
    toExponential(fractionDigits?: number<\/span>): string<\/span>;
    toPrecision(precision: number<\/span>): string<\/span>;
}<\/pre>\n
Now if we have an expression of type Number<\/span><\/tt>, the compiler knows that it’s valid to call toPrecision<\/span><\/tt> on that expression.<\/p>\n
Extending Existing Types<\/h4>\n
Moreover, interfaces in TypeScript are open<\/span>, meaning you can add your own members to an interface by simply writing another interface<\/span><\/tt> block. If you have an external script that adds members to Date<\/span><\/tt>, for example, you simply need to write interface<\/span> Date<\/span> { \/*...*\/ <\/span>}<\/tt> and declare the additional members.*<\/p>\n
* Note: There are some known issues with the Visual Studio editor that currently prevent this scenario from working as intended. We’ll be fixing this limitation in a later release.<\/span><\/p>\n
<\/a><\/p>\n
Describing an Indexable Object<\/h2>\n
A common pattern in JavaScript is to use an object (e.g. {}<\/span><\/tt>) as way to map from a set of strings to a set of values. When those values are of the same type, you can use an interface to describe that indexing into an object always produces values of a certain type (in this case, Widget<\/span><\/tt>).<\/p>\n
interface<\/span> WidgetMap<\/span> {
    [name: string<\/span>]: Widget;
}

var<\/span> map: WidgetMap<\/span> = {};
map['gear'] = new<\/span> GearWidget<\/span>();
var<\/span> w = map['gear']; \/\/ w is inferred to type Widget<\/span><\/pre>\n
Ensuring Class Instance Shape<\/h2>\n
Let’s extend the Greetable<\/span><\/tt> example above:<\/p>\n
\/** Represents an object that can be greeted *\/<\/span>
interface<\/span> Greetable<\/span> {
    \/** Used to welcome someone *\/<\/span>
    greet(message: string<\/span>): void<\/span>;

    \/** The preferred language of this object *\/<\/span>
    language: string<\/span>;
}<\/pre>\n
We can implement this interface in a class using the implements<\/span><\/tt> keyword:<\/p>\n
class<\/span> Person<\/span> implements<\/span> Greetable<\/span> {
    language = 'English';

    greet(message: string<\/span>) {
        console.log(message);
    }
}<\/pre>\n
Now we can use an instance of Person<\/span><\/tt> wherever a Greetable<\/span><\/tt> is expected:<\/p>\n
var<\/span> g: Greetable = new<\/span> Person<\/span>();<\/tt><\/p>\n
Similarly, we can take advantage of the structural typing of TypeScript to implement Greetable<\/span><\/tt> in an object literal:<\/p>\n
var<\/span> greeter = {
    greet: (message: string<\/span>) => { console.log(message) };
    language: 'Any';
};<\/pre>\n","protected":false},"excerpt":{"rendered":"
When we talk about a type in TypeScript, we mean a collection of things that you can do with a variable (or expression). You might be able to read or write a given property, call a function, use the expression as a constructor, or index into the object. Some objects (like Date) in JavaScript can […]<\/p>\n","protected":false},"author":376,"featured_media":1797,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[8],"class_list":["post-253","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-typescript","tag-walkthrough-interfaces"],"acf":[],"blog_post_summary":"
When we talk about a type in TypeScript, we mean a collection of things that you can do with a variable (or expression). You might be able to read or write a given property, call a function, use the expression as a constructor, or index into the object. Some objects (like Date) in JavaScript can […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts\/253","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/users\/376"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/comments?post=253"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts\/253\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/media\/1797"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/media?parent=253"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/categories?post=253"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/tags?post=253"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
<\/a><\/p>\n
<\/a><\/p>\n
<\/a><\/p>\n