Index signatures & Record

Objects whose keys you don't know yet

A shop keeps a count of how many of each product is in stock. The keys are product IDs, and new products arrive all the time, so you can't list every key when you write the code. In JavaScript, you add and read keys with square brackets:

const stock = { tea: 3, jam: 5 };
stock["mint"] = 8;

const productId = "jam";
console.log(stock[productId]);

Line 1 makes stock with two products. Line 2 adds a third, mint. Line 4 picks a product ID, and line 5 reads it with stock[productId], the square-bracket way to use a key held in a variable. It prints 5. (Object basics covers square brackets.)

An object type like { tea: number; jam: number } can't describe this, because it would need every name ahead of time. TypeScript has a type for "any key, but every value is a number":

1type Stock = { [productId: string]: number };2 3const stock: Stock = { tea: 3, jam: 5 };4stock["mint"] = 8;5stock["honey"] = "none";6 7const count = stock["jam"];8//    ^?9console.log(count);

Line 1 is the new part. [productId: string]: number is an index signature. Read it as "for any key that is a string, the value is a number". productId is only a label for the key; any name works there. Then:

• Line 3 makes the stock, and line 4 adds mint. Both are fine: any string key is allowed.
• Line 5 stores the text "none". TypeScript marks it, on purpose: Type 'string' is not assignable to type 'number' means "the value must be a number, and this is text".
• Line 7 reads jam. The query on line 8 shows const count: number, and line 9 prints 5.

Writing an index signature

An index signature goes inside an object type, in square brackets: a label for the key, a colon, the key's type, then a colon and the value's type. The key type is usually string. You can read and write keys with a dot too, like stock.tea, as long as the name is a valid JavaScript name.

A type can have named properties as well, but every one of them must fit the index signature:

1type Inventory = {2  updatedAt: string;3  [productId: string]: number;4};

Line 2 says an Inventory has an updatedAt that is text. Line 3 says every string key holds a number. But updatedAt is a string key too, so it would have to hold a number. TypeScript says Property 'updatedAt' of type 'string' is not assignable to 'string' index type 'number': the named property breaks the rule.

One fix is to let the values be either type:

1type Inventory = {2  updatedAt: string;3  [productId: string]: number | string;4};5 6const inventory: Inventory = { updatedAt: "09:00", tea: 3 };7const tea = inventory["tea"];8//    ^?9console.log(tea);

Line 3 now says number | string: a number or text (Union types covers |). There's no error. But look at the query on line 8: tea is string | number, so every count you read could be text, and you'd have to check before adding. A cleaner fix puts the counts in an object of their own:

1type Inventory = {2  updatedAt: string;3  counts: { [productId: string]: number };4};5 6const inventory: Inventory = { updatedAt: "09:00", counts: { tea: 3 } };7const tea = inventory.counts["tea"];8//    ^?9console.log(tea);

Line 3 makes counts a property, with its own index signature. Line 6 fills it in. Line 7 reads inventory.counts["tea"], and the query on line 8 shows a plain number. Line 9 prints 3. Keeping the lookup table apart from the named fields keeps both types simple.

Like any property, an index signature can be readonly, so no key can be changed after the object is made:

1const prices: { readonly [productId: string]: number } = { tea: 3, jam: 5 };2prices["tea"] = 1;

Line 1 makes the prices with a readonly index signature. Line 2 tries to change the tea's price. TypeScript says Index signature in type … only permits reading: you may read any key, but not write one.

The Record type

TypeScript comes with a shorter way to write the same thing: Record<K, V>. You fill in two types inside the angle brackets: K for the keys and V for the values. Record<string, number> means "any string key, holding a number", exactly like the overview's type:

1type Stock = Record<string, number>;2 3const stock: Stock = { tea: 3, jam: 5 };4stock["mint"] = 8;5stock["honey"] = "none";6console.log(Object.keys(stock).join(", "));

Line 1 makes Stock a Record<string, number>. Lines 3 and 4 work as before. Line 5 gets the same error as the overview, on purpose, because the value must be a number. Line 6 lists the keys with Object.keys (Object.keys, values, entries) and prints tea, jam, mint, honey: the error didn't stop line 5 from running.

Record can do something an index signature with string can't: take a fixed list of keys. A union of strings like "small" | "medium" | "large" means "one of these three words". Give that to Record, and the object must have exactly those keys:

