Mapped types w TypeScript: składnia, modyfikatory i as

Mapped type buduje nowy typ obiektowy, przechodząc w pętli po zestawie kluczy. { [K in keyof T]: boolean } znaczy "dla każdego klucza K z T właściwość o nazwie K i typie 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

Dodaj klucz do Features, a Flags<Features> też będzie go wymagać. Mapped types istnieją tylko w czasie kompilacji: opisują obiekty, ale ich nie tworzą.

Składnia

Mapped type ma trzy części: zmienną klucza, unię kluczy, po której się iteruje, i typ właściwości, który może używać zmiennej klucza.

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

Keys może być dowolną unią stringów, liczb lub symboli. Nie musi pochodzić z 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

Dokładnie to robi Record<Size, number>; Record to jednolinijkowy mapped type. Typ właściwości może używać klucza: { [K in keyof T]: T[K] } kopiuje typ każdej właściwości przez indexed access, a { [K in keyof T]: T[K] | null } dopuszcza null w każdej właściwości.

Modyfikatory: readonly i ? z + i -

Mapped type może dodać lub usunąć modyfikatory readonly i opcjonalności (?) we wszystkich właściwościach naraz. Przedrostek + dodaje (to domyślne, gdy nie piszesz żadnego), a - usuwa:

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 }

Ostatnia linia pokazuje, że readonly to tylko reguła czasu kompilacji: przypisanie zostało zgłoszone (i tu wyciszone przez @ts-expect-error), ale wygenerowany JavaScript i tak je wykonał. -? robi więcej niż usunięcie znaku zapytania: usuwa też undefined z typu właściwości, więc AllRequired<Account> odrzuca { id: 1, email: undefined } z komunikatem error TS2322: Type 'undefined' is not assignable to type 'string'.

Jak zbudowane są Partial, Readonly, Pick i Record

Wbudowane utility types, które zmieniają kształt obiektów, to mapped types. Oto definicje z pliku lib.es5.d.ts samego 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 };

Czytanie ich to dobre ćwiczenie: Pick iteruje tylko po przekazanych kluczach, a Record ignoruje typ źródłowy i daje każdemu kluczowi ten sam typ wartości. Omit nie jest osobnym mapped type: to Pick<T, Exclude<keyof T, K>>. Wszystkie są wymienione w przeglądzie utility types.

Zmiana nazw kluczy przez as

Klauzula as po kluczu zmienia nazwę właściwości. W połączeniu z template literal types może generować nowe nazwy ze starych:

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 jest tu dlatego, że keyof T może zawierać klucze number i symbol, a Capitalize przyjmuje tylko stringi. Przecięcie zostawia klucze tekstowe i odrzuca resztę.

Filtrowanie kluczy przez never

Jeśli klauzula as daje never dla jakiegoś klucza, ten klucz zostaje usunięty. Z conditional type możesz zachować lub odrzucić właściwości na podstawie ich typu:

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

Typy takie jak DataOnly przydają się do opisania tego, co przetrwa JSON.stringify, albo tego, co edytuje formularz: pól bez metod.

Które modyfikatory są zachowywane

Mapped type po keyof T dla jakiegoś typu T nazywa się homomorficznym i kopiuje modyfikatory readonly oraz ? każdej właściwości z T. Mapped type po zwykłej unii kluczy zaczyna bez modyfikatorów:

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 wciąż ma undefined w typie email, bo Account["email"] go zawiera, ale sama właściwość nie jest już opcjonalna: { id: 1 } zostaje odrzucone. Dlatego Partial<T> i pokrewne typy mapują po keyof T: zachowują wszystko, czego jawnie nie zmieniają.

Generyczny homomorficzny mapped type zastosowany do tablicy lub krotki daje tablicę lub krotkę, a nie obiekt z kluczami liczbowymi. Readonly<string[]> to readonly string[], a przy type Box<T> = { [K in keyof T]: { value: T[K] } } typ Box<[string, number]> to [{ value: string }, { value: number }].

Mapped types a kod w czasie działania

Mapped type tylko opisuje obiekt, więc funkcja, która taki obiekt buduje, potrzebuje własnej pętli w czasie działania. Typ opisuje wtedy jej wynik:

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

Callbacki dostają typy parametrów z mapped type (v to string w jednym i number w drugim) bez żadnej adnotacji. Jeśli szukasz klasy Map, a nie mapowania typów, zobacz Map w TypeScript.