Structural typing and excess property checks
TypeScript compares types by shape, not by name. Why that fits JavaScript, and the one place it gets stricter: extra properties on fresh object literals.
Object types, optional and readonly propertiesType aliases vs interfaces
Structural typing and excess property checks
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- TypeScript's type system is structural: a value is assignable to a type when it has the required members with compatible types, whatever its type is called or where it came from.
- An object type describes a minimum, so a value with extra properties still fits; `{ x: number }` means "has at least a numeric `x`", not "has exactly `x`".
- Classes are compared structurally too, except that `private` and `protected` members only match members from the same declaration.
- Excess property checking is an extra rule for fresh object literals only: an object literal written directly where a type is expected may not contain properties that type doesn't declare.
- Once the literal is stored in a variable it loses its freshness and the extra-property rule no longer applies, though an all-optional target still requires at least one shared property.
- Against a union, a literal's property counts as excess only if no member declares it, unless the union is discriminated, in which case the literal is checked against the member its tag selects.
Two ways a type checker can decide “is this the right kind of thing?”
Languages like Java and C# use nominal typing. A value is a Point only if it was created from something declared as a Point, or something that explicitly says it extends or implements Point. Two classes with identical fields are still different types, because they have different names.
That rule would fight JavaScript at every turn. JavaScript code passes around object literals, JSON from the network, and objects built by spreading other objects. None of those have a declared lineage. The JavaScript habit is duck typing: if it has the fields you need, use it. TypeScript was designed to type existing JavaScript, so it took the same approach and made it static. This is structural typing: a value fits a type when its shape fits, regardless of names.
Compatibility by shape
interface Point {
x: number;
y: number;
}
function length(p: Point) {
return Math.hypot(p.x, p.y);
}
const p3 = { x: 1, y: 2, z: 3 };
length(p3); // fine
p3 was never declared as a Point, and it has an extra z. Neither matters. length needs an x and a y, both numbers, and p3 has them. Think of an object type as a job posting’s minimum requirements: a candidate with extra skills still qualifies.
Classes follow the same rule:
class Meters {
constructor(public value: number) {}
}
class Seconds {
constructor(public value: number) {}
}
const m: Meters = new Seconds(5); // fine: same shape
That can be surprising, and sometimes it’s a real bug. The exception is private and protected members. Those are only compatible with members from the same declaration, so adding one to each class makes them distinct. When you genuinely want nominal-style distinctions, such as a UserId that isn’t interchangeable with any other string, the branded types lesson shows how.
Excess property checks: the one stricter spot
If extra properties are always fine, this should compile:
interface Options {
color?: string;
width?: number;
}
function draw(o: Options) {}
draw({ colour: "red" });
// Error: Object literal may only specify known properties, but 'colour'
// does not exist in type 'Options'. Did you mean to write 'color'?
It doesn’t, and you’re glad. colour is a typo, and without this check draw would silently get no color at all.
The rule is called excess property checking, and it applies only to fresh object literals: an object literal written directly at the place where a type is expected. That covers annotated variable declarations, function arguments, return statements, and property values inside another literal. The reasoning is that a literal written in place has no other users. Nothing else could need its extra property, so an unknown key is almost certainly a mistake.
Freshness doesn’t survive assignment:
const opts = { colour: "red", width: 2 };
draw(opts); // fine: opts is not a fresh literal
Now the object might be used elsewhere with its extra property, so TypeScript falls back to ordinary structural checking. width matches and colour is just an extra.
Weak types
There’s one more rule that catches a case freshness misses. A type whose properties are all optional, like Options, is called a weak type. Structurally, almost anything fits it. So TypeScript adds a requirement: a value assigned to a weak type must share at least one property with it, even when it’s not fresh.
const opts2 = { colour: "red" };
draw(opts2);
// Error: Type '{ colour: string; }' has no properties in common with type 'Options'.
Unions
When the target is a union, a property is excess only if no member of the union declares it:
type Loose = { a: number } | { b: string };
const ok: Loose = { a: 1, b: "x" }; // fine: both keys are known somewhere
const bad: Loose = { a: 1, c: 2 };
// Error: Object literal may only specify known properties, and 'c' does not exist in type 'Loose'.
A discriminated union is checked more precisely. The literal’s tag picks a member, and extra keys are judged against that member alone:
type Shape =
| { kind: "circle"; radius: number }
| { kind: "square"; side: number };
const s: Shape = { kind: "circle", radius: 1, side: 2 };
// Error: Object literal may only specify known properties, and 'side'
// does not exist in type '{ kind: "circle"; radius: number; }'.
Allowing extras on purpose
Sometimes extra keys are legitimate. The cleanest fix is to say so in the type, either with a declared optional property or an index signature. Passing a variable instead of a literal works, at the cost of losing typo protection for that object. A type assertion, { colour: "red" } as Options, also silences the error, but it silences everything else wrong with the literal too. When you want a literal checked against a type without widening the variable to that type, satisfies is the better tool. It’s covered in type assertions, non-null, and satisfies.
About the video
Schalk Neethling’s eight-minute video, from 2025, zooms in on the part of this lesson that surprises people most: why an object literal with an extra property is rejected when the same object in a variable is accepted. It’s a focused look at excess property checks, so the structural-typing foundation above, compatibility by shape, the class example, and the weak-type rule, is carried by this text. For the bigger picture, Drew Colthorp’s Strange Loop talk in the links makes structural typing its central idea and uses it to tour the rest of the type system. It dates from 2018, so treat its compiler details as older, though the ideas still hold.
Check yourself
Two unrelated classes `Meters` and `Seconds` each have only `constructor(public value: number)`. Why does `const m: Meters = new Seconds(5)` compile, and what would stop it?
Both classes have the same public shape, a single numeric `value`, and TypeScript only compares shapes. Giving them a `private` member stops it, because private members are only compatible with the same declaration. The branded types lesson shows a lighter way to get name-like distinctions.
`draw({ colour: "red" })` errors, but `const o = { colour: "red", width: 2 }; draw(o)` compiles, when `draw` takes `{ color?: string; width?: number }`. Why the difference?
The first argument is a fresh object literal, so excess property checking applies and flags `colour` as unknown. In the second call `o` is a variable, so its literal is no longer fresh; it's checked only structurally, and since it shares `width` with the target it's accepted.
Why does `const o2 = { colour: "red" }; draw(o2)` still fail, even though `o2` is not a fresh literal?
The parameter type has only optional properties, which makes it a weak type. TypeScript requires a value assigned to a weak type to share at least one property with it, and `o2` shares none, so it reports that the types have no properties in common.
What problem is excess property checking designed to catch, given that extra properties are normally harmless?
Typos and stale option names in object literals. When you write the literal directly at the point of use, there's nobody else who could need the extra property, so an unknown key is almost certainly a mistake, like `colour` for `color`, that would otherwise be silently ignored.
Name two ways to pass a literal with an extra property on purpose, and the trade-off of each?
Add an index signature or a declared optional property to the target type, which documents that extra keys are expected. Or build the object first in a variable and pass that, which keeps the target strict but means typos in that literal go unchecked. A type assertion with `as` also silences the error, but it silences other mistakes too.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.