L'opérateur satisfies en TypeScript : face aux annotations et à as

value satisfies Type vérifie à la compilation que value correspond à Type, puis laisse tranquille le type propre, plus précis, de la valeur. Une annotation remplacerait ce type précis par Type ; satisfies valide sans élargir.

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 fait tout de même la vérification : une couleur manquante, une clé mal orthographiée comme bleu, ou une valeur comme true est une erreur de compilation sur cette ligne. Il existe depuis TypeScript 4.9 et, comme toute annotation de type, il est retiré du JavaScript émis.

Le problème que résout satisfies

Avec une annotation de type, le type de la variable est l'annotation. Le compilateur oublie ce qu'il a vu dans le littéral. Ici, la même palette est annotée à la place, et TypeScript ne sait plus que green est une chaîne :

// 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());

Le compilateur signale :

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

Avant TypeScript 4.9, les choix étaient : annoter et affiner à la main partout (typeof palette.green === "string"), ou renoncer à l'annotation et perdre la vérification. satisfies donne les deux. Remplacez : Record<ColorName, Color> par satisfies Record<ColorName, Color> après l'accolade fermante et le code s'exécute.

satisfies, annotation de type ou as

Le même objet de réglages, écrit de trois façons :

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 a laissé passer le lang manquant, et asserted.lang vaut undefined à l'exécution alors que son type indique string. Retirez lang des deux autres lignes et toutes deux échouent avec TS2741, Property 'lang' is missing in type ....

Règle empirique : annotez quand vous voulez que la variable ait le type déclaré (une valeur que vous réassignerez, une API publique), et utilisez satisfies quand vous voulez une vérification mais que le type propre de la valeur est plus utile.

Détecter les erreurs dans les littéraux objet

satisfies exécute la vérification d'assignabilité complète, y compris la vérification des propriétés en trop : les fautes de frappe dans les clés sont donc des erreurs.

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 vérification donne aussi au littéral un type contextuel, comme le fait une annotation. Cela compte de deux façons. Les littéraux de chaîne sont conservés comme types littéraux quand le type cible les attend : { path: "/", method: "GET" } satisfies Route a method: "GET", alors que le même objet sans annotation inférerait method: string. Et les paramètres des callbacks sont inférés à partir du type cible :

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

Les clés d'un Record restent connues

Un usage courant est la table de correspondance. Annotée Record<string, T>, toute chaîne est une clé valide et une faute de frappe compile, en renvoyant undefined à l'exécution. Avec satisfies, les valeurs sont toujours vérifiées par rapport à T, mais le type de la variable liste exactement les clés que vous avez écrites :

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 n'est utile que parce que les clés ont survécu. Avec l'annotation, ce serait un simple string.

Pour exiger un ensemble de clés fixe, satisfaites un Record sur une union : satisfies Record<"dev" | "prod", string> signale un prod manquant avec TS2741 et un staging inconnu avec TS2353.

as const satisfies

as const et satisfies se combinent. Écrivez as const en premier : il rend la valeur readonly en profondeur avec des types littéraux, puis satisfies vérifie cette valeur exacte.

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' ]

Chaque route est vérifiée par rapport à Route (un method: "PUT" serait une erreur), et le tuple de types littéraux reste disponible : Path est donc une union des vrais chemins. Utilisez readonly Route[] (ou ReadonlyArray<Route>) comme cible, puisqu'un tableau as const est readonly.

Objets de configuration

La configuration, c'est là que satisfies se rend indispensable : la forme doit être juste, et le code ailleurs a besoin des valeurs précises.

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

Oubliez l'entrée production, faites une faute dans logLevel, ou écrivez logLevel: "verbose", et le compilateur désigne la ligne exacte. Le même motif convient aux fichiers *.config.ts : export default { ... } satisfies SomeConfig vérifie tout le fichier tandis que l'objet exporté garde ses valeurs littérales.

Quand ne pas utiliser satisfies

• La variable sera réassignée. let cfg = { port: 3000 } satisfies { port: number | string } donne à cfg le type { port: number }, donc un cfg = { port: "80" } ultérieur échoue (TS2322). Annotez les variables que vous comptez modifier.
• Vous voulez volontairement le type déclaré. Pour la valeur de retour d'une fonction ou une constante exportée qui fait partie d'une API, le type de l'annotation est le contrat, et exposer le type littéral exact peut rendre les changements ultérieurs cassants.
• La valeur n'est pas un littéral. satisfies brille sur les littéraux d'objets et de tableaux. Sur une variable ou le résultat d'un appel, c'est une simple vérification d'assignabilité, ce qu'une annotation vous donne déjà.