Interfaces & Type Aliases

An interface describes the shape of an object — the property names and their types — without saying anything about where the object came from. TypeScript uses structural typing (sometimes called duck typing): any object with the right properties satisfies the interface, whether or not it was ever declared with that interface in mind. This is different from languages like Java or C#, where a class has to explicitly say it implements an interface.

interface User {
  name: string
  age: number
}

const bad: User = { name: "Ada" }

app.ts:6:7 - error TS2741: Property 'age' is missing in type '{ name: string; }' but required in type 'User'.

6 const bad: User = { name: "Ada" }
        ~~~

const bad: User = { name: "Ada", age: 36 }

Structural typing

A type system that checks compatibility by comparing shape (property names and types) rather than by name or explicit declaration.

Duck typing

"If it walks like a duck and quacks like a duck…" — the informal name for structural typing: an object qualifies by having the right members, not by declaring an identity.

Both interface and type can describe an object shape, and for plain object shapes they are nearly interchangeable. The differences that decide which one to reach for: an interface can be reopened and extended — declared again with more members, which get merged — and it uses extends for inheritance; a type alias can represent things an interface cannot, like a union ("a" | "b"), a tuple, or a mapped type, but once declared it is final — you cannot declare the same type name twice.

An interface can extend one or more other interfaces, inheriting all of their members and adding its own. The extending interface must be compatible with everything it extends — if it redeclares an inherited property, the new type has to be assignable to the original, not just any type.

Marking a property readonly means it can be set when the object is first created, but never reassigned afterward. It is a compile-time-only guarantee — JavaScript objects have no real immutability, so readonly is the type checker refusing to compile an assignment, not a runtime lock. It is also shallow: a readonly property that holds an object does not make that nested object's own properties readonly.

A property marked with ? may be omitted entirely when constructing an object of that type. Reading it back gives a type unioned with undefined — timeout?: number means options.timeout has type number | undefined — so you generally need a fallback, most often with the ?? operator, before using it as a plain number.

interface Options {
  label?: string
}
function shout(options: Options) {
  console.log(options.label.toUpperCase())
}

app.ts:5:23 - error TS2532: Object is possibly 'undefined'.

5   console.log(options.label.toUpperCase())
                        ~~~~~

function shout(options: Options) {
  console.log((options.label ?? "").toUpperCase())
}

Optional property

A property that may be omitted from an object of that type, declared with a trailing ?. Its type when read is unioned with undefined.

An index signature types an object whose exact keys are not known ahead of time, but whose values all share one type — a dictionary. [player: string]: number means: whatever string key someone uses, the value at that key is a number. The name inside the brackets (player) is just documentation; only the key type (string) and value type (number) are checked.

Structural typing normally only checks that an object has at least the required properties — extra ones are fine, because anything with the right shape is compatible. But when you pass a fresh object literal directly where a typed value is expected, TypeScript runs a stricter check on top: it also flags any property the literal has that the target type does not. This is an excess property check, and it exists specifically to catch typos — a misspelled optional property would otherwise silently vanish with no warning at all.