Codectionary / Developer documentation / TypeScript

Excess Property Checks

Fresh object literals receive an additional check for unexpected fields when assigned to a known object type.

What it is and why to use it

Fresh object literals receive an additional check for unexpected fields when assigned to a known object type. This often catches spelling mistakes in an options object. It does not make that type an exact closed runtime shape for every possible assignment.

Common mistakes and limitations

Do not rely on excess-property checking to remove unknown fields or secure an API. Avoid assertions solely to bypass a useful typo error. Use explicit validation and field selection when an external object must have an exact accepted shape.

Run this example

Use TypeScript 5.8 or later with strict checking and an ES2022 target. Save each complete example independently as example.ts, compile it, then run the generated JavaScript with a compatible Node.js installation. Compiler-only options below affect checking; they do not add runtime validation.

Terminal — compile and run

npx tsc example.ts --strict --target ES2022 --module commonjs
node example.js

Syntax

const options: Options = { title: "Guide" };

Examples

Excess Property Checks

Standalone TypeScript 5.8+ example; expected output is explained below.

type Options = { title: string };
const existing = { title: "Guide", debug: true };
const options: Options = existing;
console.log(options.title);
console.log("debug" in options);
  1. existing is first inferred with both title and debug.
  2. It can then be assigned structurally to Options because title is compatible.
  3. The debug property still exists at runtime. Writing a fresh Options literal with an unexpected debug field would instead trigger the excess-property check.
  4. Expected output: Guide true

Best practices

  • Do not rely on excess-property checking to remove unknown fields or secure an API. Avoid assertions solely to bypass a useful typo error. Use explicit validation and field selection when an external object must have an exact accepted shape.
  • Keep external-input validation separate from compile-time type descriptions.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

TypeScript Handbook

Specifications & further reading