Bonnes pratiques TypeScript : 8 règles avec avant et après

Les règles ci-dessous sont celles qui évitent le plus de bugs dans du vrai code TypeScript. Chacune montre d'abord la version courante, puis la meilleure, dans du code que vous pouvez exécuter. La première règle est la plus importante : arrêtez d'utiliser any.

Utiliser unknown plutôt que any

any désactive la vérification des types pour une valeur et pour tout ce qui est calculé à partir d'elle. unknown accepte lui aussi n'importe quelle valeur, mais vous devez la vérifier avant de l'utiliser, ce qui place la vérification là où les données entrent dans votre programme :

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

Les frontières sont les endroits où les types cessent d'être garantis : JSON.parse, les réponses de fetch, localStorage, les saisies de formulaire, les variables d'environnement et les messages d'autres processus. Validez à ces endroits avec un type guard ou une bibliothèque de schémas, et le reste du code peut faire confiance à ses types.

Garder strict activé

strict est la valeur par défaut dans TypeScript 7 ; ne le désactivez pas. Ajoutez les vérifications qu'il laisse de côté et qui attrapent le plus de bugs :

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

noUncheckedIndexedAccess fait inclure undefined à arr[i] et record[key], puisque c'est ce qu'ils renvoient pour un index absent. noImplicitOverride oblige une méthode de sous-classe à indiquer override, et noFallthroughCasesInSwitch refuse un case qui déborde sur le suivant.

Laisser l'inférence travailler

Annotez ce que TypeScript ne peut pas savoir : les paramètres de fonctions, et les types de retour des fonctions utilisées par d'autres modules. Laissez l'inférence gérer les variables locales et les paramètres des callbacks. Une annotation inutile n'est pas seulement du bruit : elle peut rendre un type plus large que la valeur :

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

Sans le commentaire @ts-expect-error, setStatus(annotated) provoque l'erreur TS2345. La const déduite garde le type littéral "active", elle est donc acceptée. Survolez une variable dans votre éditeur pour voir ce qui a été déduit avant d'ajouter un type.

Préférer les unions aux enums

Une union de littéraux de chaîne offre l'autocomplétion et des vérifications exhaustives sans code généré. Quand vous avez aussi besoin de la liste des valeurs à l'exécution, dérivez le type d'un tableau as const :

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

Un enum Role { Admin, Viewer } se compile en un objet avec un mappage inverse, et un paramètre de type enum numérique accepte n'importe quelle variable number, même une qui contient une valeur que l'enum ne liste pas. Les enums ne peuvent pas non plus tourner avec le type stripping de Node (TypeScript enum is not supported in strip-only mode). Les compromis sont comparés sur la page enums.

Vérifier les objets de configuration avec satisfies

Annoter un objet avec un type large comme Record<string, Route> vérifie ses valeurs mais oublie ses clés. satisfies fait la même vérification et garde le type exact :

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

Utilisez une annotation quand la variable doit avoir exactement le type déclaré (un paramètre de fonction, une valeur que vous réaffecterez). Utilisez satisfies pour les tables de correspondance, les tables de routes, les tokens de thème et les autres objets constants.

Modéliser l'état avec des unions discriminées

Un objet unique avec des champs optionnels autorise des états impossibles : loading: true en même temps qu'une error, ou data absent après un succès. Une union d'objets partageant une étiquette n'autorise que les états réels, et chaque branche ne voit que ses propres champs :

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

La ligne never est la vérification d'exhaustivité. Quand quelqu'un ajoute un état et oublie de le gérer, le build casse à cette ligne :

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

L'erreur est index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. Elle nomme le cas non géré. Ajoutez case "cancelled": et le code compile.

Éviter ! et as

L'assertion non nulle x! et l'assertion de type x as T demandent au compilateur d'arrêter de vérifier. Aucune ne change la valeur à l'exécution, donc une assertion fausse devient un plantage plus tard, loin de sa cause :

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

Remplacez ! par ?., ??, un return anticipé, ou une erreur levée avec un message utile. Remplacez as par un type guard qui teste vraiment la valeur. La seule assertion toujours sûre est as const, car elle ne fait que rendre un type plus étroit et en lecture seule. Une bonne configuration de lint (les règles no-non-null-assertion et no-explicit-any de typescript-eslint) signale le reste.

Rendre les données readonly

Marquez les propriétés et les tableaux readonly quand le code ne doit pas les modifier. Le compilateur refuse alors push, sort et les affectations, et les fonctions renvoient de nouvelles valeurs au lieu de modifier leurs entrées :

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly n'est vérifié qu'à la compilation et sur un seul niveau : il ne gèle pas l'objet à l'exécution. Cela suffit pourtant à attraper la modification accidentelle d'un état partagé, qui est à l'origine de la plupart de ces bugs.