Alias de type en TypeScript : le mot-clé type avec exemples

Un alias de type donne un nom à un type. Vous écrivez type Name = ..., et à partir de là Name peut être utilisé partout où un type est attendu. Contrairement à une interface, un alias peut nommer absolument n'importe quel type, pas seulement des formes d'objets.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

Les alias n'existent qu'à la compilation. Le JavaScript émis ne contient aucune de ces lignes type.

Syntaxe

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

Par convention, les noms sont en PascalCase. Le côté droit est n'importe quelle expression de type, et un alias peut utiliser d'autres alias, y compris lui-même (voir les types récursifs plus bas). L'alias est disponible dans toute la portée où il est déclaré, même au-dessus de la ligne de déclaration, car les types sont vérifiés à la compilation et ne s'exécutent pas dans l'ordre comme const ou let.

Types objet

Pour une forme d'objet, un alias et une interface s'écrivent presque de la même façon. L'alias utilise = et se termine en général par un point-virgule.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

Un alias ne peut pas utiliser extends ; c'est l'intersection & qui joue ce rôle. La vérification des propriétés en trop, les propriétés optionnelles et readonly fonctionnent exactement comme pour les interfaces. Le choix entre les deux pour les formes d'objets est traité sur la page interface ou type.

Unions, tuples et fonctions

Ce sont les cas que seul un alias peut nommer, et la principale raison d'être de type. Un alias d'union liste les alternatives, un alias de tuple fixe la longueur et le type des éléments d'un tableau, et un alias de fonction décrit une signature.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

Dans scale, les paramètres n'ont pas besoin d'annotations : l'alias Transform fournit leurs types. La syntaxe des tuples est présentée dans tuples, et le narrowing des unions sur la page des types union.

Alias de type génériques

Les paramètres de type permettent à un seul alias de servir pour de nombreux types. Ils peuvent avoir des valeurs par défaut, comme les paramètres de fonction.

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> utilise la valeur par défaut E = string. De petits alias génériques comme type Nullable<T> = T | null ou type Dict<T> = Record<string, T> sont courants dans du vrai code. Les types utilitaires intégrés (Partial<T>, Pick<T, K>, ReturnType<F>) sont eux aussi des alias génériques, déclarés dans la bibliothèque standard.

Les alias sont des noms, pas de nouveaux types

Un alias ne crée pas de type distinct. C'est un second nom pour le type de droite, et le compilateur traite les deux comme identiques. Deux alias de string sont entièrement interchangeables :

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

Ce code affiche cancelling u_42 sans erreur, et c'est précisément le bug qu'un alias ne peut pas empêcher. L'alias aide quand même les lecteurs (un paramètre typé OrderId en dit plus que string), mais si confondre deux identifiants doit être une erreur de compilation, utilisez un type branded comme string & { readonly __brand: "OrderId" }.

Alias de type récursifs

Un alias peut faire référence à lui-même, c'est ainsi qu'on décrit des arbres, des listes imbriquées et du JSON :

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

L'alias Json refuse les valeurs que JSON ne peut pas représenter : { when: new Date() } ou { f: undefined } assignés à Json sont des erreurs de compilation (TS2322).

Des types à partir de valeurs : typeof

Quand une valeur existe déjà, vous pouvez nommer son type au lieu de l'écrire. L'opérateur de type typeof lit le type d'une variable, et il se combine avec d'autres opérateurs :

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

La valeur reste l'unique source de vérité : ajoutez une propriété à defaults et Options suit. Plus de détails dans typeof.

Exporter et importer des alias

Les alias s'exportent et s'importent comme des valeurs. import type indique explicitement que seul un type est importé, si bien que l'import est toujours retiré de la sortie JavaScript :

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };