Zawężanie typów w TypeScript: jak działa control flow

Zawężanie typów to ustalanie przez TypeScript bardziej konkretnego typu wartości w danym miejscu kodu na podstawie sprawdzeń, które kod już wykonał. Parametr string | number staje się string wewnątrz if (typeof x === "string") i number w 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]

Wywołanie value.toFixed(2) przed sprawdzeniem byłoby błędem kompilacji, bo toFixed nie istnieje w string. Sprawdzenie to zwykły JavaScript wykonywany w czasie działania programu, a zawężanie to kompilator, który je odczytuje i dopasowuje typ. Nic dodatkowego nie jest emitowane.

Analiza przepływu sterowania

TypeScript śledzi każdą ścieżkę przez funkcję: if/else, wczesne return i throw, switch, pętle oraz operatory skrócone &&, ||, ?? i ?:. W każdym miejscu typ zmiennej to to, co nadal jest tam możliwe.

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

Styl z wczesnym return ("guard clauses") to najczytelniejszy sposób zawężania: najpierw obsłuż nietypowe przypadki, a reszta funkcji pracuje na czystym typie.

Wszystkie sposoby zawężania

Ostatnie trzy omawiają strony o type guards i discriminated unions. Pozostałe są opisane niżej.

Zawężanie przez truthiness

if (x) usuwa null i undefined (oraz typy literałów false, 0, ""). Jest krótkie i ma jedną klasyczną pułapkę: 0 i "" są falsy, więc poprawne wartości są traktowane jak brakujące.

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

Liczby i stringi porównuj jawnie z undefined albo null (albo użyj ??). Truthiness sprawdza się dla obiektów, tablic i funkcji, które nigdy nie są falsy.

Zawężanie przez równość

===, !==, == i != zawężają obie strony. Porównanie z literałem zawęża do tego literału. == null (luźna równość) dopasowuje w jednym sprawdzeniu zarówno null, jak i undefined i to jedyne miejsce, gdzie luźna równość jest idiomatyczna.

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

Porównanie dwóch zmiennych zawęża obie do tego, co mogą mieć wspólnego: jeśli a: string | number i b: string | boolean przejdą a === b, obie mają w if typ string.

Operator in

"key" in obj zawęża unię typów obiektów do tych elementów, które mają (albo mogą mieć) tę właściwość.

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 działa też na unknown, gdy wiesz już, że to obiekt: po typeof v === "object" && v !== null && "id" in v TypeScript wie, że v ma właściwość id typu unknown. W uniach, które projektujesz sam, wspólna właściwość-znacznik (kind: "fish") jest czytelniejsza niż sprawdzanie metod: ten wzorzec to discriminated union.

Zawężanie przez przypisanie

Zmienna ma typ zadeklarowany i typ zawężony, który podąża za jej przypisaniami. Przypisanie wartości zawęża zmienną do typu tej wartości, w granicach typu zadeklarowanego.

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

Gdzie zawężanie ginie

Zawężanie jest lokalne i ostrożne. Kilka sytuacji je resetuje:

• Inne wyrażenie. Sprawdzenie obj.name zawęża obj.name (i obj["name"]), ale nie obj[key], gdy key to zmienna typu string, a nie literał, i nie kopię zrobioną przed sprawdzeniem.
• Callbacki i ponowne przypisanie. W callbacku zawężona zmienna let zachowuje zawężenie tylko wtedy, gdy po utworzeniu callbacka nie dostaje nowej wartości. const albo parametr, któremu nigdy nie przypisuje się nowej wartości, pozostaje zawężony.
• Sprawdzenia ukryte w funkcjach pomocniczych. Funkcja isString(x: unknown): boolean nic nie mówi kompilatorowi. Nadaj jej typ zwracany w postaci predykatu typu, x is string, a jej wywołania będą zawężać tak jak 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);

Kompilator zgłasza index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. Callback mógłby się wykonać później, po x = undefined. Usuń to ostatnie przypisanie (albo skopiuj wartość do const wewnątrz if), a kod się skompiluje i dwa razy wypisze 5.

Funkcję pomocniczą, która zwraca boolean, można naprawić, deklarując, czego dowodzi. Tym właśnie jest type guard:

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

Od TypeScript 5.5 kompilator wnioskuje takie predykaty dla prostych funkcji strzałkowych, dlatego list.filter((x) => x !== undefined) zwraca teraz tablicę bez undefined.