index-signature-alternatives

Index signatures are imprecise. Use interfaces, Records, or Maps instead.

Index signatures ({[key: string]: T}) allow any string key, don't require specific keys, and can't have different types for different keys. There are almost always better alternatives.

• Defining types with known property names
• Modeling data from APIs or configuration files
• Working with CSV or dynamic data
• Choosing between object types and Maps

```

If you know the property names, DON'T use an index signature.

Use an interface, Record, or mapped type instead.

```

Remember:

• Index signatures allow any key (including typos)
• Index signatures don't require any specific keys
• Index signatures can't have distinct types per key
• Language services (autocomplete) don't work well with index signatures

```typescript

// Index signature: too permissive

type Rocket = { [property: string]: string };

const rocket: Rocket = {

name: 'Falcon 9',

variant: 'Block 5',

thrust: '7,607 kN',

};

// Problems:

rocket.Name; // Typo compiles (should be 'name')

const r: Rocket = {}; // Empty object is valid

rocket.thrust; // Can't be a number, even though it should be

```

1. Interface (Best for Known Properties)

```typescript

interface Rocket {

name: string;

variant: string;

thrust_kN: number; // Can have different types

}

const falconHeavy: Rocket = {

name: 'Falcon Heavy',

variant: 'v1',

thrust_kN: 15200,

};

// Benefits:

// - Typos caught: rocket.Name is an error

// - Required fields enforced

// - Each field has its own type

// - Autocomplete works

```

2. Record (For Union of Known Keys)

```typescript

// Limited set of keys, same value type

type Vec3D = Record<'x' | 'y' | 'z', number>;

// Same as: { x: number; y: number; z: number }

type CSSColors = Record<'primary' | 'secondary' | 'accent', string>;

```

3. Optional Properties (For Partial Sets)

```typescript

// When you know possible keys but not all will be present

interface Row {

a: number;

b?: number;

c?: number;

d?: number;

}

```

4. Union Types (For Precise Combinations)

```typescript

// When specific combinations are valid

type Row =

| { a: number }

| { a: number; b: number }

| { a: number; b: number; c: number };

```

5. Map (For Truly Dynamic Keys)

```typescript

// When keys are genuinely unknown at compile time

function parseCSV(input: string): Map[] {

const lines = input.split('\n');

const [headerLine, ...rows] = lines;

const headers = headerLine.split(',');

return rows.map(rowStr => {

const row = new Map();

rowStr.split(',').forEach((cell, i) => {

row.set(headers[i], cell);

});

return row;

});

}

const rockets = parseCSV(csvData);

const thrust = rockets[0].get('thrust_kN');

// ^? const thrust: string | undefined (safer!)

```

Allowing Additional Properties

```typescript

interface ButtonProps {

title: string;

onClick: () => void;

[otherProps: string]: unknown; // Allow any extra props

}

renderButton({

title: 'Click me',

onClick: () => {},

theme: 'dark', // OK now

'data-testid': 'submit-btn', // OK

});

```

Template Literal Constraints

```typescript

// Only allow keys starting with 'data-'

interface DataProps {

[key: data-${string}]: string;

}

const props: DataProps = {

'data-testid': 'my-button',

'data-value': '42',

// 'theme': 'dark', // Error! Key must start with 'data-'

};

```

| Feature | Map | Index Signature |

|---------|-----|-----------------|

| .get() returns | T \| undefined | T (unsafe) |

| Prototype issues | No | Yes |

| Iteration order | Guaranteed | Not guaranteed |

| Any key type | Yes | String/number/symbol only |

| TypeScript support | Good | Better autocomplete |

```typescript

// Map is safer for dynamic data

const scores = new Map();

const score = scores.get('alice');

// ^? const score: number | undefined

// Index signature pretends value always exists

const scoreObj: { [name: string]: number } = {};

const score2 = scoreObj['alice'];

// ^? const score2: number (but it's actually undefined!)

```

```typescript

// Parse dynamic data, validate, return typed object

function parseRocket(map: Map): Rocket {

const name = map.get('name');

const variant = map.get('variant');

const thrust_kN = Number(map.get('thrust_kN'));

if (!name || !variant || isNaN(thrust_kN)) {

throw new Error(Invalid rocket: ${JSON.stringify([...map])});

}

return { name, variant, thrust_kN };

}

// Now you have type safety

const rockets = parseCSV(csvData).map(parseRocket);

// ^? const rockets: Rocket[]

```

1. "I Don't Know All the Keys"

Pressure: "The keys come from user input/API"

Response: Use Map for truly dynamic data, then validate into a typed interface.

Action: Map for input, then parse to interface.

2. "Index Signatures Are Simpler"

Pressure: "Just use {[k: string]: any} and move on"

Response: You lose all type safety and autocomplete.

Action: Define the actual structure, even if it takes more code.

• Index signature with known property names
• [key: string]: any anywhere
• Missing autocomplete when typing property names
• Typos in property names not caught by TypeScript

| Excuse | Reality |

|--------|---------|

| "Keys are dynamic" | Often they're actually known at compile time |

| "Too many properties to list" | Record or mapped types handle this |

| "It's just config" | Config has a schema; define it |

```typescript

// DON'T: Index signature for known keys

type Bad = { [key: string]: string };

// DO: Interface for known keys

interface Good { name: string; value: string; }

// DO: Record for union of keys

type Colors = Record<'red' | 'green' | 'blue', number>;

// DO: Map for truly dynamic keys

const data = new Map();

// DO: Index signature only for extra properties

interface Props {

required: string;

[extra: string]: unknown;

}

```

Index signatures sacrifice precision for flexibility you usually don't need.

If you know the property names, use an interface. If you have a known set of keys, use Record. If keys are truly dynamic, use Map. Reserve index signatures for cases where you explicitly want to allow additional properties.

Based on "Effective TypeScript" by Dan Vanderkam, Item 16: Prefer More Precise Alternatives to Index Signatures.