Interfaces & Types

An interface describes the shape of an object — the names and types of its properties and methods — as a compile-time contract. It supports optional members (?), readonly members, method and call signatures, and index signatures. A class can implements an interface, and object literals are checked against it. Interfaces are erased at compile time, so they add no runtime cost.

Both can describe object shapes and are largely interchangeable there. The differences: interface supports declaration merging and is the convention for object and class contracts and public APIs; a type alias can also express unions, intersections, tuples, mapped and conditional types, and alias primitives — none of which interface can. Rule of thumb: reach for interface for extendable object and class shapes, and type for unions and computed types.

Excess property checking is an extra rule for fresh object literals: one assigned or passed directly is rejected if it has a member the target type does not declare. Structural typing alone would accept it; the rule catches typos like widht.

TypeScript compares types by shape, not by name. A value fits Point as soon as it has the members Point requires: no implements, no import, no declared relationship. In a nominal language like Java the name must match and the code is rejected.

TypeScript uses structural ("duck") typing — compatibility is decided by an object's shape, not by its declared name. An object is assignable to a type if it has the required members, even if it never explicitly declares that interface, and two unrelated types with the same members are compatible. Fresh object literals additionally get an excess-property check. This contrasts with nominal typing in Java or C#, where the declared name must match.

The literal loses its freshness once bound to a variable, and only fresh literals get the excess-property check. Plain structural typing is left: it asks only whether the required members are there. The value is assignable, and the typo lives on.

Every declared property must fit the signature's value type, so { [k: string]: number; name: string } is an error. The key must be string, number, symbol or a template literal. A read is unchecked: obj.missing is number, not undefined.

Use extends when you own the type: it is explicit and the new name says what it is. Merging is for the case you cannot rename — adding a member to a type you do not own, like Express.Request or Window. Existing references see the addition.

Both describe an object whose values share a type V, but they constrain keys differently. An index signature { [k: string]: V } allows any key of that primitive kind. Record<K, V> is a mapped type over a known key set K, which may be a finite union of string literals like Record<'a' | 'b', V> — then exactly those keys must exist. So Record can enforce a fixed key set; an index signature stays open-ended.

Declaring the same interface name more than once merges the declarations into one interface whose members are combined. This is used to augment existing types — for example adding properties to Window, or extending a library's types via module augmentation. Only interfaces and namespaces merge this way; a duplicate type alias of the same name is an error. Members with the same name but incompatible types across the declarations are also an error.

An interface is an open name for a shape, so a second declaration can add members. An alias is a closed binding to a computed type — a union, a conditional — with no shape to add to. A second alias of the same name is a duplicate identifier.

A shallow, freshness-scoped approximation: a literal written at the assignment site is checked, nothing else is. A value arriving via a variable, a return or a spread carries its extras through, since structural typing asks only for required members.

The namespace's exported members become static members of the value: function f() {} plus namespace f { export const v = 1 } gives f.v. The two occupy different declaration spaces, so the compiler attaches rather than clashes.