TypeScript 6.0 `--noPropertyAccessFromIndexSignature`: The Flag That Forces Honest API Contracts

TypeScript 6.0 introduces a new flag called --noPropertyAccessFromIndexSignature, designed to enforce honest API contracts. This feature addresses a common runtime error in JavaScript and TypeScript codebases: accessing properties defined only through index signatures using dot notation.

When the --noPropertyAccessFromIndexSignature flag is enabled, TypeScript prevents developers from using dot notation to access properties that are only available through index signatures. Instead, developers must use bracket notation, which explicitly signals the uncertainty of the property's existence. This change transforms implicit runtime failures into compile-time errors, providing developers with immediate feedback during development.

Index signatures ( [key: string]: T ) are used to describe objects with an unknown set of properties, while explicit properties (e.g., theme: "light" | "dark") indicate that certain properties are guaranteed to exist. The flag forces a clear semantic distinction between these two types of properties, ensuring that the codebase accurately reflects the intended contract.

For example, consider an interface UserPreferences with an explicit property theme and an index signature for additional properties:

interface UserPreferences {

theme: "light" | "dark";

[key: string]: string;

}

When --noPropertyAccessFromIndexSignature is enabled, accessing the theme property with dot notation (prefs.theme) is allowed, but accessing the fontSize property (prefs.fontSize) results in an error because it's defined only through the index signature. The compiler requires bracket notation (prefs[fontSize]) to make the uncertainty explicit.

This flag integrates seamlessly with TypeScript's structural type system. When an object literal satisfies an interface with both explicit properties and index signatures, the compiler keeps track of which properties come from explicit definitions versus inferred index entries. This information persists through type narrowing and control flow analysis.

To summarize, the --noPropertyAccessFromIndexSignature flag in TypeScript 6.0 forces a clear distinction between properties that are guaranteed to exist and those that are only defined through index signatures. By enforcing bracket notation for the latter, the flag eliminates false confidence in the presence of properties and promotes honest API contracts. This results in more robust code, earlier detection of potential issues, and a cleaner, more honest codebase.