El operador satisfies en TypeScript: frente a anotaciones y as

value satisfies Type comprueba en tiempo de compilación que value encaja con Type, y después deja en paz el tipo propio del valor, más preciso. Una anotación sustituiría ese tipo preciso por Type; satisfies valida sin ensanchar.

type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Record<ColorName, Color>;

// Checked against the Record, yet every property keeps its own type:
console.log(palette.green.toUpperCase());      // #00FF00 (green: string)
console.log(palette.red.map((c) => c / 255));  // [ 1, 0, 0 ] (red: [number, number, number])

satisfies sigue haciendo la comprobación: un color que falta, una clave mal escrita como bleu o un valor como true son un error de compilación en esa línea. Existe desde TypeScript 4.9 y, como todas las anotaciones de tipo, se elimina del JavaScript generado.

El problema que resuelve satisfies

Con una anotación de tipo, el tipo de la variable es la anotación. El compilador olvida lo que vio en el literal. Aquí la misma paleta está anotada, y ahora TypeScript ya no sabe que green es un string:

// This does not compile: the annotation widens every property to Color.
type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette: Record<ColorName, Color> = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
};

console.log(palette.green.toUpperCase());

El compilador informa:

index.ts(11,27): error TS2339: Property 'toUpperCase' does not exist on type 'Color'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.

Antes de TypeScript 4.9 las opciones eran: anotar y estrechar a mano en todas partes (typeof palette.green === "string"), o prescindir de la anotación y perder la comprobación. satisfies da las dos cosas. Cambia : Record<ColorName, Color> por satisfies Record<ColorName, Color> después de la llave de cierre y se ejecuta.

satisfies frente a anotación de tipo y as

El mismo objeto de configuración, escrito de tres formas:

type Settings = {
  theme: "light" | "dark";
  fontSize: number;
  lang: string;
};

const annotated: Settings = { theme: "dark", fontSize: 14, lang: "en" };
const asserted = { theme: "dark", fontSize: 14 } as Settings; // lang is missing!
const satisfied = { theme: "dark", fontSize: 14, lang: "en" } satisfies Settings;

// annotated.theme: "light" | "dark"   (the annotation's type)
// satisfied.theme: "dark"             (what was actually written)
const isDark: "dark" = satisfied.theme; // fine; annotated.theme would be rejected

console.log(annotated.lang, asserted.lang, satisfied.lang); // en undefined en
console.log(isDark);                                         // dark

as dejó pasar la falta de lang, y asserted.lang es undefined en tiempo de ejecución aunque su tipo diga string. Quita lang de las otras dos líneas y ambas fallan con TS2741, Property 'lang' is missing in type ....

Regla práctica: anota cuando quieras que la variable tenga el tipo declarado (un valor que vas a reasignar, una API pública), y usa satisfies cuando quieras una comprobación pero el tipo propio del valor sea más útil.

Detectar errores en objetos literales

satisfies hace la comprobación de asignabilidad completa, incluida la de propiedades de más, así que las erratas en las claves son errores:

type Route = { path: string; method: "GET" | "POST" };

const home = { path: "/", metod: "GET" } satisfies Route;
// error TS2561: Object literal may only specify known properties, but 'metod' does not exist in type 'Route'. Did you mean to write 'method'?

La comprobación también da al literal un tipo contextual, igual que una anotación. Eso importa de dos maneras. Los literales de string se conservan como tipos literales cuando el tipo destino los espera: { path: "/", method: "GET" } satisfies Route tiene method: "GET", mientras que el mismo objeto sin anotación inferiría method: string. Y los parámetros de los callbacks se infieren a partir del tipo destino:

type Handlers = {
  onSave: (doc: { id: number; title: string }) => string;
  onDelete: (id: number) => boolean;
};

const handlers = {
  onSave: (doc) => `saved #${doc.id}: ${doc.title}`, // doc is typed from Handlers
  onDelete: (id) => id > 0,
} satisfies Handlers;

console.log(handlers.onSave({ id: 7, title: "Notes" })); // saved #7: Notes
console.log(handlers.onDelete(-1));                      // false

Las claves de Record siguen siendo conocidas

