Narrowing en TypeScript : comment fonctionne l'analyse du flux

Le narrowing, c'est TypeScript qui détermine un type plus précis pour une valeur à un endroit donné du code, à partir des vérifications que le code a déjà faites. Un paramètre string | number devient string dans if (typeof x === "string") et number dans le else.

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

Appeler value.toFixed(2) avant la vérification serait une erreur de compilation, car toFixed n'existe pas sur string. La vérification est du JavaScript ordinaire et s'exécute ; le narrowing, c'est le compilateur qui la lit et ajuste le type. Rien de plus n'est émis.

L'analyse du flux de contrôle

TypeScript suit chaque chemin d'une fonction : if/else, les return et throw anticipés, switch, les boucles, et les opérateurs de court-circuit &&, ||, ?? et ?:. À chaque endroit, le type d'une variable est ce qui y reste possible.

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

Le style à return anticipé (les « guard clauses ») est la façon la plus lisible d'affiner : traitez d'abord les cas particuliers, et le reste de la fonction travaille avec le type propre.

Toutes les façons d'affiner

Les trois dernières sont traitées sur les pages type guards et unions discriminées. Les autres sont présentées ci-dessous.

Narrowing par véracité

if (x) retire null et undefined (ainsi que les types littéraux false, 0, ""). C'est court, avec un piège classique : 0 et "" sont falsy, donc des valeurs valides sont traitées comme absentes.

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

Pour les nombres et les chaînes, comparez explicitement à undefined ou null (ou utilisez ??). La véracité convient aux objets, aux tableaux et aux fonctions, qui ne sont jamais falsy.

Narrowing par égalité

===, !==, == et != affinent les deux côtés. Comparer à un littéral affine vers ce littéral ; == null (égalité large) correspond à la fois à null et à undefined en une seule vérification, et c'est le seul endroit où l'égalité large est idiomatique.

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

Comparer deux variables les affine toutes deux vers ce qu'elles peuvent avoir en commun : si a: string | number et b: string | boolean passent a === b, les deux sont string dans le if.

L'opérateur in

"key" in obj affine une union de types objet vers les membres qui ont (ou peuvent avoir) cette propriété.

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

in fonctionne aussi sur unknown une fois que vous savez que c'est un objet : après typeof v === "object" && v !== null && "id" in v, TypeScript sait que v possède une propriété id de type unknown. Pour les unions que vous concevez vous-même, une propriété étiquette commune (kind: "fish") est plus claire que de sonder la présence de méthodes : ce motif s'appelle une union discriminée.

Narrowing par assignation

Une variable a un type déclaré, et un type affiné qui suit ses assignations. Assigner une valeur l'affine vers le type de cette valeur, dans la limite du type déclaré.

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

Quand l'affinage se perd

Le narrowing est local et prudent. Quelques situations le réinitialisent :

• Une autre expression. Vérifier obj.name affine obj.name (et obj["name"]), mais pas obj[key] quand key est une variable string et non un littéral, ni une copie faite avant la vérification.
• Callbacks et réassignation. Dans un callback, une let affinée ne garde son affinage que si elle n'est pas réassignée après la création du callback. Une const, ou un paramètre jamais réassigné, reste affiné.
• Vérifications cachées dans des helpers. Une fonction isString(x: unknown): boolean n'apprend rien au compilateur. Donnez-lui un type de retour prédicat, x is string, et ses appels affineront comme le fait typeof.

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

Le compilateur signale index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. Le callback pourrait s'exécuter plus tard, après x = undefined. Supprimez cette dernière assignation (ou copiez la valeur dans une const à l'intérieur du if) et le code compile et affiche 5 deux fois.

Un helper qui renvoie boolean se corrige en déclarant ce qu'il prouve. C'est cela, un type guard :

function isString(value: unknown): value is string {
  return typeof value === "string";
}

Depuis TypeScript 5.5, le compilateur infère de tels prédicats pour les fonctions fléchées simples, c'est pourquoi list.filter((x) => x !== undefined) renvoie désormais un tableau sans undefined.