When Excess Property Checks Trigger
You'll learn: The specific situations where TypeScript performs strict excess property checking and when it quietly allows extra properties.
The Core Rule
TypeScript's excess property checks don't happen everywhere—they activate in specific scenarios where you're creating a fresh object literal directly in a type-checked context.
Think of it like airport security: you get thoroughly checked when entering directly through the gate, but if someone hands you their already-screened bag inside the terminal, nobody rechecks it.
Checks DO Trigger
Excess property checks activate when you:
- Assign an object literal directly to a typed variable:
type User = { name: string };
const user: User = { name: "Alice", age: 30 }; // ❌ Error: 'age' does not exist
- Pass an object literal directly to a function:
function greet(user: User) {}
greet({ name: "Bob", age: 25 }); // ❌ Error: 'age' does not exist
- Return an object literal from a typed function:
function getUser(): User {
return { name: "Carol", age: 40 }; // ❌ Error: 'age' does not exist
}
Checks DON'T Trigger
The check is bypassed when using an intermediate variable:
const temp = { name: "Dave", age: 35 }; // No error yet
const user: User = temp; // ✅ No error - already an object reference
The object isn't "fresh" anymore—it's a reference to something created elsewhere, so TypeScript uses regular structural typing.
Key Takeaway: Excess property checks only trigger when assigning, passing, or returning fresh object literals directly in a typed context. Using an intermediate variable bypasses this stricter check.