1type Size = "small" | "medium" | "large";2 3const cupPrices: Record<Size, number> = {4  small: 3,5  medium: 4,6};

Line 1 makes Size, the three sizes. Line 3 says cupPrices has a number for every size. Lines 4 and 5 give two. TypeScript marks line 3: Property 'large' is missing in type … but required in type 'Record<Size, number>'. Every key in the list is required. An extra key, like huge: 6, would get the excess property error from the previous lesson.

Reading works the same way. Type a key for line 8 to read, and watch the list under the code:

1type Size = "small" | "medium" | "large";2 3const cupPrices: Record<Size, number> = {4  small: 3,5  medium: 4,6  large: 5,7};8console.log(cupPrices.medium);

small, medium, and large have no errors and print their prices. huge gets Property 'huge' does not exist, and Medium gets a Did you mean 'medium'? suggestion. With Record<string, number>, every one of those keys would be allowed, and the wrong ones would print undefined.

The table below compares the three ways. Read each row as: the type, which keys it allows, and what reading a key it doesn't have does.

Keys that aren't there

An index signature says what every key would hold, not which keys exist. So by default, TypeScript says reading any key gives a number, even a key nobody stored. The noUncheckedIndexedAccess setting changes that. It's a compiler option (a setting in your project's tsconfig.json), and strict doesn't turn it on. Press each button:

1type Stock = Record<string, number>;2 3const stock: Stock = { tea: 3, jam: 5 };4const cakes = stock["cake"];5//    ^?6console.log(cakes + 1);

Line 3 makes the stock with tea and jam. Line 4 reads cake, which isn't there. The query on line 5 shows the type TypeScript gives it, and line 6 adds 1. With Flag off, the type is number, there are no errors, and it prints NaN. With Flag on, the type is number | undefined, and TypeScript marks line 6 on purpose: 'cakes' is possibly 'undefined' means "this might be nothing, check first". Flag on, with ?? 0 uses 0 when the key is missing (the ?? operator), so it prints 1 with no errors.

The flag covers arrays too, because a position like cart[2] may not exist either:

1const cart = ["tea", "jam"];2const third = cart[2];3//    ^?4console.log(third.toUpperCase());

This example turns the flag on; the list under the code shows it. Line 1 makes a cart with two items. Line 2 reads position 2, the third item. The query on line 3 shows string | undefined. Line 4 calls toUpperCase on it, and TypeScript says 'third' is possibly 'undefined'. It's right: when this runs, it throws a TypeError. Keys that a Record lists, like cupPrices.small, are known to exist, so the flag leaves them as plain number.

Maps vs objects

JavaScript has a second way to keep a lookup table: a Map. In TypeScript, you say the key and value types in angle brackets, as with Record:

1const tagCounts = new Map<string, number>();2 3for (const tag of ["sale", "new", "sale"]) {4  tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);5}6 7const sales = tagCounts.get("sale");8//    ^?9console.log(sales, tagCounts.size);

Line 1 makes an empty Map<string, number>: string keys, number values. Line 3 loops over three tags. Line 4 adds 1 to each tag's count, using 0 when .get() finds nothing. Line 7 reads the sale count. The query on line 8 shows number | undefined: a Map's .get() always admits it might find nothing, flag or no flag. Line 9 prints 2 2: two sales, and two different tags.

Here is the same counter with a plain object. TypeScript reports nothing, but watch the second tag:

1const tagCounts: Record<string, number> = {};2 3for (const tag of ["sale", "constructor"]) {4  tagCounts[tag] = (tagCounts[tag] ?? 0) + 1;5}6 7console.log(tagCounts["sale"]);8console.log(tagCounts["constructor"]);

Line 3 loops over sale and constructor. Line 7 prints 1, as expected. Line 8 prints function Object() { [native code] }1. Every plain object already has a few built-in properties, like constructor and toString, that it gets from Object.prototype (the Prototype chain lesson explains where they come from). So tagCounts["constructor"] was never missing: it was a function, and adding 1 joined it into text. The type said number the whole time. When keys come from users, like search tags, a Map avoids this.

The table below compares the two. Read each row as a question, then the answer for a plain object and for a Map.

Translations for a language switcher

A page shows a greeting in the language the visitor picks: English, Hindi, or Tamil. A Record over the list of languages makes sure no language is forgotten:

1type Language = "en" | "hi" | "ta";2 3const greeting: Record<Language, string> = {4  en: "Hello",5  hi: "Namaste",6};7 8function greet(language: Language) {9  return greeting[language];10}11console.log(greet("ta"));

