Excess Property Checks

The plain-language idea

Structural typing, covered elsewhere in this track, says a value is assignable to a type as long as it has at least the required shape — extra properties are normally completely fine. That's what makes structural typing useful: you can pass a bigger, more detailed object anywhere a smaller shape is expected.

Except when you pass a fresh object literal directly. Then TypeScript runs a stricter check called an excess property check: any property on that literal that isn't part of the target type is flagged as an error, even though the general structural-typing rule would otherwise allow it. The check exists specifically to catch typos and mistakes — a fresh literal has no other purpose than being that one argument, so an unrecognized property on it is almost certainly a mistake, not a deliberate extra field.

See it in a real thing: the same shape, checked two different ways

interface Config {
  mode: "dark" | "light";
}

function apply(cfg: Config) { /* ... */ }

apply({ mode: "dark", retries: 3 });
// ❌ Object literal may only specify known properties, and
//    'retries' does not exist in type 'Config'

const draft = { mode: "dark" as const, retries: 3 };
apply(draft);
// ✅ no error — draft is structurally compatible (it has `mode`);
//    the extra `retries` is allowed once it's not a fresh literal

Both calls pass an object with the exact same shape. The literal, passed directly, gets the tighter freshness check and is rejected. The identical shape, stored in draft first, is checked under the ordinary structural-typing rule and passes — draft has everything Config requires, and extra properties on a non-literal value are simply not a problem.

What people usually miss

Watch out

• Excess property checks only apply to fresh object literals. The moment the object is stored in a variable, held in an array, spread, or returned from a function, the freshness check no longer applies — only the object's own declared or inferred type matters from then on.
• This is a deliberate carve-out from structural typing, not a contradiction of it. The general "extra properties are fine" rule still holds everywhere else; freshness-checking exists narrowly because a literal has no other explanation for its shape, making an unexpected property overwhelmingly likely to be a typo'd key name.
• Spreading defeats the check, even though the result still looks like a literal: apply({ ...draft, mode: "dark" }) is not treated as "fresh" the same way a plain literal is, so it bypasses excess property checking even though it's still written inline at the call site.
• Reaching for an intermediate variable or satisfies isn't a workaround or a hack. It's often the genuinely correct choice when you deliberately want a value checked structurally rather than by freshness — the two checks exist for different purposes, and picking the right one is a real design decision, not a way to silence an error.

Why this matters in interviews

This is a concrete, specific carve-out from the structural typing covered elsewhere in this track — being able to explain why the same shape is checked two different ways (rather than just knowing "assign it to a variable first to fix the error") is what separates having memorized a workaround from actually understanding what TypeScript is protecting against.