TypeScript Academy · Lección

Aserciones frente a type guards

Prefiera las comprobaciones en tiempo de ejecución a las aserciones siempre que sea posible.

Aserciones frente a type guards es una lección gratuita de TypeScript Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de TypeScript Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de TypeScript Academy incluye 4 lecciones en total.

Dos formas de convencer al compilador

Cuando el compilador no conoce el tipo exacto de un valor, tiene dos opciones: hacer una aserción (afirmar el tipo) o usar una guarda (demostrar el tipo en tiempo de ejecución). Parecen similares, pero ofrecen niveles de seguridad muy diferentes.

function viaAssert(v: unknown): number {
  return (v as number) + 1; // claim
}
function viaGuard(v: unknown): number {
  return typeof v === 'number' ? v + 1 : 0; // prove
}
console.log(viaAssert(5), viaGuard(5), viaGuard('x'));

Las aserciones no verifican

Una aserción es una promesa sin comprobación. Si se equivoca, el error llega hasta el tiempo de ejecución. Las aserciones intercambian seguridad por comodidad.

const v: unknown = 'hello';
const n = v as number;
console.log(n.toFixed(2)); // runtime error: toFixed is not a function

Las guardas de tipos verifican en tiempo de ejecución

Una guarda de tipos comprueba realmente el valor. Si la comprobación es satisfactoria, tanto usted como el compilador saben que el tipo es correcto: existe una prueba real en tiempo de ejecución que respalda el refinamiento.

function toFixed2(v: unknown): string {
  if (typeof v === 'number') return v.toFixed(2);
  return 'N/A';
}
console.log(toFixed2(3.14159), toFixed2('hi'));

Funciones de guarda de tipos personalizadas

Encapsule las comprobaciones complejas en una guarda reutilizable que devuelva value is T. Todo el código se beneficia de una única validación bien probada.

type Email = { address: string };
function isEmail(v: unknown): v is Email {
  return typeof v === 'object' && v !== null &&
    'address' in v && typeof (v as any).address === 'string';
}
console.log(isEmail({ address: 'a@b.com' }), isEmail(null));

Las guardas se combinan y reutilizan

Como las guardas son funciones normales, puede combinarlas, probarlas y reutilizarlas. En cambio, las aserciones son afirmaciones dispersas que no se pueden validar de forma centralizada.

function isString(v: unknown): v is string { return typeof v === 'string'; }
function isNonEmpty(v: unknown): v is string {
  return isString(v) && v.length > 0;
}
console.log(isNonEmpty('hi'), isNonEmpty(''));

Funciones de aserción con asserts

TypeScript también ofrece funciones de aserción. Su anotación de retorno utiliza la palabra clave asserts. Si la función retorna normalmente, el compilador refina el tipo del argumento a partir de ese punto; si la condición falla, lanza una excepción.

function assertNumber(v: unknown): asserts v is number {
  if (typeof v !== 'number') throw new Error('not a number');
}
function use(v: unknown): number {
  assertNumber(v); // after this line, v is number
  return v * 2;
}
console.log(use(21));

asserts frente a value is

Una guarda value is T devuelve un booleano sobre el que puede crear una bifurcación. Una función asserts value is T lanza una excepción si falla y refina el tipo durante el resto del ámbito. Ambas tienen respaldo en tiempo de ejecución, a diferencia de un as simple.

function assertDefined<T>(v: T): asserts v is NonNullable<T> {
  if (v === null || v === undefined) throw new Error('missing');
}
const maybe: string | null = 'ok';
assertDefined(maybe);
console.log(maybe.length); // narrowed to string

Ayudantes genéricos de aserción

Las funciones de aserción son excelentes para crear precondiciones reutilizables. Un único ayudante assert(condition) puede proteger invariantes en todo el código y lanzar una excepción de inmediato cuando se infringen.

function assert(cond: unknown, msg: string): asserts cond {
  if (!cond) throw new Error(msg);
}
function half(n: number): number {
  assert(n % 2 === 0, 'must be even');
  return n / 2;
}
console.log(half(8));

Comparación de la seguridad

De mayor a menor riesgo: las guardas de tipos y las funciones de aserción (comprobadas en tiempo de ejecución) están por encima de las aserciones simples con as (no comprobadas), que a su vez están por encima de las aserciones dobles (que inducen activamente a error). Elija la herramienta más segura que se ajuste a sus necesidades.

// Safe: guard
function safe(v: unknown) {
  return typeof v === 'string' ? v.trim() : '';
}
console.log(safe('  hi  '));

Elija la herramienta adecuada

Use una guarda de tipos cuando cree una bifurcación según el tipo. Use una función de aserción cuando deba cumplirse una precondición o la ejecución deba detenerse. Use as únicamente cuando sea imposible refinar el tipo (por ejemplo, para especializar elementos del DOM).

function getInput(v: unknown): asserts v is string {
  if (typeof v !== 'string') throw new Error('expected string');
}
const raw: unknown = 'name';
getInput(raw);
console.log(raw.toUpperCase());

Ganan las comprobaciones en tiempo de ejecución

El tema recurrente de este curso es preferir las comprobaciones en tiempo de ejecución a las aserciones. Las guardas y las funciones de aserción le proporcionan tanto tipos en tiempo de compilación como seguridad en tiempo de ejecución. Las aserciones solo proporcionan una afirmación.

function parsePort(v: unknown): number {
  if (typeof v === 'number' && Number.isInteger(v)) return v;
  throw new Error('invalid port');
}
console.log(parsePort(8080));

Comprobación rápida

Compruebe su comprensión de las aserciones y las guardas de tipos.

Repaso: aserciones frente a guardas

Ha aprendido que:

Las guardas de tipos (value is T) demuestran un tipo en tiempo de ejecución y permiten crear bifurcaciones.
Las funciones de aserción (asserts value is T) lanzan una excepción si fallan y refinan el tipo a partir de entonces.
Las aserciones simples con as solo afirman un tipo; no ofrecen seguridad en tiempo de ejecución.
Prefiera herramientas comprobadas en tiempo de ejecución y reserve las aserciones para los casos que no se puedan resolver mediante un refinamiento.

Siguiente curso: encadenamiento opcional y coalescencia nula.

function isPositive(v: unknown): v is number {
  return typeof v === 'number' && v > 0;
}
console.log(isPositive(5), isPositive(-1));

Preguntas frecuentes

¿La lección «Aserciones frente a type guards» es gratis?

Sí — el texto completo de «Aserciones frente a type guards» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de TypeScript Academy, actualiza a CoddyKit PRO. El curso de TypeScript Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Aserciones frente a type guards»?

Prefiera las comprobaciones en tiempo de ejecución a las aserciones siempre que sea posible. Practicas TypeScript Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar TypeScript Academy?

No se requiere experiencia previa. TypeScript Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Aserciones frente a type guards»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de TypeScript Academy?

Sí. Cada lección de TypeScript Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

La palabra clave as para aserciones de tipos
Operador de aserción de no nulo
Aserciones dobles y sus riesgos
Aserciones frente a type guards

← Volver a TypeScript Academy