Line 1 lists the three languages. Line 3 says greeting has a string for each. Lines 4 and 5 give English and Hindi, and TypeScript marks line 3: Property 'ta' is missing. Line 8 makes greet, which looks up the chosen language on line 9. Run it anyway, and line 11 prints undefined: a Tamil visitor would see an empty greeting.

1type Language = "en" | "hi" | "ta";2 3const greeting: Record<Language, string> = {4  en: "Hello",5  hi: "Namaste",6  ta: "Vanakkam",7};8 9function greet(language: Language) {10  return greeting[language];11}12console.log(greet("ta"));

Line 6 adds ta: "Vanakkam". The error is gone, and line 12 prints Vanakkam. If someone adds a fourth language to line 1 later, TypeScript points at every Record that needs a new entry.

Common mix-ups

• "An index signature means every key exists." No. It says what a key would hold. A key nobody stored gives undefined when the code runs.
• "strict turns on noUncheckedIndexedAccess." No. You turn it on by itself in tsconfig.json.
• "Record is something different from an index signature." No. Record<string, number> and { [key: string]: number } are the same type. Record can also take a fixed list of keys.
• "Record<Size, number> lets me leave a size out." No. Every key in the list is required.
• "After .has(), a Map's .get() can't be undefined." No. TypeScript still says number | undefined. Read the value once and check it.
• "An empty object has no keys." No. It already has built-in ones like constructor and toString, which is why a Map is safer for keys that come from users.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1const prices: { [name: string]: number } = { tea: 3, jam: 5 };2const cake = prices["cake"];

1const prices: { [name: string]: number } = { tea: 3, jam: 5 };2const cake = prices["cake"];3//    ^?

type Stock = Record<string, number>;

const stock: Stock = {
  tea: 3,
  jam: "5",
  mint: 8,
};

1type Stock = Record<string, number>;2 3const stock: Stock = {4  tea: 3,5  jam: 5,6  mint: 8,7};

1type Size = "small" | "medium" | "large";2 3const cupPrices: Record<Size, number> = {4  small: 3,5  medium: 4,6};7 8console.log(cupPrices.small + cupPrices.medium + cupPrices.large);

1type Size = "small" | "medium" | "large";2 3const cupPrices: Record<Size, number> = {4  small: 3,5  medium: 4,6  large: 5,7};8 9console.log(cupPrices.small + cupPrices.medium + cupPrices.large);

1type Inventory = {2  updatedAt: string;3  [productId: string]: number;4};5 6const inventory: Inventory = { updatedAt: "09:00", tea: 3 };7console.log(inventory["tea"]);

1type Inventory = {2  updatedAt: string;3  counts: { [productId: string]: number };4};5 6const inventory: Inventory = { updatedAt: "09:00", counts: { tea: 3 } };7console.log(inventory.counts["tea"]);

1const stock: Record<string, number> = { tea: 3, jam: 5 };2 3function restock(productId: string) {4  stock[productId] = stock[productId] + 10;5  return stock[productId];6}7 8console.log(restock("cake"));

1const stock: Record<string, number> = { tea: 3, jam: 5 };2 3function restock(productId: string) {4  stock[productId] = (stock[productId] ?? 0) + 10;5  return stock[productId];6}7 8console.log(restock("cake"));

1const counts = new Map<string, number>();2 3for (const tag of ["sale", "new", "sale"]) {4  counts.set(tag, counts.get(tag) + 1);5}6 7console.log(counts.get("sale"));

1const counts = new Map<string, number>();2 3for (const tag of ["sale", "new", "sale"]) {4  counts.set(tag, (counts.get(tag) ?? 0) + 1);5}6 7console.log(counts.get("sale"));

Check your understanding

For each question, keep two things apart: which keys the type allows, and which keys the object really has when the code runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• An index signature, [productId: string]: number, types an object whose keys you don't know ahead of time.
• Every named property in the same type must fit the index signature. Keep a lookup table in a property of its own.
• Record<string, number> is the same type. Record<Size, number> takes a list of keys and needs every one.
• By default, reading any key is typed as the value type. noUncheckedIndexedAccess adds undefined, so you check first.
• A Map's .get() always gives value | undefined, and a Map has no built-in keys. Use one for keys that come from users.

Coming next: Intersection types. It combines object types with &, so one object has every property from both.