Excess property checking behavior in Typescript

Introduction

Excess property checking helps catch mistakes when you add extra properties that are not expected. It keeps your code safe and clear.

When you create an object to match a specific shape or type.

When you want to avoid typos in property names.

When you want to make sure you only pass allowed properties to functions.

When you want TypeScript to warn you about extra, unexpected properties.

When you want to keep your data structures clean and predictable.

Syntax

Typescript

interface TypeName {
  property1: Type1;
  property2: Type2;
}

const obj: TypeName = {
  property1: value1,
  property2: value2
  // extraProperty: value3, // This will cause an error
};

Excess property checking happens when you assign an object literal directly to a variable or pass it as an argument.

It only checks for extra properties in object literals, not in variables or expressions.

Examples

This example shows an error because 'location' is not part of the Person interface.

Typescript

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

const person: Person = {
  name: "Alice",
  age: 30,
  location: "Wonderland" // Error: 'location' does not exist in type 'Person'
};

Here, no error occurs because excess property checking only applies to object literals, not variables.

Typescript

interface Car {
  make: string;
  model: string;
}

const carDetails = {
  make: "Toyota",
  model: "Corolla",
  year: 2020
};

const car: Car = carDetails; // No error here because carDetails is a variable, not an object literal

Passing an object literal with an extra property to a function causes an error.

Typescript

interface Book {
  title: string;
  author: string;
}

function printBook(book: Book) {
  console.log(`${book.title} by ${book.author}`);
}

printBook({
  title: "1984",
  author: "George Orwell",
  pages: 328 // Error: 'pages' does not exist in type 'Book'
});

Sample Program

This program shows how excess property checking works. The commented-out code shows an error when an extra property is added directly in an object literal. But when the extra property is in a variable, TypeScript allows it.

Typescript

interface User {
  username: string;
  email: string;
}

// Correct object literal
const user1: User = {
  username: "john_doe",
  email: "[e-mail]"
};

// Object literal with extra property - causes error
// const user2: User = {
//   username: "jane_doe",
//   email: "[e-mail]",
//   age: 25 // Error: 'age' does not exist in type 'User'
// };

// Using a variable with extra property - no error
const extraInfo = {
  username: "mike",
  email: "[e-mail]",
  age: 40
};

const user3: User = extraInfo;

console.log(user1);
console.log(user3);

Important Notes

Excess property checking helps catch simple mistakes like typos in property names.

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

Remember, excess property checking only applies to object literals assigned directly or passed as arguments.

Summary

Excess property checking warns you about extra properties in object literals.

It helps prevent bugs by catching unexpected properties early.

It only applies to object literals, not variables or expressions.