Utility types TypeScript : la liste complète avec exemples

Les utility types sont des types génériques intégrés à TypeScript qui transforment un type en un autre. Au lieu d'écrire un second type User avec tous les champs optionnels, vous écrivez Partial<User> ; au lieu de copier trois champs, Pick<User, "id" | "name">. Ils sont globaux, aucun import n'est donc nécessaire.

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

Quand User change, les quatre types dérivés suivent. La bibliothèque standard de TypeScript (lib.es5.d.ts) déclare 22 utility types. Les sections ci-dessous les listent tous, regroupés selon le genre de type sur lequel ils agissent, avec un lien vers la page détaillée quand elle existe.

Types objets : 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> est l'inverse de Partial<T> ; la page Partial couvre les deux, y compris le undefined explicite qu'un spread comme celui-ci laisse passer.

Types union : 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

Ces trois types agissent sur des unions, pas sur des objets. C'est la différence essentielle avec Pick et Omit, qui prennent un type objet et une liste de ses clés.

Types de fonctions et de classes : Parameters, ReturnType et autres

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 est nécessaire parce que ces utilitaires prennent un type, et createOrder est une valeur. Il en va de même pour les classes : typeof Point est le type du constructeur, alors que Point seul, employé comme type, désigne déjà le type d'instance.

NoInfer contrôle d'où un générique tire son type :

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");

Sans NoInfer, TypeScript inférerait C à partir des deux arguments et l'élargirait en "red" | "green" | "blue", si bien que la faute de frappe dans la valeur de repli serait acceptée.

Types de chaîne : Uppercase, Lowercase, Capitalize, Uncapitalize

Ces quatre types sont intégrés au compilateur au lieu d'être écrits en TypeScript, et ils sont surtout utiles dans les template literal types, comme `on${Capitalize<E>}` pour des noms de gestionnaires d'événements.

Promesses : 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>> est la façon standard de nommer le type du résultat d'une fonction async sans le déclarer à part.

Combiner les utility types

Les utility types s'imbriquent. Quelques combinaisons reviennent assez souvent pour valoir d'être connues par cœur :

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

Lisez un utility type imbriqué de l'intérieur vers l'extérieur : Readonly<Pick<Post, "id" | "title">> garde d'abord deux propriétés, puis les passe en lecture seule. Les mêmes briques permettent de construire un helper PartialBy qui ne rend optionnelles que certaines clés ; la page Partial l'écrit en entier.

Les utility types ne font rien à l'exécution

Chaque utility type est effacé à la compilation. Une valeur typée Omit<User, "password"> peut encore contenir un mot de passe à l'exécution si l'objet d'origine en avait un :

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"}

Le type limite seulement ce que votre code a le droit de lire. Pour retirer un champ des données, déstructurez-le comme dans les dernières lignes, et pour empêcher la mutation à l'exécution utilisez Object.freeze, pas Readonly. Les types intégrés sont des mapped types et des types conditionnels d'une ligne, les mêmes outils vous permettent donc d'écrire les vôtres.