TypeScript satisfies: vs Typannotation und as

value satisfies Type prüft beim Kompilieren, dass value zu Type passt, und lässt dann den eigenen, genaueren Typ des Werts in Ruhe. Eine Annotation würde diesen genauen Typ durch Type ersetzen; satisfies validiert, ohne zu erweitern.

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 prüft trotzdem: Eine fehlende Farbe, ein falsch geschriebener Schlüssel wie bleu oder ein Wert wie true ist in dieser Zeile ein Compilerfehler. Es gibt satisfies seit TypeScript 4.9, und wie jede Typannotation wird es aus dem erzeugten JavaScript entfernt.

Das Problem, das satisfies löst

Mit einer Typannotation ist der Typ der Variablen die Annotation. Der Compiler vergisst, was er im Literal gesehen hat. Hier wird dieselbe Palette stattdessen annotiert, und nun weiß TypeScript nicht mehr, dass green ein String ist:

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

Der Compiler meldet:

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

Vor TypeScript 4.9 blieb die Wahl: annotieren und überall von Hand einengen (typeof palette.green === "string") oder die Annotation weglassen und die Prüfung verlieren. satisfies bietet beides. Ändere : Record<ColorName, Color> zu satisfies Record<ColorName, Color> hinter der schließenden geschweiften Klammer, und es läuft.

satisfies vs Typannotation vs as

Dasselbe Einstellungsobjekt, auf drei Arten geschrieben:

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 hat das fehlende lang durchgelassen, und asserted.lang ist zur Laufzeit undefined, während sein Typ string sagt. Entferne lang aus den anderen beiden Zeilen, und beide scheitern mit TS2741, Property 'lang' is missing in type ....

Faustregel: Annotiere, wenn die Variable den deklarierten Typ haben soll (ein Wert, den du neu zuweist, eine öffentliche API), und nimm satisfies, wenn du eine Prüfung willst, der eigene Typ des Werts aber nützlicher ist.

Fehler in Objektliteralen finden

satisfies führt die vollständige Prüfung auf Zuweisbarkeit durch, einschließlich Excess Property Checks, Tippfehler in Schlüsseln sind also Fehler:

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

Die Prüfung gibt dem Literal auch einen kontextuellen Typ, genau wie eine Annotation. Das zählt in zweierlei Hinsicht. String-Literale bleiben Literaltypen, wenn der Zieltyp sie erwartet: { path: "/", method: "GET" } satisfies Route hat method: "GET", während dasselbe Objekt ohne Annotation method: string ableiten würde. Und Callback-Parameter werden aus dem Zieltyp abgeleitet:

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

Record-Schlüssel bleiben bekannt

Ein häufiger Einsatz ist eine Lookup-Tabelle. Als Record<string, T> annotiert ist jeder String ein gültiger Schlüssel, und ein Tippfehler kompiliert und liefert zur Laufzeit undefined. Mit satisfies werden die Werte weiterhin gegen T geprüft, aber der Typ der Variablen führt genau die Schlüssel auf, die du geschrieben hast:

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 ist nur nützlich, weil die Schlüssel erhalten geblieben sind. Mit der Annotation wäre es einfach string.

Um eine feste Menge von Schlüsseln zu verlangen, erfülle einen Record über eine Union: satisfies Record<"dev" | "prod", string> meldet ein fehlendes prod mit TS2741 und ein unbekanntes staging mit TS2353.

as const satisfies

as const und satisfies lassen sich kombinieren. Schreibe as const zuerst: Es macht den Wert tief readonly mit Literaltypen, dann prüft satisfies genau diesen Wert.

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

Jede Route wird gegen Route geprüft (ein method: "PUT" wäre ein Fehler), und das Tupel aus Literaltypen bleibt verfügbar, sodass Path eine Union der echten Pfade ist. Nimm readonly Route[] (oder ReadonlyArray<Route>) als Ziel, da ein Array mit as const readonly ist.

Konfigurationsobjekte

Bei Konfigurationen zeigt satisfies seinen Wert: Die Form muss stimmen, und Code an anderer Stelle braucht die genauen Werte.

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

Vergiss den Eintrag production, schreib logLevel falsch oder setze logLevel: "verbose", und der Compiler zeigt auf genau die Zeile. Dasselbe Muster passt zu *.config.ts-Dateien: export default { ... } satisfies SomeConfig prüft die ganze Datei, während das exportierte Objekt seine Literalwerte behält.

Wann man satisfies nicht verwendet

• Die Variable wird neu zugewiesen. let cfg = { port: 3000 } satisfies { port: number | string } gibt cfg den Typ { port: number }, also scheitert ein späteres cfg = { port: "80" } (TS2322). Annotiere Variablen, die du ändern willst.
• Du willst absichtlich den deklarierten Typ. Bei einem Rückgabewert oder einer exportierten Konstante, die Teil einer API ist, ist der Typ der Annotation der Vertrag, und den genauen Literaltyp preiszugeben kann spätere Änderungen zu Breaking Changes machen.
• Der Wert ist kein Literal. satisfies glänzt bei Objekt und Array-Literalen. Bei einer Variablen oder einem Funktionsergebnis ist es eine einfache Prüfung auf Zuweisbarkeit, die eine Annotation bereits liefert.