What is the Record type?

Question

What does Record<K, T> mean in Typescript?

Typescript 2.1 introduced the Record type, describing it in an example:

// For every properties K of type T, transform it to U
function mapObject<K extends string, T, U>(obj: Record<K, T>, f: (x: T) => U): Record<K, U>

see Typescript 2.1

And the Advanced Types page mentions Record under the Mapped Types heading alongside Readonly, Partial, and Pick, in what appears to be its definition:

type Record<K extends string, T> = {
    [P in K]: T;
}

Readonly, Partial and Pick are homomorphic whereas Record is not. One clue that Record is not homomorphic is that it doesn’t take an input type to copy properties from:

type ThreeStringProps = Record<'prop1' | 'prop2' | 'prop3', string>

And that's it. Besides the above quotes, there is no other mention of Record on typescriptlang.org.

Questions

1. Can someone give a simple definition of what Record is?

2. Is Record<K,T> merely a way of saying "all properties on this object will have type T"? Probably not all properties, since K has some purpose...

3. Does the K generic forbid additional keys on the object that are not K, or does it allow them and just indicate that their properties are not transformed to T?

4. With the given example:

   type ThreeStringProps = Record<'prop1' | 'prop2' | 'prop3', string>
   

   Is it exactly the same as this?:

   type ThreeStringProps = {prop1: string, prop2: string, prop3: string}
   

Answer 1

A Record lets you create a new type from a Union. The values in the Union are used as attributes of the new type.

For example, say I have a Union like this:

type CatNames = "miffy" | "boris" | "mordred";

Now I want to create an object that contains information about all the cats, I can create a new type using the values in the CatNames union as keys.

type CatList = Record<CatNames, {age: number}>

If I want to satisfy this CatList, I must create an object like this:

const cats: CatList = {
  miffy: { age:99 },
  boris: { age:16 },
  mordred: { age:600 }
}

You get very strong type safety:

• If I forget a cat, I get an error.
• If I add a cat that's not allowed, I get an error.
• If I later change CatNames, I get an error. This is especially useful because CatNames is likely imported from another file, and likely used in many places.

Real-world React example.

I used this recently to create a Status component. The component would receive a status prop, and then render an icon. I've simplified the code quite a lot here for illustrative purposes

I had a union like this:

type Statuses = "failed" | "complete";

I used this to create an object like this:

const icons: Record<
  Statuses,
  { iconType: IconTypes; iconColor: IconColors }
> = {
  failed: {
    iconType: "warning",
    iconColor: "red"
  },
  complete: {
    iconType: "check",
    iconColor: "green"
  };

I could then render by destructuring an element from the object into props, like so:

const Status = ({status}) => <Icon {...icons[status]} />

If the Statuses union is later extended or changed, I know my Status component will fail to compile and I'll get an error that I can fix immediately. This allows me to add additional error states to the app.

Note that the actual app had dozens of error states that were referenced in multiple places, so this type safety was extremely useful.

Docs

Wonderful to see that my silly little cat example is now part of the official TypeScript docs!

https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type

Answer 2

1. Can someone give a simple definition of what Record is?

A Record<K, T> is an object type whose property keys are K and whose property values are T. That is, keyof Record<K, T> is equivalent to K, and Record<K, T>[K] is (basically) equivalent to T.

2. Is Record<K,T> merely a way of saying "all properties on this object will have type T"? Probably not all objects, since K has some purpose...

As you note, K has a purpose... to limit the property keys to particular values. If you want to accept all possible string-valued keys, you could do something like Record<string, T>, but the idiomatic way of doing that is to use an index signature like { [k: string]: T }.

3. Does the K generic forbid additional keys on the object that are not K, or does it allow them and just indicate that their properties are not transformed to T?

It doesn't exactly "forbid" additional keys: after all, a value is generally allowed to have properties not explicitly mentioned in its type... but it wouldn't recognize that such properties exist:

declare const x: Record<"a", string>;
x.b; // error, Property 'b' does not exist on type 'Record<"a", string>'

and it would treat them as excess properties which are sometimes rejected:

declare function acceptR(x: Record<"a", string>): void;
acceptR({a: "hey", b: "you"}); // error, Object literal may only specify known properties

and sometimes accepted:

const y = {a: "hey", b: "you"};
acceptR(y); // okay

4. With the given example:

    type ThreeStringProps = Record<'prop1' | 'prop2' | 'prop3', string>
   

   Is it exactly the same as this?:

    type ThreeStringProps = {prop1: string, prop2: string, prop3: string}
   

Yes!

Answer 3

There is now a slightly longer documentation of the Record type: https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type

Quoting that:

Record<Keys, Type> Released: 2.1

Constructs an object type whose property keys are Keys and whose property values are Type. This utility can be used to map the properties of a type to another type.

interface CatInfo {
  age: number;
  breed: string;
}
 
type CatName = "miffy" | "boris" | "mordred";
 
const cats: Record<CatName, CatInfo> = {
  miffy: { age: 10, breed: "Persian" },
  boris: { age: 5, breed: "Maine Coon" },
  mordred: { age: 16, breed: "British Shorthair" },
};
 
cats.boris;
 
const cats: Record<CatName, CatInfo>

Answer 4

simple example of using Record :

let say we have the following object and we want to define an object type for it.

const networkConfig = {
 4: {
    name: "rinkeby",
    ethUsdPriceFeed: "0x8A753747A1Fa494EC906cE90E9f37563A8AF630e",
  }
}

So the type will be like the following one using Record :

type networkConfigType = Record<number, {
    name: string;
    ethUsdPriceFeed: string;
}>;