TypeScript satisfies Operatörü: Tip Notasyonu ve as ile Farkı

value satisfies Type, value değerinin Type ile eşleştiğini derleme zamanında kontrol eder ve ardından değerin kendi, daha kesin tipine dokunmaz. Bir notasyon bu kesin tipi Type ile değiştirirdi; satisfies genişletmeden doğrular.

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

Kontrolü yine satisfies yapar: eksik bir renk, bleu gibi yanlış yazılmış bir anahtar ya da true gibi bir değer o satırda bir derleme hatasıdır. TypeScript 4.9'dan beri vardır ve her tip notasyonu gibi üretilen JavaScript'ten kaldırılır.

satisfies'ın Çözdüğü Sorun

Bir tip notasyonuyla değişkenin tipi notasyonun ta kendisidir. Derleyici literal'de gördüklerini unutur. Burada aynı palet bunun yerine notasyonla yazılmış ve TypeScript artık green değerinin bir string olduğunu bilmiyor:

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

Derleyici şunu bildirir:

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

TypeScript 4.9 öncesinde seçenekler şunlardı: notasyon yazıp her yerde elle daraltmak (typeof palette.green === "string") ya da notasyonu atlayıp kontrolü kaybetmek. satisfies ikisini birden verir. : Record<ColorName, Color> ifadesini kapanış parantezinden sonra satisfies Record<ColorName, Color> olarak değiştirin, çalışır.

satisfies, Tip Notasyonu ve as

Aynı ayarlar nesnesi, üç şekilde yazılmış:

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 eksik lang özelliğinin geçmesine izin verdi ve asserted.lang tipi string derken çalışma zamanında undefined oldu. Diğer iki satırdan lang özelliğini silin, ikisi de TS2741 ile başarısız olur, Property 'lang' is missing in type ....

Pratik kural: değişkenin bildirilen tipe sahip olmasını istediğinizde (yeniden atayacağınız bir değer, public bir API) notasyon yazın; bir kontrol istediğiniz ama değerin kendi tipinin daha işe yarar olduğu durumlarda satisfies kullanın.

Nesne Literal'lerindeki Hataları Yakalamak

satisfies, fazla özellik kontrolleri dahil tam atanabilirlik kontrolünü çalıştırır, bu yüzden anahtarlardaki yazım hataları hatadır:

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

Kontrol ayrıca literal'e, tıpkı bir notasyon gibi, bir bağlamsal tip verir. Bu iki açıdan önemlidir. Hedef tip onları beklediğinde string literal'ler literal tip olarak korunur: { path: "/", method: "GET" } satisfies Route ifadesinde method: "GET" olur, notasyonsuz aynı nesne ise method: string çıkarırdı. Ve callback parametreleri hedef tipten çıkarılır:

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 Anahtarları Bilinir Kalır

Yaygın bir kullanım bir arama tablosudur. Record<string, T> notasyonuyla her string geçerli bir anahtardır ve bir yazım hatası derlenip çalışma zamanında undefined döndürür. satisfies ile değerler yine T tipine karşı kontrol edilir, ama değişkenin tipi tam olarak yazdığınız anahtarları listeler:

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 yalnızca anahtarlar hayatta kaldığı için işe yarar. Notasyonla bu düz string olurdu.

Sabit bir anahtar kümesi istemek için bir union üzerinden Record karşılayın: satisfies Record<"dev" | "prod", string> eksik bir prod anahtarını TS2741 ile, bilinmeyen bir staging anahtarını da TS2353 ile bildirir.

as const satisfies

as const ve satisfies birleşir. Önce as const yazın: değeri literal tiplerle derinlemesine readonly yapar, ardından satisfies o kesin değeri kontrol eder.

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

Her route Route tipine karşı kontrol edilir (method: "PUT" hata olurdu) ve literal tiplerden oluşan tuple kullanılabilir kalır; böylece Path gerçek yolların bir union'ı olur. Hedef olarak readonly Route[] (veya ReadonlyArray<Route>) kullanın, çünkü bir as const dizisi readonly'dir.

Yapılandırma Nesneleri

satisfies operatörünün yerini hak ettiği yer yapılandırmadır: biçim doğru olmalıdır ve başka yerdeki kod kesin değerleri ister.

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

production girdisini unutun, logLevel adını yanlış yazın ya da logLevel: "verbose" yazın, derleyici tam olarak o satırı gösterir. Aynı kalıp *.config.ts dosyalarına uyar: export default { ... } satisfies SomeConfig dosyanın tamamını kontrol ederken export edilen nesne literal değerlerini korur.

satisfies Ne Zaman Kullanılmamalı

• Değişken yeniden atanacaksa. let cfg = { port: 3000 } satisfies { port: number | string }, cfg değişkenine { port: number } tipini verir; bu yüzden daha sonraki bir cfg = { port: "80" } başarısız olur (TS2322). Değiştirmeyi düşündüğünüz değişkenlere notasyon yazın.
• Bildirilen tipi bilerek istiyorsanız. Bir fonksiyon dönüş değeri ya da bir API'nin parçası olan export edilmiş bir sabit için notasyonun tipi sözleşmedir ve kesin literal tipin sızması sonraki değişiklikleri kırıcı hale getirebilir.
• Değer bir literal değilse. satisfies nesne ve dizi literal'lerinde parlar. Bir değişken veya bir çağrı sonucu üzerinde, bir notasyonun zaten sağladığı düz bir atanabilirlik kontrolüdür.