Utility types in TypeScript: la lista completa con esempi

Gli utility types sono tipi generici integrati in TypeScript che trasformano un tipo in un altro. Invece di scrivere un secondo tipo User con tutti i campi opzionali, scrivi Partial<User>; invece di copiare tre campi, Pick<User, "id" | "name">. Sono globali, quindi non serve importarli.

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
}

type UserPatch = Partial<User>;                 // every field optional
type UserCard = Pick<User, "id" | "name">;      // only id and name
type PublicUser = Omit<User, "password">;       // everything but password
type UsersById = Record<number, PublicUser>;    // an object keyed by id

const patch: UserPatch = { email: "new@example.com" };
const card: UserCard = { id: 1, name: "Ada" };
const users: UsersById = {
  1: { id: 1, name: "Ada", email: "ada@example.com" },
};

console.log(patch, card, users[1].email);
// { email: 'new@example.com' } { id: 1, name: 'Ada' } ada@example.com

Quando User cambia, tutti e quattro i tipi derivati si adeguano. La libreria standard di TypeScript (lib.es5.d.ts) dichiara 22 utility types. Le sezioni seguenti li elencano tutti, raggruppati in base al genere di tipo su cui lavorano, con un link alla pagina dettagliata quando esiste.

Tipi oggetto: Partial, Required, Readonly, Pick, Omit, Record

interface Config {
  host: string;
  port?: number;
  debug?: boolean;
}

const defaults: Required<Omit<Config, "host">> = { port: 8080, debug: false };

function withDefaults(config: Config): Readonly<Required<Config>> {
  return { ...defaults, ...config };
}

const cfg = withDefaults({ host: "localhost", debug: true });
console.log(cfg); // { port: 8080, debug: true, host: 'localhost' }
// cfg.port = 1 would be error TS2540: Cannot assign to 'port' because it is a read-only property.

Required<T> è l'opposto di Partial<T>; la pagina su Partial tratta entrambi, compreso l'undefined esplicito che uno spread come questo lascia passare.

Tipi unione: Exclude, Extract, NonNullable

type Status = "draft" | "review" | "published" | "archived";

type Live = Exclude<Status, "draft" | "archived">; // "review" | "published"
type Mixed = string | number | (() => void);
type Callable = Extract<Mixed, (...args: never[]) => unknown>; // () => void

function lookup(id: number): string | undefined {
  return id === 1 ? "Ada" : undefined;
}
type Found = NonNullable<ReturnType<typeof lookup>>; // string

const s: Live = "review";
const run: Callable = () => console.log("called");
const found: Found = lookup(1) ?? "nobody";
run();
console.log(s, found); // review Ada

Questi tre lavorano sulle unioni, non sugli oggetti. È questa la differenza chiave rispetto a Pick e Omit, che ricevono un tipo oggetto e una lista delle sue chiavi.

Tipi di funzioni e classi: Parameters, ReturnType e altri

function createOrder(customer: string, items: string[], express = false) {
  return { customer, items, express, total: items.length * 10 };
}

type OrderArgs = Parameters<typeof createOrder>; // [customer: string, items: string[], express?: boolean | undefined]
type Order = ReturnType<typeof createOrder>;     // { customer: string; items: string[]; express: boolean; total: number }

const args: OrderArgs = ["Ada", ["book", "pen"]];
const order: Order = createOrder(...args);
console.log(order.total, order.express); // 20 false

class Point {
  constructor(public x: number, public y: number) {}
}
const coords: ConstructorParameters<typeof Point> = [3, 4];
const p: InstanceType<typeof Point> = new Point(...coords);
console.log(p); // Point { x: 3, y: 4 }

typeof createOrder serve perché queste utility ricevono un tipo, e createOrder è un valore. Lo stesso vale per le classi: typeof Point è il tipo del costruttore, mentre Point da solo, usato come tipo, indica già il tipo dell'istanza.

NoInfer controlla da dove un generic prende il suo tipo:

function pickColor<C extends string>(colors: C[], fallback: NoInfer<C>): C {
  return colors[0] ?? fallback;
}

console.log(pickColor(["red", "green"], "green")); // red
// @ts-expect-error: "blue" is not "red" | "green"
pickColor(["red", "green"], "blue");

Senza NoInfer, TypeScript dedurrebbe C da entrambi gli argomenti e lo allargherebbe a "red" | "green" | "blue", quindi il refuso nel valore di ripiego verrebbe accettato.

Tipi per le stringhe: Uppercase, Lowercase, Capitalize, Uncapitalize

Questi quattro sono integrati nel compilatore invece di essere scritti in TypeScript, e danno il meglio dentro i template literal types, come `on${Capitalize<E>}` per i nomi dei gestori di eventi.

Promise: Awaited

async function fetchUser(id: number) {
  return { id, name: "Ada" };
}

type Pending = ReturnType<typeof fetchUser>;           // Promise<{ id: number; name: string }>
type User = Awaited<ReturnType<typeof fetchUser>>;      // { id: number; name: string }

async function main() {
  const user: User = await fetchUser(1);
  const all: User[] = await Promise.all([fetchUser(2), fetchUser(3)]);
  console.log(user.name, all.map((u) => u.id)); // Ada [ 2, 3 ]
}
main();

Awaited<ReturnType<typeof fn>> è il modo standard per dare un nome al tipo del risultato di una funzione async senza dichiararlo a parte.

Combinare gli utility types

Gli utility types si annidano. Alcune combinazioni ricorrono abbastanza spesso da valere la pena di impararle a memoria:

interface Post {
  id: number;
  title: string;
  body: string;
  tags: string[];
}

// Create: everything except the server-generated id
type NewPost = Omit<Post, "id">;
// Update: id required, everything else optional
type PostUpdate = Pick<Post, "id"> & Partial<Omit<Post, "id">>;
// A lookup table of read-only summaries
type PostIndex = Record<number, Readonly<Pick<Post, "id" | "title">>>;

const created: NewPost = { title: "Hello", body: "...", tags: [] };
const update: PostUpdate = { id: 1, title: "Hello again" };
const index: PostIndex = { 2: { id: 2, title: "Idea" } };
console.log(created.title, update, index[2]);
// Hello { id: 1, title: 'Hello again' } { id: 2, title: 'Idea' }

Un utility type annidato si legge dall'interno verso l'esterno: Readonly<Pick<Post, "id" | "title">> prima conserva due proprietà, poi le rende di sola lettura. Con gli stessi pezzi si costruisce un helper PartialBy che rende opzionali solo alcune chiavi; la pagina su Partial lo scrive per intero.

Gli utility types non fanno nulla a runtime

Ogni utility type viene cancellato quando il codice viene compilato. Un valore tipizzato come Omit<User, "password"> può ancora contenere una password a runtime, se l'oggetto da cui proviene ne aveva una:

interface User {
  name: string;
  password: string;
}

const full: User = { name: "Ada", password: "hunter2" };

const leaky: Omit<User, "password"> = full; // allowed: extra properties are fine
console.log(JSON.stringify(leaky)); // {"name":"Ada","password":"hunter2"}

const { password, ...safe } = full;          // this actually removes it
console.log(JSON.stringify(safe));  // {"name":"Ada"}

Il tipo limita solo ciò che il tuo codice può leggere. Per togliere un campo dai dati, estrailo con una destrutturazione come nelle ultime righe, e per impedire modifiche a runtime usa Object.freeze, non Readonly. I tipi integrati sono mapped types e conditional types di una riga, quindi con gli stessi strumenti puoi scrivere i tuoi.