Un uso habitual es una tabla de búsqueda. Anotada como Record<string, T>, cualquier string es una clave válida y una errata compila, devolviendo undefined en tiempo de ejecución. Con satisfies, los valores se siguen comprobando contra T, pero el tipo de la variable enumera exactamente las claves que escribiste:

type Endpoint = { url: string; timeoutMs: number };

const loose: Record<string, Endpoint> = {
  users: { url: "/api/users", timeoutMs: 3000 },
};

const endpoints = {
  users: { url: "/api/users", timeoutMs: 3000 },
  orders: { url: "/api/orders", timeoutMs: 8000 },
} satisfies Record<string, Endpoint>;

console.log(loose.userz?.url); // undefined: the typo compiles
console.log(endpoints.orders.timeoutMs); // 8000

type EndpointName = keyof typeof endpoints; // "users" | "orders"
const endpointName: EndpointName = "users";
console.log(endpoints[endpointName].url); // /api/users

// @ts-expect-error: TS2551 Property 'userz' does not exist on type ... Did you mean 'users'?
endpoints.userz;

keyof typeof endpoints solo es útil porque las claves sobrevivieron. Con la anotación sería simplemente string.

Para exigir un conjunto fijo de claves, usa satisfies con un Record sobre una unión: satisfies Record<"dev" | "prod", string> informa de un prod que falta con TS2741 y de un staging desconocido con TS2353.

as const satisfies

as const y satisfies se combinan. Escribe as const primero: hace el valor readonly en profundidad con tipos literales, y después satisfies comprueba ese valor exacto.

type Route = { path: string; method: "GET" | "POST"; auth: boolean };

const routes = [
  { path: "/", method: "GET", auth: false },
  { path: "/login", method: "POST", auth: false },
  { path: "/account", method: "GET", auth: true },
] as const satisfies readonly Route[];

type Path = (typeof routes)[number]["path"]; // "/" | "/login" | "/account"

function link(path: Path): string {
  return `<a href="${path}">`;
}

console.log(link("/account"));                           // <a href="/account">
console.log(routes.filter((r) => r.auth).map((r) => r.path)); // [ '/account' ]

Cada ruta se comprueba contra Route (un method: "PUT" sería un error), y la tupla de tipos literales sigue disponible, así que Path es una unión de las rutas reales. Usa readonly Route[] (o ReadonlyArray<Route>) como destino, ya que un array as const es readonly.

Objetos de configuración

La configuración es donde satisfies se gana su sitio: la forma tiene que ser correcta, y el código de otras partes quiere los valores precisos.

type Env = "development" | "production";

type AppConfig = {
  port: number;
  logLevel: "debug" | "info" | "warn";
  features: Record<string, boolean>;
};

const configs = {
  development: { port: 3000, logLevel: "debug", features: { newCheckout: true } },
  production: { port: 8080, logLevel: "warn", features: { newCheckout: false } },
} satisfies Record<Env, AppConfig>;

function start(env: Env): string {
  const c = configs[env];
  return `${env}: port ${c.port}, log ${c.logLevel}, newCheckout=${c.features.newCheckout}`;
}

console.log(start("development")); // development: port 3000, log debug, newCheckout=true
console.log(start("production"));  // production: port 8080, log warn, newCheckout=false

Olvida la entrada production, escribe mal logLevel o pon logLevel: "verbose", y el compilador señala la línea exacta. El mismo patrón sirve para los archivos *.config.ts: export default { ... } satisfies SomeConfig comprueba todo el archivo mientras el objeto exportado conserva sus valores literales.

Cuándo no usar satisfies

• La variable se va a reasignar. let cfg = { port: 3000 } satisfies { port: number | string } da a cfg el tipo { port: number }, así que un cfg = { port: "80" } posterior falla (TS2322). Anota las variables que piensas cambiar.
• Quieres a propósito el tipo declarado. Para el valor de retorno de una función o una constante exportada que forma parte de una API, el tipo de la anotación es el contrato, y filtrar el tipo literal exacto puede hacer que cambios posteriores rompan cosas.
• El valor no es un literal. satisfies brilla con objetos y arrays literales. Sobre una variable o el resultado de una llamada es una simple comprobación de asignabilidad, que ya te da una anotación.