Mapped types en TypeScript: sintaxis, modificadores y remapeo

Un mapped type construye un tipo objeto nuevo recorriendo un conjunto de claves. { [K in keyof T]: boolean } significa «para cada clave K de T, una propiedad llamada K de tipo boolean»:

type Features = {
  darkMode: string;
  search: number;
  export: string[];
};

// Same keys as T, every property turned into a boolean
type Flags<T> = { [K in keyof T]: boolean };

const enabled: Flags<Features> = {
  darkMode: true,
  search: false,
  export: true,
};

console.log(enabled); // { darkMode: true, search: false, export: true }
// Leaving out "export" would be error TS2741: Property 'export' is missing

Si añades una clave a Features, Flags<Features> también la exige. Los mapped types solo existen en compilación: describen objetos, no los crean.

La sintaxis

Un mapped type tiene tres partes: una variable de clave, una unión de claves que recorrer y el tipo de la propiedad, que puede usar la variable de clave.

type MappedType = {
  [K in Keys]: PropertyType; // K takes each member of Keys in turn
};

Keys puede ser cualquier unión de strings, números o símbolos. No tiene por qué venir de keyof:

type Size = "small" | "medium" | "large";

type PriceTable = { [S in Size]: number };
// { small: number; medium: number; large: number }

const prices: PriceTable = { small: 3, medium: 4, large: 5 };

for (const size of ["small", "large"] as const) {
  console.log(size, prices[size]);
}
// small 3
// large 5

Es exactamente lo que hace Record<Size, number>; Record es un mapped type de una línea. El tipo de la propiedad puede usar la clave: { [K in keyof T]: T[K] } copia el tipo de cada propiedad mediante un indexed access, y { [K in keyof T]: T[K] | null } hace que todas las propiedades admitan null.

Modificadores: readonly y ? con + y -

Un mapped type puede añadir o quitar los modificadores readonly y opcional (?) de todas las propiedades a la vez. El prefijo + añade (es lo que se aplica si no escribes ninguno) y - quita:

type Account = {
  readonly id: number;
  email?: string;
};

type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type AllRequired<T> = { [K in keyof T]-?: T[K] };
type Frozen<T> = { +readonly [K in keyof T]: T[K] };

const editable: Mutable<Account> = { id: 1 };
editable.id = 2; // allowed: readonly was removed

const complete: AllRequired<Account> = { id: 1, email: "a@b.co" };
// { id: 1 } alone would be error TS2741: Property 'email' is missing

const frozen: Frozen<{ n: number }> = { n: 1 };
// @ts-expect-error: Cannot assign to 'n' because it is a read-only property
frozen.n = 2;

console.log(editable, complete, frozen);
// { id: 2 } { id: 1, email: 'a@b.co' } { n: 2 }

La última línea muestra que readonly es solo una regla de compilación: la asignación se detectó (y aquí se suprimió con @ts-expect-error), pero el JavaScript generado la ejecutó igualmente. -? hace algo más que quitar el signo de interrogación: también quita undefined del tipo de la propiedad, así que AllRequired<Account> rechaza { id: 1, email: undefined } con error TS2322: Type 'undefined' is not assignable to type 'string'.

Cómo se construyen Partial, Readonly, Pick y Record

Los utility types integrados que transforman objetos son mapped types. Estas son las definiciones del propio lib.es5.d.ts de TypeScript:

type Partial<T> = { [P in keyof T]?: T[P] };
type Required<T> = { [P in keyof T]-?: T[P] };
type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Pick<T, K extends keyof T> = { [P in K]: T[P] };
type Record<K extends keyof any, T> = { [P in K]: T };

Leerlas es buena práctica: Pick recorre solo las claves que le pasas, y Record ignora cualquier tipo de origen y da a cada clave el mismo tipo de valor. Omit no es un mapped type propio: es Pick<T, Exclude<keyof T, K>>. La referencia de utility types los recoge todos.

Remapeo de claves con as

Una cláusula as después de la clave cambia el nombre de la propiedad. Combinada con template literal types, puede generar nombres nuevos a partir de los antiguos:

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type Person = { name: string; age: number };

// { getName: () => string; getAge: () => number }
const person: Getters<Person> = {
  getName: () => "Ada",
  getAge: () => 36,
};

console.log(person.getName(), person.getAge()); // Ada 36

string & K está ahí porque keyof T puede incluir claves number y symbol, y Capitalize solo acepta strings. La intersección conserva las claves string y descarta el resto.

Filtrar claves con never

Si la cláusula as produce never para una clave, esa clave desaparece. Con un conditional type puedes conservar o descartar propiedades según su tipo:

type DataOnly<T> = {
  [K in keyof T as T[K] extends (...args: any[]) => unknown ? never : K]: T[K];
};

class Invoice {
  constructor(public id: number, public total: number) {}
  format(): string {
    return `#${this.id}: ${this.total.toFixed(2)}`;
  }
}

// { id: number; total: number }  (format is gone)
const data: DataOnly<Invoice> = { id: 7, total: 19.5 };

console.log(data);                        // { id: 7, total: 19.5 }
console.log(new Invoice(7, 19.5).format()); // #7: 19.50

Tipos como DataOnly sirven para describir lo que sobrevive a JSON.stringify o lo que edita un formulario: los campos sin los métodos.

Qué modificadores se conservan

Un mapped type sobre keyof T para algún tipo T se llama homomórfico, y copia de T los modificadores readonly y ? de cada propiedad. Un mapped type sobre una simple unión de claves empieza sin modificadores:

type Account = { readonly id: number; email?: string };

type Copy<T> = { [K in keyof T]: T[K] };
type A = Copy<Account>;
// { readonly id: number; email?: string }  (modifiers kept)

type B = { [K in "id" | "email"]: Account[K] };
// { id: number; email: string | undefined }  (email is required now)

B sigue teniendo undefined en el tipo de email, porque Account["email"] lo incluye, pero la propiedad ya no es opcional: { id: 1 } se rechaza. Por eso Partial<T> y compañía recorren keyof T: conservan todo lo que no cambian de forma explícita.

Un mapped type homomórfico genérico aplicado a un array o a una tupla produce un array o una tupla, no un objeto con claves numéricas. Readonly<string[]> es readonly string[], y con type Box<T> = { [K in keyof T]: { value: T[K] } }, Box<[string, number]> es [{ value: string }, { value: number }].

Mapped types y código en ejecución

Como un mapped type solo describe un objeto, una función que construye ese objeto necesita su propio bucle en tiempo de ejecución. El tipo describe después su resultado:

type Validators<T> = { [K in keyof T]: (value: T[K]) => boolean };

type SignUp = { email: string; age: number };

const rules: Validators<SignUp> = {
  email: (v) => v.includes("@"), // v is string
  age: (v) => v >= 13,           // v is number
};

function validate(form: SignUp): string[] {
  const failed: string[] = [];
  for (const key of Object.keys(rules) as (keyof SignUp)[]) {
    const ok = key === "email" ? rules.email(form.email) : rules.age(form.age);
    if (!ok) failed.push(key);
  }
  return failed;
}

console.log(validate({ email: "ada@example.com", age: 36 })); // []
console.log(validate({ email: "nope", age: 9 }));             // [ 'email', 'age' ]

Los callbacks reciben los tipos de sus parámetros del mapped type (v es string en uno y number en el otro) sin ninguna anotación. Si llegaste aquí buscando la clase Map y no la transformación de tipos, consulta Map en TypeScript.