as en TypeScript: aserciones de tipo y casting

value as Type es una aserción de tipo: le dice a TypeScript que trate value como Type. La gente lo llama cast, pero es solo una instrucción para el compilador. Se borra de la salida en JavaScript, no convierte nada y no comprueba nada en tiempo de ejecución.

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

Este es el uso típico: sabes más sobre un valor de lo que puede saber el compilador (aquí, la forma de un JSON), y lo dices. Si te equivocas, nada te avisa. Las siguientes secciones muestran qué significa eso y cuándo es mejor una comprobación en tiempo de ejecución.

as y la sintaxis de corchetes angulares

Hay dos formas de escribir la misma aserción:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

La forma con corchetes angulares no está permitida en archivos .tsx, donde <string> se leería como una etiqueta JSX. Usa as en todas partes y la cuestión nunca aparece. Las aserciones tienen poca precedencia, así que envuélvelas en paréntesis cuando continúes la expresión: (value as string).length.

Las aserciones no convierten valores

Esta es la parte que causa bugs reales. Una aserción cambia lo que el compilador cree sobre un valor, no el valor en sí:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

El compilador cree que asserted es un number, así que asserted + 1 se comprueba como aritmética. En tiempo de ejecución sigue siendo el string "42" y JavaScript concatena. Para cambiar el tipo de un valor, conviértelo: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). La página de string a número compara las funciones de conversión.

Qué permite el compilador

as no es ilimitado. TypeScript permite x as T cuando uno de los tipos se puede asignar al otro: ensanchar ("a" as string, dog as Animal) y estrechar (animal as Dog, unknown as User) están permitidos. Cuando los tipos no se solapan en absoluto, lo rechaza:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

El compilador informa index.ts(3,11): error TS2352: Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. El propio mensaje nombra la escapatoria: input as unknown as number. Esa aserción doble compila, y en tiempo de ejecución es exactamente igual de errónea que el ejemplo de arriba. Cuando sientas que la necesitas, la solución correcta suele ser una conversión (Number(input)) o un tipo distinto.

La regla del solapamiento es laxa con los objetos. Se acepta un objeto literal que tenga algunas de las propiedades, y así es como as deja pasar sin avisar objetos incompletos:

interface User {
  name: string;
  email: string;
}

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

Una anotación (const draft: User = { name: "Ada" }) o satisfies User informaría de que falta email (TS2741). Usa as sobre un objeto literal solo cuando de verdad pienses completarlo más tarde, y es preferible construir el objeto completo.

as const es distinto

as const parece una aserción pero hace lo contrario de relajar: hace que un literal sea lo más estrecho posible. Los strings se quedan como tipos literales, los arrays pasan a ser tuplas readonly y las propiedades de los objetos pasan a ser readonly.

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

Es seguro, porque describe el literal con exactitud en lugar de afirmar algo que el compilador no puede ver. (El sizes as readonly string[] dentro de isSize es una aserción que ensancha, también segura: permite que includes acepte cualquier string). Consulta tipos literales para saber más.

Cuándo es mejor un type guard

as es una afirmación; un type guard es una comprobación. En una frontera por la que entran datos de fuera de tu código (JSON, fetch, localStorage, la entrada del usuario, un mensaje), la afirmación puede ser falsa, y una aserción convierte un error claro en la frontera en uno confuso en otro sitio.

interface Point {
  x: number;
  y: number;
}

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

Una guía aproximada de las herramientas que se parecen:

Quedan dos buenos usos de as: estrechar algo que el compilador no puede seguir (una entrada de un Map que asignaste dos líneas antes, un valor de una librería sin tipos), y el código de tests que construye fixtures parciales. Mantenlos pequeños y cerca del lugar donde sabes que la afirmación es cierta.