Estrechamiento de tipos en TypeScript: el análisis de flujo

El estrechamiento de tipos (type narrowing) es TypeScript deduciendo un tipo más concreto para un valor en un punto determinado del código, a partir de las comprobaciones que el código ya ha hecho. Un parámetro string | number pasa a ser string dentro de if (typeof x === "string") y number en el 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]

Llamar a value.toFixed(2) antes de la comprobación sería un error de compilación, porque toFixed no existe en string. La comprobación es JavaScript normal y se ejecuta en tiempo de ejecución; el estrechamiento es el compilador leyéndola y ajustando el tipo. No se genera nada extra.

Análisis de flujo de control

TypeScript sigue cada camino de una función: if/else, los return y throw tempranos, switch, los bucles y los operadores de cortocircuito &&, ||, ?? y ?:. En cada punto, el tipo de una variable es lo que todavía es posible ahí.

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

El estilo del return temprano («cláusulas de guarda») es la forma más legible de estrechar: maneja primero los casos raros y el resto de la función trabaja con el tipo limpio.

Todas las formas de estrechar

Las tres últimas se explican en las páginas de type guards y uniones discriminadas. El resto está a continuación.

Estrechamiento por veracidad

if (x) quita null y undefined (y los tipos literales false, 0 y ""). Es corto, y tiene una trampa clásica: 0 y "" son falsy, así que valores válidos se tratan como si faltaran.

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

Con números y strings, compara con undefined o null de forma explícita (o usa ??). La veracidad está bien para objetos, arrays y funciones, que nunca son falsy.

Estrechamiento por igualdad

===, !==, == y != estrechan los dos lados. Comparar con un literal estrecha a ese literal; == null (igualdad laxa) cubre null y undefined en una sola comprobación, y es el único sitio donde la igualdad laxa es idiomática.

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

Comparar dos variables estrecha ambas a lo que podrían tener en común: si a: string | number y b: string | boolean pasan a === b, las dos son string dentro del if.

El operador in

"key" in obj estrecha una unión de tipos objeto a los miembros que tienen (o pueden tener) esa propiedad.

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 también funciona sobre unknown una vez que sabes que es un objeto: tras typeof v === "object" && v !== null && "id" in v, TypeScript sabe que v tiene una propiedad id de tipo unknown. Para las uniones que diseñas tú, una propiedad etiqueta compartida (kind: "fish") es más clara que buscar métodos: ese patrón se llama unión discriminada.

Estrechamiento por asignación

Una variable tiene un tipo declarado y un tipo estrechado que sigue a sus asignaciones. Asignar un valor la estrecha al tipo de ese valor, dentro de los límites del tipo declarado.

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

Cuándo se pierde el estrechamiento

El estrechamiento es local y conservador. Hay algunas situaciones que lo anulan:

• Una expresión distinta. Comprobar obj.name estrecha obj.name (y obj["name"]), pero no obj[key] cuando key es una variable string en lugar de un literal, ni una copia hecha antes de la comprobación.
• Callbacks y reasignación. Dentro de un callback, un let estrechado solo mantiene el estrechamiento si no se vuelve a asignar después de crear el callback. Una const o un parámetro que nunca se reasigna sigue estrechado.
• Comprobaciones escondidas en funciones auxiliares. Una función isString(x: unknown): boolean no le dice nada al compilador. Dale un predicado de tipo como tipo de retorno, x is string, y las llamadas a ella estrecharán igual que 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);

El compilador informa index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. El callback podría ejecutarse más tarde, después de x = undefined. Borra esa última asignación (o copia el valor en una const dentro del if) y compila e imprime 5 dos veces.

Una función auxiliar que devuelve boolean se arregla declarando lo que demuestra. Eso es un type guard:

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

Desde TypeScript 5.5 el compilador infiere esos predicados para funciones flecha sencillas, y por eso list.filter((x) => x !== undefined) devuelve ahora un array sin undefined.