Course contentsShow
← TypeScript
Lesson 329 of 1,7967. ObjectsFree lesson

Common Gotchas with Options Objects

Recognizing typical scenarios where excess property checks help or hinder in configuration objects.

Common Gotchas with Options Objects

You'll learn to recognize when excess property checks help you catch bugs versus when they get in your way with configuration objects.

The Helper That Sometimes Hurts

Excess property checks are TypeScript's way of protecting you from typos in object literals. But with configuration objects — one of the most common patterns in JavaScript — this safety feature can create surprising friction.

Think of it like a helpful assistant who double-checks your restaurant order. Usually great! But sometimes you want to add a special request, and they keep saying "that's not on the menu."

The Classic Configuration Gotcha

interface Options {
  timeout?: number;
  retries?: number;
}

function connect(opts: Options) {
  // ...
}

// ❌ Error: 'retires' is not in Options (typo!)
connect({ timeout: 1000, retires: 3 });

This is helpful — you misspelled retries! The check catches your mistake.

But now this:

// ❌ Error: 'debug' does not exist in Options
connect({ timeout: 1000, retries: 3, debug: true });

This is frustrating — maybe you're passing through options to an underlying library that does use debug. The excess check blocks you even though it's intentional.

The Stale Interface Trap

Your gotcha moment often happens when:

  1. A library updates and adds new options
  2. Your Options interface hasn't been updated yet
  3. You try to use the new option directly in a literal
  4. TypeScript says "no!" even though it would work at runtime

This is why many libraries use index signatures or accept Record<string, any> for their config objects — trading type safety for flexibility.

Key Takeaway: Excess property checks shine at catching typos in configuration objects, but can frustrate you when passing through or using newer properties that aren't yet in your type definition. Understanding when the check triggers helps you choose the right workaround.