Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Literal and Object Types

TypeScript excess property checks

Reference for TypeScript excess property checks: why object literals are checked strictly, how variables and spreads bypass them, and the correct ways to fix errors.

TypeScript's type system is structural, so a value with extra properties is normally assignable to a type with fewer. There is one exception: when you assign a fresh object literal directly to a target type, the compiler reports any property that the target does not declare. This is the excess property check. It catches typos and stale options (colour instead of color) that would otherwise be silently accepted.

The check applies only to fresh literals. Once the object is stored in a variable, it loses its "freshness" and extra properties are fine.

TypeScript
interface Options { color: string }
const ok: Options = { color: "red" };
// const bad: Options = { color: "red", size: 3 }; // error

Try it

TypeScript Where the check applies

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Fixing the error properly

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Concepts

Freshness

An object literal expression has a fresh type. Assigning it, passing it as an argument, or returning it from a function with a declared return type triggers the check against the target. Once the value passes through a variable or a type assertion, the fresh flag is gone.

What counts as an excess property

A property in the literal with no matching property in the target. If the target is a union, a property is excess only if it is absent from every member (for discriminated unions the discriminant narrows the target first). An index signature on the target accepts any key. If the target is {}, object or has no properties, any literal is accepted.

Why not check everything?

Structural typing relies on being able to pass richer objects to functions that need less. Checking every assignment would break that. The literal check is a pragmatic compromise: if you wrote the property in a literal right there, it is far more likely a mistake.

Usage notes

  • Optional-only targets are "weak types" with an additional rule; see Weak types.
  • Spread ({ ...base, extra: 1 }) still checks the properties you write explicitly, not those that come from the spread.
  • Computed keys of type string are not checked.
  • Generics: when the parameter type is a type parameter, the check does not apply unless the argument also has a contextual constraint.
  • Prefer satisfies over as when you want validation without widening.