L'operatore satisfies in TypeScript: vs annotazioni e as

value satisfies Type controlla in fase di compilazione che value corrisponda a Type, e poi lascia stare il tipo proprio del valore, più preciso. Un'annotazione sostituirebbe quel tipo preciso con Type; satisfies convalida senza allargare.

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 fa comunque il controllo: un colore mancante, una chiave scritta male come bleu o un valore come true è un errore di compilazione su quella riga. Esiste da TypeScript 4.9 e, come ogni annotazione di tipo, viene rimosso dal JavaScript generato.

Il problema che satisfies risolve

Con un'annotazione di tipo, il tipo della variabile è l'annotazione. Il compilatore dimentica ciò che ha visto nel letterale. Qui la stessa tavolozza è annotata, e ora TypeScript non sa più che green è una stringa:

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

Il compilatore segnala:

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

Prima di TypeScript 4.9 le scelte erano: annotare e restringere a mano ovunque (typeof palette.green === "string"), oppure saltare l'annotazione e perdere il controllo. satisfies dà entrambe le cose. Cambia : Record<ColorName, Color> in satisfies Record<ColorName, Color> dopo la parentesi graffa di chiusura e funziona.

satisfies vs annotazione di tipo vs as

Lo stesso oggetto di impostazioni, scritto in tre modi:

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 ha lasciato passare il lang mancante, e asserted.lang è undefined in fase di esecuzione mentre il suo tipo dice string. Togli lang dalle altre due righe ed entrambe falliscono con TS2741, Property 'lang' is missing in type ....

Regola pratica: annota quando vuoi che la variabile abbia il tipo dichiarato (un valore che riassegnerai, un'API pubblica), e usa satisfies quando vuoi un controllo ma il tipo proprio del valore è più utile.

Intercettare errori negli oggetti letterali

satisfies esegue il controllo di assegnabilità completo, compreso quello delle proprietà in eccesso, quindi gli errori di battitura nelle chiavi sono errori:

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

Il controllo dà anche al letterale un tipo contestuale, proprio come fa un'annotazione. Questo conta in due modi. I letterali stringa vengono mantenuti come tipi letterali quando il tipo di destinazione se li aspetta: { path: "/", method: "GET" } satisfies Route ha method: "GET", mentre lo stesso oggetto senza annotazione inferirebbe method: string. E i parametri delle callback vengono inferiti dal tipo di destinazione:

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

Le chiavi di un Record restano note

Un uso comune è una tabella di lookup. Annotata come Record<string, T>, ogni stringa è una chiave valida e un errore di battitura compila, restituendo undefined in fase di esecuzione. Con satisfies, i valori vengono comunque controllati rispetto a T, ma il tipo della variabile elenca esattamente le chiavi che hai scritto:

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 è utile solo perché le chiavi sono sopravvissute. Con l'annotazione sarebbe un semplice string.

Per richiedere un insieme fisso di chiavi, usa satisfies con un Record su un'unione: satisfies Record<"dev" | "prod", string> segnala un prod mancante con TS2741 e uno staging sconosciuto con TS2353.

as const satisfies

as const e satisfies si combinano. Scrivi prima as const: rende il valore readonly in profondità con tipi letterali, poi satisfies controlla quel valore esatto.

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

Ogni route viene controllata rispetto a Route (un method: "PUT" sarebbe un errore), e la tupla di tipi letterali resta disponibile, quindi Path è un'unione dei percorsi reali. Usa readonly Route[] (o ReadonlyArray<Route>) come destinazione, dato che un array as const è readonly.

Oggetti di configurazione

La configurazione è il campo in cui satisfies si guadagna il posto: la forma deve essere giusta, e il codice altrove vuole i valori precisi.

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

Dimentica la voce production, scrivi male logLevel o scrivi logLevel: "verbose", e il compilatore indica la riga esatta. Lo stesso schema va bene per i file *.config.ts: export default { ... } satisfies SomeConfig controlla l'intero file mentre l'oggetto esportato mantiene i suoi valori letterali.

Quando non usare satisfies

• La variabile verrà riassegnata. let cfg = { port: 3000 } satisfies { port: number | string } dà a cfg il tipo { port: number }, quindi un successivo cfg = { port: "80" } fallisce (TS2322). Annota le variabili che intendi modificare.
• Vuoi di proposito il tipo dichiarato. Per il valore di ritorno di una funzione o una costante esportata che fa parte di un'API, il tipo dell'annotazione è il contratto, e far trapelare il tipo letterale esatto può rendere incompatibili le modifiche future.
• Il valore non è un letterale. satisfies dà il meglio su oggetti e array letterali. Su una variabile o sul risultato di una chiamata è un semplice controllo di assegnabilità, che un'annotazione ti dà già.