null et undefined en TypeScript : vérifications, ?. et ??

Avec strictNullChecks activé (l'option fait partie de strict), null et undefined sont des types à part entière. Un string ne peut jamais valoir null ; une valeur qui peut manquer doit l'indiquer dans son type, comme string | null, et TypeScript vous oblige à traiter ce cas avant d'utiliser la valeur.

function initials(name: string | null | undefined): string {
  if (name == null) return "?"; // handles both null and undefined
  return name
    .split(" ")
    .map((part) => part[0])
    .join("");
}

console.log(initials("Ada Lovelace")); // AL
console.log(initials(null));           // ?
console.log(initials(undefined));      // ?

Après la vérification, le compilateur sait que name est un string, donc .split est autorisé. La suite de cette page présente les façons de faire cette vérification et les opérateurs qui la raccourcissent.

strictNullChecks et les erreurs « possibly null »

Quand un type inclut null ou undefined, TypeScript refuse d'utiliser la valeur comme si elle était toujours présente :

// This does not compile: name may be null
function greet(name: string | null) {
  return "Hello, " + name.toUpperCase();
}

console.log(greet("ada"));

index.ts(3,22): error TS18047: 'name' is possibly 'null'.

La version undefined est TS18048, 'x' is possibly 'undefined'. Sans strictNullChecks, null et undefined sont autorisés dans tous les types : ce code compile, puis plante à l'exécution avec une TypeError la première fois que name vaut null. Cette catégorie de bugs est la principale raison de garder strict activé.

D'où viennent ces types dans le code de tous les jours :

Vérifier null et undefined

Chaque vérification ci-dessous affine le type dans le bloc. Choisissez celle qui correspond à ce que vous voulez exclure.

function label(value: string | null | undefined): string {
  if (value === undefined) return "undefined";
  if (value === null) return "null";
  return value.toUpperCase(); // value is string here
}

function orNone(value: string | null | undefined): string {
  if (value == null) return "(none)"; // == null matches null AND undefined
  return `"${value}"`;
}

console.log(label(undefined), label(null), label("ok")); // undefined null OK
console.log(orNone(null), orNone(undefined), orNone("")); // (none) (none) ""

== null est le seul endroit où l'égalité large est idiomatique : elle est vraie exactement pour null et undefined, rien d'autre. Un test de véracité aurait traité la chaîne vide comme absente, ce qui est souvent un bug.

Le chaînage optionnel : ?.

a?.b lit b si a ne vaut ni null ni undefined, et sinon s'arrête et renvoie undefined. Le même opérateur fonctionne pour les indices, a?.[i], et pour les appels, fn?.().

interface User {
  name: string;
  address?: { city: string; zip?: string };
  tags?: string[];
  onLogin?: () => string;
}

const ada: User = { name: "Ada", address: { city: "London" }, onLogin: () => "welcome" };
const bob: User = { name: "Bob" };

console.log(ada.address?.city);        // London
console.log(bob.address?.city);        // undefined
console.log(ada.address?.zip?.length); // undefined
console.log(bob.tags?.[0]);            // undefined
console.log(ada.onLogin?.());          // welcome
console.log(bob.onLogin?.());          // undefined

Le type de bob.address?.city est string | undefined : le chaînage optionnel ajoute undefined au résultat, on l'associe donc en général à ??. Le comportement à l'exécution est du JavaScript pur ; voir chaînage optionnel pour le détail du court-circuit.

Le double point d'interrogation : ??

a ?? b renvoie a sauf s'il vaut null ou undefined, auquel cas il renvoie b. Il remplace l'ancien idiome a || b, qui écarte aussi 0, "", false et NaN :

function pageSize(input: number | undefined): string {
  const withOr = input || 20;      // 0 is falsy, so it is replaced
  const withNullish = input ?? 20; // only undefined is replaced
  return `${withOr} vs ${withNullish}`;
}

console.log(pageSize(undefined)); // 20 vs 20
console.log(pageSize(0));         // 20 vs 0

const scores = new Map([["Ada", 90]]);
const score: number = scores.get("Linus") ?? 0; // number | undefined becomes number
console.log(score);                             // 0

Côté types, ?? retire null et undefined du côté gauche et fait l'union du reste avec le côté droit, c'est pourquoi scores.get("Linus") ?? 0 peut être assigné à un number.

L'assignation nullish : ??=

a ??= b assigne b à a uniquement quand a vaut null ou undefined. Ses cousins ||= et &&= assignent quand le côté gauche est falsy ou truthy.

interface Options {
  retries?: number;
  label?: string;
}

function withDefaults(opts: Options) {
  opts.retries ??= 3;   // assign only if null or undefined
  opts.label ||= "job"; // assign if falsy, so "" is replaced too
  return opts;
}

console.log(withDefaults({}));                       // { retries: 3, label: 'job' }
console.log(withDefaults({ retries: 0, label: "" })); // { retries: 0, label: 'job' }

retries: 0 survit à ??=, alors que le label vide est remplacé par ||=. Après opts.retries ??= 3, TypeScript affine opts.retries en number pour le reste de la fonction.

Propriétés optionnelles ou | undefined

nickname?: string et nickname: string | undefined se lisent de la même façon, mais diffèrent sur l'obligation de présence de la clé :

interface WithOptional { nickname?: string }            // key may be missing
interface WithUndefined { nickname: string | undefined } // key must be present

const a: WithOptional = {};
const b: WithUndefined = { nickname: undefined };

// @ts-expect-error: Property 'nickname' is missing in type '{}' but required in type 'WithUndefined'.
const c: WithUndefined = {};

console.log("nickname" in a, "nickname" in b); // false true
console.log(a.nickname === b.nickname);        // true: both read as undefined

Utilisez ? quand les appelants peuvent omettre la propriété, et | undefined quand vous voulez que chaque appelant la passe explicitement, même si la valeur est undefined. L'option exactOptionalPropertyTypes (qui ne fait pas partie de strict) resserre encore ? : nickname?: string refuse alors { nickname: undefined } et n'accepte qu'une clé absente ou une chaîne. Les paramètres de fonction optionnels (x?: number) se comportent comme les propriétés optionnelles : dans la fonction, x est number | undefined.

null ou undefined : lequel utiliser

TypeScript n'impose pas de choix, mais mélanger les deux dans une base de code oblige chaque vérification à traiter deux cas. Une convention courante :

• Utilisez undefined (et les propriétés optionnelles) pour « non défini » dans vos propres types. C'est ce que produit JavaScript par défaut : propriétés absentes, arguments omis, échecs de find et de Map.get.
• Acceptez null là où une API vous le fournit : JSON n'a pas de undefined, String.prototype.match et de nombreuses méthodes du DOM renvoient null.
• Vérifiez avec == null quand une valeur peut être l'un ou l'autre.

L'accès aux tableaux par indice est la seule lacune : users[5] est typé comme le type des éléments même quand l'indice est hors limites. L'option noUncheckedIndexedAccess (qui ne fait pas partie de strict) ajoute | undefined à chaque accès par indice pour que le compilateur détecte aussi ce cas.