TypeScript satisfies Operatörü: Tip Notu ve as ile Karşılaştırma

Üç yöntem tek örnekte

Bir ayar nesnesini üç şekilde tanımlayıp ortam alanının tipini kontrol edelim (--strict --target es2022):

type Ayar = { ortam: "gelistirme" | "canli"; debug: boolean };

const a1: Ayar = { ortam: "canli", debug: false };              // tip notu
const a2 = { ortam: "canli", debug: false } satisfies Ayar;     // satisfies
const a3 = { ortam: "canli", debug: false };                    // hiçbiri

const t1: "canli" = a1.ortam;
// TS2322: Type '"gelistirme" | "canli"' is not assignable to type '"canli"'.
//   Type '"gelistirme"' is not assignable to type '"canli"'.

const t2: "canli" = a2.ortam; // hata yok: tip "canli" olarak korundu

const t3: Ayar = a3;
// TS2322: Type '{ ortam: string; debug: boolean; }' is not assignable to type 'Ayar'.
//   Types of property 'ortam' are incompatible.
//     Type 'string' is not assignable to type '"gelistirme" | "canli"'.

a1 tip notu aldığı için ortam alanı artık Ayar'daki geniş birleşimdir. a3 hiçbir bağlam almadığından ortam düz string olarak genişledi ve sonradan Ayar'a atanamadı. a2 ise hem Ayar'a göre denetlendi hem de "canli" literal tipini korudu. Literal tiplerin neden genişlediğini literal tipler yazısında anlattık.

Gerçek bir senaryo: ortam ayarları

TypeScript 4.9 sürüm notlarındaki renk paleti örneğine benzer bir durumda, her ortam için bir port ve tek ya da birden fazla host tutuyoruz:

type Ortam = "gelistirme" | "test" | "canli";
type Ayar = { port: number; host: string | string[] };

// 1) Tip notu ile
const ayar1: Record<Ortam, Ayar> = {
  gelistirme: { port: 3000, host: "localhost" },
  test: { port: 3001, host: ["10.0.0.5", "10.0.0.6"] },
  canli: { port: 443, host: "keydal.tr" },
};
ayar1.test.host.map((h) => h.trim());
// TS2339: Property 'map' does not exist on type 'string | string[]'.
//   Property 'map' does not exist on type 'string'.

// 2) satisfies ile
const ayar2 = {
  gelistirme: { port: 3000, host: "localhost" },
  test: { port: 3001, host: ["10.0.0.5", "10.0.0.6"] },
  canli: { port: 443, host: "keydal.tr" },
} satisfies Record<Ortam, Ayar>;
ayar2.test.host.map((h) => h.trim());   // host: string[]
ayar2.canli.host.toUpperCase();         // host: string

Tip notunda derleyici yalnızca Record<Ortam, Ayar> bilgisini hatırlar, bu yüzden test.host değerinin dizi olduğunu bilemez. satisfies ile her alanın gerçek tipi korunur ve map ya da toUpperCase doğrudan kullanılabilir. Record ve diğer yardımcı tipler için utility types yazısına bakın.

satisfies hangi hataları yakalar

Aynı nesnede üç ayrı hata yaptığımızda tsc 6.0 şu mesajları verdi:

// Anahtar adında yazım hatası
const a = {
  gelistirme: { port: 3000, host: "localhost" },
  tset: { port: 3001, host: "10.0.0.5" },
  // TS2353: Object literal may only specify known properties, and 'tset' does not exist in type 'Record<Ortam, Ayar>'.
  canli: { port: 443, host: "keydal.tr" },
} satisfies Record<Ortam, Ayar>;

// Eksik anahtar
const b = {
  gelistirme: { port: 3000, host: "localhost" },
  canli: { port: 443, host: "keydal.tr" },
} satisfies Record<Ortam, Ayar>;
// TS1360: Type '{ gelistirme: ...; canli: ...; }' does not satisfy the expected type 'Record<Ortam, Ayar>'.
//   Property 'test' is missing in type ... but required in type 'Record<Ortam, Ayar>'.

// Yanlış değer tipi
const c = {
  gelistirme: { port: 3000, host: "localhost" },
  test: { port: 3001, host: "10.0.0.5" },
  canli: { port: "443", host: "keydal.tr" },
  // TS2322: Type 'string' is not assignable to type 'number'.
} satisfies Record<Ortam, Ayar>;

TS1360 mesajındaki uzun tip adlarını okunabilirlik için kısalttık. Sürüm notlarının örneklerinden biri de anahtarları tam olarak bir union'daki değerlerle sınırlayıp değer tiplerini serbest bırakmak için satisfies Record<Renkler, unknown> kullanır.

