Operator satisfies w TypeScript: a adnotacje typów i as

value satisfies Type sprawdza podczas kompilacji, czy value pasuje do Type, a potem zostawia własny, bardziej precyzyjny typ wartości w spokoju. Adnotacja zastąpiłaby ten precyzyjny typ przez Type; satisfies weryfikuje bez poszerzania.

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 nadal sprawdza: brakujący kolor, błędnie wpisany klucz, taki jak bleu, albo wartość w rodzaju true to błąd kompilacji w tej linii. Istnieje od TypeScript 4.9 i, jak każda adnotacja typu, jest usuwany z wynikowego JavaScriptu.

Problem, który rozwiązuje satisfies

Z adnotacją typu typ zmiennej jest adnotacją. Kompilator zapomina, co widział w literale. Tu ta sama paleta ma zamiast tego adnotację i TypeScript już nie wie, że green to 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());

Kompilator zgłasza:

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

Przed TypeScript 4.9 do wyboru było: dodać adnotację i wszędzie zawężać ręcznie (typeof palette.green === "string") albo pominąć adnotację i stracić sprawdzenie. satisfies daje jedno i drugie. Zamień : Record<ColorName, Color> na satisfies Record<ColorName, Color> po zamykającym nawiasie klamrowym, a kod się uruchomi.

satisfies a adnotacja typu a as

Ten sam obiekt ustawień zapisany na trzy sposoby:

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 przepuścił brakujące lang, a asserted.lang w czasie działania to undefined, choć jego typ mówi string. Usuń lang z dwóch pozostałych linii, a obie zakończą się błędem TS2741, Property 'lang' is missing in type ....

Praktyczna zasada: dodawaj adnotację, gdy chcesz, żeby zmienna miała zadeklarowany typ (wartość, którą będziesz ponownie przypisywać, publiczne API), a satisfies używaj, gdy chcesz sprawdzenia, ale własny typ wartości jest bardziej przydatny.

Wyłapywanie błędów w literałach obiektów

satisfies wykonuje pełne sprawdzenie przypisywalności, łącznie ze sprawdzaniem nadmiarowych właściwości, więc literówki w kluczach to błędy:

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

Sprawdzenie nadaje też literałowi typ kontekstowy, tak jak adnotacja. Ma to znaczenie na dwa sposoby. Literały tekstowe zostają typami literałowymi, gdy typ docelowy ich oczekuje: { path: "/", method: "GET" } satisfies Route ma method: "GET", podczas gdy ten sam obiekt bez adnotacji dałby method: string. A parametry callbacków są wnioskowane z typu docelowego:

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

Klucze Record pozostają znane

Częste zastosowanie to tablica wyszukiwania. Z adnotacją Record<string, T> każdy string jest poprawnym kluczem, a literówka się kompiluje i w czasie działania zwraca undefined. Z satisfies wartości nadal są sprawdzane względem T, ale typ zmiennej wymienia dokładnie te klucze, które zapisano:

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 jest przydatne tylko dlatego, że klucze przetrwały. Z adnotacją byłoby zwykłym string.

Aby wymagać stałego zbioru kluczy, użyj satisfies z Record po unii: satisfies Record<"dev" | "prod", string> zgłasza brakujące prod błędem TS2741, a nieznane staging błędem TS2353.

as const satisfies

as const i satisfies można łączyć. Pisz najpierw as const: czyni wartość głęboko readonly z typami literałowymi, a potem satisfies sprawdza tę dokładną wartość.

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

Każda trasa jest sprawdzana względem Route (method: "PUT" byłoby błędem), a krotka typów literałowych pozostaje dostępna, więc Path to unia prawdziwych ścieżek. Jako typu docelowego użyj readonly Route[] (albo ReadonlyArray<Route>), bo tablica as const jest readonly.

Obiekty konfiguracji

To w konfiguracji satisfies naprawdę się opłaca: kształt musi się zgadzać, a kod w innych miejscach potrzebuje precyzyjnych wartości.

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

Pomiń wpis production, pomyl pisownię logLevel albo napisz logLevel: "verbose", a kompilator wskaże dokładną linię. Ten sam wzorzec pasuje do plików *.config.ts: export default { ... } satisfies SomeConfig sprawdza cały plik, a eksportowany obiekt zachowuje swoje wartości literałowe.

Kiedy nie używać satisfies

• Zmienna będzie ponownie przypisywana. let cfg = { port: 3000 } satisfies { port: number | string } nadaje cfg typ { port: number }, więc późniejsze cfg = { port: "80" } się nie uda (TS2322). Dodawaj adnotacje do zmiennych, które zamierzasz zmieniać.
• Celowo chcesz zadeklarowanego typu. Dla wartości zwracanej funkcji albo eksportowanej stałej, która jest częścią API, typ z adnotacji jest kontraktem, a ujawnienie dokładnego typu literałowego może sprawić, że późniejsze zmiany staną się breaking changes.
• Wartość nie jest literałem. satisfies błyszczy na literałach obiektów i tablic. Na zmiennej lub wyniku wywołania to zwykłe sprawdzenie przypisywalności, które daje już adnotacja.