Excess property checks vs structural compatibility in Typescript

Introduction

We want to make sure objects have the right properties without mistakes. Excess property checks help catch extra wrong properties, while structural compatibility lets objects work if they have the needed parts.

When creating objects that must match a specific shape exactly.

When passing objects to functions expecting certain properties.

When assigning one object to another with similar but not identical properties.

When you want TypeScript to warn about typos in object properties.

When you want flexibility to use objects with extra properties without errors.

Syntax

Typescript

interface Person {
  name: string;
  age: number;
}

const p: Person = { name: "Alice", age: 30, location: "NY" };

Excess property checks happen when you assign an object literal directly to a variable or parameter expecting a specific type.

Structural compatibility means TypeScript checks if an object has at least the required properties, ignoring extra ones when not assigned directly.

Examples

This causes an error because location is not in Person.

Typescript

interface Person {
  name: string;
  age: number;
}

// Excess property check error
const p1: Person = { name: "Bob", age: 25, location: "LA" };

Assigning a variable with extra properties to Person works because of structural compatibility.

Typescript

interface Person {
  name: string;
  age: number;
}

const extra = { name: "Bob", age: 25, location: "LA" };
const p2: Person = extra; // No error here

Passing an object literal with extra property hobby causes an error.

Typescript

function greet(person: Person) {
  console.log(`Hello, ${person.name}`);
}

greet({ name: "Eve", age: 28, hobby: "reading" }); // Error: excess property 'hobby'

Passing a variable with extra properties works fine due to structural compatibility.

Typescript

const obj = { name: "Eve", age: 28, hobby: "reading" };
greet(obj); // No error because obj is a variable

Sample Program

This program shows how excess property checks cause an error when assigning an object literal with extra properties directly. But assigning a variable with extra properties to the expected type works fine.

Typescript

interface Car {
  make: string;
  year: number;
}

// Direct object literal with extra property - error
// const car1: Car = { make: "Toyota", year: 2020, color: "red" };

// Using a variable with extra property - no error
const carDetails = { make: "Toyota", year: 2020, color: "red" };
const car2: Car = carDetails;

console.log(car2.make);
console.log(car2.year);

Important Notes

Excess property checks only happen on fresh object literals assigned directly.

Structural compatibility allows objects with extra properties to be assigned if they come from variables.

You can use type assertions or index signatures to bypass excess property checks if needed.

Summary

Excess property checks catch extra properties in direct object literals to prevent mistakes.

Structural compatibility allows objects with extra properties to be used if assigned from variables.

This helps balance safety and flexibility in TypeScript object typing.