Cevap.

Soruya dair tarih:

Birçok JavaScript ekosisteminde yer alan kütüphane yalnızca kaynak js dosyalarını sunar ve kendi tiplerine sahip değildir. Üçüncü taraf veya özel kütüphanelerin yanı sıra global değişkenler için tip tanımı yapmak amacıyla, TypeScript'te .d.ts (declaration files) uzantısına sahip dosyalar için özel bir format uygulanmıştır. Bunlar, herhangi bir js modülünün üzerinde tip bilgisi ve tip güvenliği sağlamak için standart haline gelmiştir.

Problem:

Eğer üçüncü taraf JS modülleri için tip tanımları yoksa, TypeScript bu tür ithalatları any olarak yorumlamak zorunda kalır, bu da statik tip konusunda tüm avantajları kaybettiğiniz anlamına gelir: çağrılardaki hatalar, var olmayan alanlar, yanlış parametreler mantıksal olarak derlemeden geçer ve yalnızca kod çalıştırıldığında ortaya çıkar. Ayrıca, otomatik tamamlama ve tipler arasında gezinti yapmak mümkün değildir.

Çözüm:

Değerlendirme dosyaları kullanarak, herhangi bir JS kodu için tipleri manuel olarak tanımlayabilirsiniz: fonksiyonlar, sınıflar, nesneler, namespace'ler ve hatta global sabitler. Böylece, dış kütüphanenin kökenine bakılmaksızın, proje tip güvenliğini korur.

Kod örneği:

// hello.d.ts
declare module 'hello' {
  export function sayHello(name: string): string;
}
// app.ts
import { sayHello } from 'hello';
sayHello('TypeScript'); // Tip güvenli

Anahtar özellikler:

İmza ve tip yapılarını uygulamalardan (kaynak JS kodundan) ayırır;
Üçüncü taraf/eski yapılar içinde sıkı tip denetimi sağlar;
.d.ts dosyalarında uygulama yapılması yasaktır, yalnızca imzalar/tanımlar bulunur.

Yanıtlar içeren sorular.

İlan dosyalarında fonksiyonların uygulamasını doğrudan tanımlamak mümkün müdür?

Hayır, ilan dosyalarında yalnızca yapıların ve imzaların tanımlanmasına izin verilir, uygulamalara değil. Herhangi bir fonksiyon gövdesi, derleme hatası çağırır.

// Yapılamaz:
declare function sum(a: number, b: number) { return a + b; }

Popüler npm modülleri için tipleri nerede bulabilirim, eğer paket içinde yoksa?

DefinitelyTyped deposunda (npm paketi @types/<lib>): neredeyse tüm popüler paketlerin güncel tip tanımları ayrı npm modülleri olarak mevcuttur.

d.ts dosyası kullanarak global değişkenleri (import etmeden) tanımlamak mümkün müdür?

Evet, ambient declarations mekanizması ile, örneğin, declare var VERSION: string; şeklinde tanımlayabilirsiniz. Bu, window.X, global sabitler ve değişkenlerin tanımlanması için pratiktir.

Tipik hatalar ve anti-patternler

d.ts dosyalarına fonksiyon ve sınıf gövdeleri yazmak;
Tam ya da eski imza tanımlamaları yapmak, gerçek yapı ile çelişki yaratmak;
Bir modül/global değişken için farklı tip tanımları ekleyerek tip çelişkisi yaratmak.

Gerçek hayat örneği

** Olumsuz durum Projede typeları olmayan bir JS kütüphanesi kullanılıyor. Geliştiriciler d.ts dosyasını unuttular ve API'ye any ile erişiyorlar. Kütüphane güncellenirken hatalar ortaya çıkıyor: eski çağrılar bozuluveriyor, ancak derleyici bunu fark etmiyor.

Artılar:

Hızlı başlangıç, ek tanım gerekmez.

Eksiler:

Gizli hatalar, belirsiz davranış, büyük kod hacimlerinde karmaşık hata ayıklama.

** Olumlu durum Mevcut kütüphane için özel bir d.ts dosyası oluşturuldu, imzalar güncel durumda tutuluyor, IDE'de otomatik tamamlama ve gezinti kullanılıyor.