7.1 Interface Declarations

An interface declaration declares an interface type.

  InterfaceDeclaration:   interface BindingIdentifier TypeParameters_opt InterfaceExtendsClause_opt ObjectType

  InterfaceExtendsClause:   extends ClassOrInterfaceTypeList

  ClassOrInterfaceTypeList:   ClassOrInterfaceType   ClassOrInterfaceTypeList , ClassOrInterfaceType

  ClassOrInterfaceType:   TypeReference

An InterfaceDeclaration introduces a named type (section 3.7) in the containing declaration space. The BindingIdentifier of an interface declaration may not be one of the predefined type names (section 3.8.1).

An interface may optionally have type parameters (section 3.6.1) that serve as placeholders for actual types to be provided when the interface is referenced in type references. An interface with type parameters is called a generic interface. The type parameters of a generic interface declaration are in scope in the entire declaration and may be referenced in the InterfaceExtendsClause and ObjectType body.

An interface can inherit from zero or more base types which are specified in the InterfaceExtendsClause. The base types must be type references to class or interface types.

An interface has the members specified in the ObjectType of its declaration and furthermore inherits all base type members that aren’t hidden by declarations in the interface:

• A property declaration hides a public base type property with the same name.
• A string index signature declaration hides a base type string index signature.
• A numeric index signature declaration hides a base type numeric index signature.

The following constraints must be satisfied by an interface declaration or otherwise a compile-time error occurs:

• An interface declaration may not, directly or indirectly, specify a base type that originates in the same declaration. In other words an interface cannot, directly or indirectly, be a base type of itself, regardless of type arguments.
• An interface cannot declare a property with the same name as an inherited private or protected property.
• Inherited properties with the same name must be identical (section 3.11.2).
• All properties of the interface must satisfy the constraints implied by the index signatures of the interface as specified in section 3.9.4.
• The this-type (section 3.6.3) of the declared interface must be assignable (section 3.11.4) to each of the base type references.

An interface is permitted to inherit identical members from multiple base types and will in that case only contain one occurrence of each particular member.

Below is an example of two interfaces that contain properties with the same name but different types:

interface Mover {  
    move(): void;  
    getStatus(): { speed: number; };  
}
interface Shaker {  
    shake(): void;  
    getStatus(): { frequency: number; };  
}

An interface that extends ‘Mover’ and ‘Shaker’ must declare a new ‘getStatus’ property as it would otherwise inherit two ‘getStatus’ properties with different types. The new ‘getStatus’ property must be declared such that the resulting ‘MoverShaker’ is a subtype of both ‘Mover’ and ‘Shaker’:

interface MoverShaker extends Mover, Shaker {  
    getStatus(): { speed: number; frequency: number; };  
}

Since function and constructor types are just object types containing call and construct signatures, interfaces can be used to declare named function and constructor types. For example:

interface StringComparer { (a: string, b: string): number; }

This declares type ‘StringComparer’ to be a function type taking two strings and returning a number.