Mapped types in TypeScript: sintassi, modificatori e rimappatura

Un mapped type costruisce un nuovo tipo oggetto scorrendo un insieme di chiavi. { [K in keyof T]: boolean } significa "per ogni chiave K di T, una proprietà di nome K e 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

Aggiungi una chiave a Features e anche Flags<Features> la richiede. I mapped types esistono solo in fase di compilazione: descrivono oggetti, non li creano.

La sintassi

Un mapped type ha tre parti: una variabile per la chiave, un'unione di chiavi su cui iterare e il tipo della proprietà, che può usare la variabile della chiave.

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

Keys può essere qualsiasi unione di stringhe, numeri o symbol. Non deve per forza venire da 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

È esattamente ciò che fa Record<Size, number>; Record è un mapped type di una riga. Il tipo della proprietà può usare la chiave: { [K in keyof T]: T[K] } copia il tipo di ogni proprietà tramite un indexed access, e { [K in keyof T]: T[K] | null } rende nullable ogni proprietà.

Modificatori: readonly e ? con + e -

Un mapped type può aggiungere o togliere i modificatori readonly e opzionale (?) su tutte le proprietà in un colpo solo. Il prefisso + aggiunge (è il comportamento predefinito se non scrivi nulla) e - toglie:

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 }

L'ultima riga mostra che readonly è solo una regola della fase di compilazione: l'assegnazione è stata segnalata (e qui soppressa con @ts-expect-error), ma il JavaScript generato l'ha eseguita comunque. -? fa più che togliere il punto interrogativo: toglie anche undefined dal tipo della proprietà, quindi AllRequired<Account> rifiuta { id: 1, email: undefined } con error TS2322: Type 'undefined' is not assignable to type 'string'.

Come sono fatti Partial, Readonly, Pick e Record

I tipi di utilità integrati che rimodellano gli oggetti sono mapped types. Queste sono le definizioni prese dal lib.es5.d.ts di 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 };

Leggerle è un buon esercizio: Pick itera solo sulle chiavi che passi, e Record ignora qualsiasi tipo di partenza e dà a ogni chiave lo stesso tipo di valore. Omit non è un mapped type a sé: è Pick<T, Exclude<keyof T, K>>. Il riferimento sugli utility types li elenca tutti.

Rimappare le chiavi con as

Una clausola as dopo la chiave cambia il nome della proprietà. Insieme ai template literal types, può generare nomi nuovi a partire da quelli vecchi:

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 serve perché keyof T può includere chiavi number e symbol, e Capitalize accetta solo stringhe. L'intersezione tiene le chiavi stringa e scarta le altre.

Filtrare le chiavi con never

Se la clausola as produce never per una chiave, quella chiave viene rimossa. Con un conditional type puoi tenere o scartare proprietà in base al loro 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

Tipi come DataOnly sono utili per descrivere cosa sopravvive a JSON.stringify o cosa modifica un form: i campi senza i metodi.

Quali modificatori vengono mantenuti

Un mapped type su keyof T per un tipo T si chiama omomorfo, e copia da T i modificatori readonly e ? di ogni proprietà. Un mapped type su una semplice unione di chiavi parte senza modificatori:

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 ha ancora undefined nel tipo di email, perché Account["email"] lo include, ma la proprietà in sé non è più opzionale: { id: 1 } viene rifiutato. Ecco perché Partial<T> e simili mappano su keyof T: mantengono tutto ciò che non cambiano esplicitamente.

Un mapped type omomorfo generico applicato a un array o a una tupla produce un array o una tupla, non un oggetto con chiavi numeriche. Readonly<string[]> è readonly string[], e con type Box<T> = { [K in keyof T]: { value: T[K] } }, Box<[string, number]> è [{ value: string }, { value: number }].

Mapped types e codice a runtime

Dato che un mapped type descrive soltanto un oggetto, una funzione che costruisce un oggetto del genere ha bisogno di un proprio ciclo a runtime. Il tipo descrive poi il suo risultato:

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' ]

Le callback ricevono i tipi dei parametri dal mapped type (v è string in una e number nell'altra) senza nessuna annotazione. Se cercavi la classe Map e non la mappatura dei tipi, vedi Map in TypeScript.