as ile farkı: denetim yerine güven

as bir tip iddiasıdır (type assertion). Değeri o tipe uydurduğunuzu söylersiniz ve derleyici eksik alanları sormaz:

const ayar = {
  gelistirme: { port: 3000, host: "localhost" },
  canli: { port: 443, host: "keydal.tr" },
} as Record<Ortam, Ayar>;   // derleme hatası yok

console.log(ayar.test.port);
// Node.js 24 çalışma zamanı: TypeError: Cannot read properties of undefined (reading 'port')

Bu dosya hatasız derlendi ama çalışırken çöktü. as yalnızca iki tip birbiriyle hiç örtüşmüyorsa itiraz eder:

const p = { port: "443" } as { port: number };
// TS2352: Conversion of type '{ port: string; }' to type '{ port: number; }' may be a mistake because neither type
// sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.

as'ın ne zaman gerekli olduğunu ve as unknown as kalıbının risklerini type assertion yazısında anlattık.

as const satisfies: salt okunur ve denetlenmiş

as const değerleri literal ve readonly yapar; arkasına satisfies ekleyince bu literal değerler aynı zamanda bir şemaya göre denetlenir. Rota listesi gibi sabit tablolarda kullanışlıdır:

type Rota = { yol: string; yetki: "herkes" | "uye" | "admin" };

const rotalar = [
  { yol: "/", yetki: "herkes" },
  { yol: "/panel", yetki: "admin" },
] as const satisfies readonly Rota[];

type Yol = (typeof rotalar)[number]["yol"]; // "/" | "/panel"

const y: Yol = "/panel";
const z: Yol = "/ayarlar";
// TS2322: Type '"/ayarlar"' is not assignable to type '"/" | "/panel"'.

as const dizi ürettiği için hedef tipi readonly Rota[] olarak yazdık. yetki alanına listede olmayan bir değer yazılsaydı satisfies onu yakalardı. Indexed access sözdizimi ([number]["yol"]) için keyof ve indexed access yazısına bakın.

Ne zaman hangisini kullanmalı?

• Değişkenin tipini bilerek genişletmek istiyorsanız (sonradan başka değerler atanacaksa): tip notu.
• Sabit bir yapılandırma, eşleme tablosu veya sözlük tanımlıyorsanız ve özel tipleri korumak istiyorsanız: satisfies.
• Derleyicinin bilemeyeceği bir şeyi kesin olarak biliyorsanız (örneğin doğruladığınız dış veri): as, dikkatle.
• Değerlerin hem değişmez hem şemaya uygun olması gerekiyorsa: as const satisfies.

JSON dosyalarından okunan ayarlar çalışma zamanında gelir; satisfies yalnızca kaynak koddaki değerleri denetler. Dış veriyi doğrulamak için JSON.parse yazısındaki yaklaşımlara ve type guard yazısına bakın.

Sık yapılan hatalar

• satisfies'ın değişkene tip verdiğini sanmak. let ile tanımlanan bir değişkene sonradan atanacak değerler tip notundaki gibi denetlenmez.
• Eksik alanları susturmak için as kullanmak; hata derlemeden çalışma zamanına kayar.
• as const ile birlikte hedef tipte readonly yazmayı unutmak.
• TypeScript 4.9 öncesi bir derleyiciyle çalışan projede satisfies kullanmak; sözdizimi o sürümlerde tanınmaz.

Sık Sorulan Sorular

satisfies çalışma zamanında bir şey yapar mı?

Hayır. Tamamen derleme zamanında çalışır ve derlenen JavaScript'ten silinir.

satisfies ile tip notu aynı anda kullanılabilir mi?

Teknik olarak mümkündür ama tip notu değişkenin tipini belirlediği için satisfies'ın tip koruma avantajı kaybolur. Genellikle ikisinden birini seçin.

JavaScript dosyalarında satisfies kullanabilir miyim?

TypeScript 5.0 sürüm notlarına göre JSDoc içinde @satisfies etiketi desteklenir; tip denetimi yapılan JavaScript dosyalarında aynı işi görür.

satisfies hangi sürümden beri var?

TypeScript 4.9 ile geldi. Sürüm notları özelliği, bir ifadenin tipe uyduğunu doğrularken ifadenin tipini değiştirmeyen bir operatör olarak tanımlar.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: TypeScript öğrenme rehberi · type assertion (as) · literal tipler ve as const · utility types · TypeScript ileri seviye · JSON.parse ve stringify