Operator satisfies di TypeScript: vs Anotasi Tipe dan as

value satisfies Type mengecek saat kompilasi bahwa value cocok dengan Type, lalu membiarkan tipe milik nilai itu sendiri, yang lebih tepat, tetap seperti semula. Anotasi akan mengganti tipe yang tepat itu dengan Type; satisfies memvalidasi tanpa melebarkan tipe.

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 tetap melakukan pengecekan: warna yang hilang, key yang salah eja seperti bleu, atau nilai seperti true adalah error kompilasi di baris itu. Operator ini ada sejak TypeScript 4.9 dan, seperti setiap anotasi tipe, dihapus dari JavaScript yang dihasilkan.

Masalah yang Diselesaikan satisfies

Dengan anotasi tipe, tipe variabel adalah anotasinya. Compiler melupakan apa yang dilihatnya di literal. Di sini palet yang sama diberi anotasi, dan sekarang TypeScript tidak lagi tahu bahwa green adalah 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());

Compiler melaporkan:

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

Sebelum TypeScript 4.9, pilihannya adalah: beri anotasi lalu persempit tipe secara manual di mana-mana (typeof palette.green === "string"), atau lewati anotasi dan kehilangan pengecekannya. satisfies memberi keduanya. Ganti : Record<ColorName, Color> dengan satisfies Record<ColorName, Color> setelah kurung kurawal penutup dan kodenya berjalan.

satisfies vs Anotasi Tipe vs as

Object pengaturan yang sama, ditulis dengan tiga cara:

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 meloloskan lang yang hilang, dan asserted.lang bernilai undefined saat runtime padahal tipenya bilang string. Hapus lang dari dua baris lainnya dan keduanya gagal dengan TS2741, Property 'lang' is missing in type ....

Patokan praktisnya: beri anotasi kalau kamu ingin variabelnya punya tipe yang dideklarasikan (nilai yang akan di-assign ulang, API publik), dan pakai satisfies kalau kamu ingin pengecekan tetapi tipe milik nilai itu sendiri lebih berguna.

Menangkap Kesalahan di Object Literal

satisfies menjalankan pengecekan assignability secara penuh, termasuk excess property check, jadi salah ketik di key menjadi error:

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

Pengecekan ini juga memberi literal itu contextual type, sama seperti anotasi. Itu penting dalam dua hal. String literal dipertahankan sebagai literal type kalau tipe targetnya mengharapkannya: { path: "/", method: "GET" } satisfies Route punya method: "GET", sedangkan object yang sama tanpa anotasi akan menyimpulkan method: string. Lalu parameter callback disimpulkan dari tipe target:

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

Key Record Tetap Diketahui

Pemakaian yang umum adalah tabel lookup. Kalau dianotasi sebagai Record<string, T>, setiap string adalah key yang valid dan salah ketik tetap lolos kompilasi, lalu menghasilkan undefined saat runtime. Dengan satisfies, nilainya tetap dicek terhadap T, tetapi tipe variabelnya mendaftar tepat key yang kamu tulis:

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 hanya berguna karena key-nya bertahan. Dengan anotasi, hasilnya hanya string.

Untuk mewajibkan himpunan key yang tetap, pastikan nilainya memenuhi Record atas sebuah union: satisfies Record<"dev" | "prod", string> melaporkan prod yang hilang dengan TS2741 dan staging yang tidak dikenal dengan TS2353.

as const satisfies

as const dan satisfies bisa digabungkan. Tulis as const lebih dulu: ia membuat nilainya readonly secara mendalam dengan literal type, lalu satisfies mengecek nilai yang persis itu.

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

Setiap route dicek terhadap Route (method: "PUT" akan menjadi error), dan tuple berisi literal type tetap tersedia, jadi Path adalah union dari path yang sebenarnya. Pakai readonly Route[] (atau ReadonlyArray<Route>) sebagai target, karena array as const bersifat readonly.

Object Konfigurasi

Konfigurasi adalah tempat satisfies paling berguna: bentuknya harus benar, dan kode di tempat lain menginginkan nilai yang persis.

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

Lupakan entri production, salah eja logLevel, atau tulis logLevel: "verbose", dan compiler menunjuk baris yang tepat. Pola yang sama cocok untuk file *.config.ts: export default { ... } satisfies SomeConfig mengecek seluruh file sementara object yang di-export tetap mempertahankan nilai literalnya.

Kapan Tidak Memakai satisfies

• Variabelnya akan di-assign ulang. let cfg = { port: 3000 } satisfies { port: number | string } memberi cfg tipe { port: number }, jadi cfg = { port: "80" } di kemudian hari gagal (TS2322). Beri anotasi pada variabel yang memang ingin kamu ubah.
• Kamu memang menginginkan tipe yang dideklarasikan. Untuk nilai kembalian fungsi atau konstanta yang di-export sebagai bagian dari API, tipe anotasinya adalah kontraknya, dan membocorkan literal type yang persis bisa membuat perubahan di kemudian hari menjadi breaking change.
• Nilainya bukan literal. satisfies paling bermanfaat pada object dan array literal. Pada variabel atau hasil pemanggilan fungsi, ia hanya pengecekan assignability biasa, yang sudah diberikan oleh anotasi.