TypeScript Best Practices: Önce ve Sonra ile 8 Kural

Q: TypeScript'te any kullanmalı mıyım?

Uygulama kodunda neredeyse hiçbir zaman. any, değer ve ondan türetilen her şey için kontrolü kapatır. Tipini henüz bilmediğiniz değerler için unknown kullanın ve onları kontrollerle daraltın; any'yi nadir kaçış yolları için, nedenini açıklayan bir yorumla birlikte saklayın.

Q: Yeni bir TypeScript projesi için en iyi tsconfig ayarları nelerdir?

strict'i açık tutun (TypeScript 7'nin varsayılanı) ve noUncheckedIndexedAccess ekleyin. Birçok proje ayrıca noImplicitOverride, noFallthroughCasesInSwitch ve verbatimModuleSyntax seçeneklerini açar. tsc --init'in yazdığı config, diğerlerinin yanında strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes ve verbatimModuleSyntax ayarlar.

Aşağıdaki kurallar, gerçek TypeScript kodunda en çok hatayı önleyenlerdir. Her biri önce yaygın sürümü, sonra daha iyisini, çalıştırabileceğiniz kodla gösterir. En önemlisi ilk kuraldır: any kullanmayı bırakın.

any Yerine unknown Kullanın

any, bir değer ve ondan hesaplanan her şey için tip kontrolünü kapatır. unknown da her değeri kabul eder, ama kullanmadan önce onu kontrol etmeniz gerekir; bu da kontrolü verinin programınıza girdiği yere koyar:

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

Sınırlar, tiplerin artık garanti olmadığı yerlerdir: JSON.parse, fetch yanıtları, localStorage, form girdileri, ortam değişkenleri ve diğer süreçlerden gelen mesajlar. Orada bir type guard ya da bir şema kütüphanesiyle doğrulayın, kodun geri kalanı tiplerine güvenebilir.

strict'i Açık Tutun

strict, TypeScript 7'de varsayılandır; kapatmayın. Onun dışarıda bıraktığı ve en çok hatayı yakalayan kontrolleri ekleyin:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

noUncheckedIndexedAccess, arr[i] ve record[key] tiplerine undefined ekler; eksik bir indeks için döndürdükleri de budur. noImplicitOverride bir alt class metodunun override yazmasını sağlar, noFallthroughCasesInSwitch ise bir sonrakine akan bir case'i reddeder.

Tip Çıkarımını Çalıştırın

TypeScript'in bilemeyeceği şeyleri işaretleyin: fonksiyon parametreleri ve diğer modüllerin kullandığı fonksiyonların dönüş tipleri. Yerel değişkenleri ve callback parametrelerini tip çıkarımına bırakın. Gereksiz bir işaretleme yalnızca gürültü değildir; bir tipi değerden daha geniş yapabilir:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

@ts-expect-error yorumu olmadan setStatus(annotated) TS2345 hatasıdır. Çıkarılan const, "active" literal tipini korur, bu yüzden kabul edilir. Bir tip eklemeden önce neyin çıkarıldığını görmek için editörünüzde değişkenin üzerine gelin.

Enum Yerine Union Tiplerini Tercih Edin

String literal'lerinden oluşan bir union, hiç kod üretmeden otomatik tamamlama ve eksiksizlik kontrolü verir. Değer listesine çalışma zamanında da ihtiyacınız varsa, tipi bir as const dizisinden türetin:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

Bir enum Role { Admin, Viewer }, ters eşlemeli bir nesneye derlenir ve sayısal bir enum parametresi, enum'un listelemediği bir değeri tutsa bile herhangi bir number değişkenini kabul eder. Enum'lar Node'un type stripping'i altında da çalışamaz (TypeScript enum is not supported in strip-only mode). Artıları ve eksileri enum'lar sayfasında karşılaştırılır.

Config Nesnelerini satisfies ile Kontrol Edin

Bir nesneyi Record<string, Route> gibi geniş bir tiple işaretlemek değerlerini kontrol eder ama anahtarlarını unutur. satisfies aynı şeyi kontrol eder ve tam tipi korur:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

Değişkenin tam olarak belirtilen tipe sahip olması gerektiğinde (bir fonksiyon parametresi, yeniden atayacağınız bir değer) işaretleme kullanın. Arama tabloları, route haritaları, tema token'ları ve diğer sabit nesneler için satisfies kullanın.

Durumu Discriminated Union ile Modelleyin

İsteğe bağlı alanları olan tek bir nesne, gerçekleşemeyecek durumlara izin verir: bir error ile birlikte loading: true ya da başarıdan sonra eksik data. Ortak bir etiketi paylaşan nesnelerden oluşan bir union yalnızca gerçek durumlara izin verir ve her dal yalnızca kendi alanlarını görür:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

never satırı eksiksizlik kontrolüdür. Biri yeni bir durum ekleyip onu ele almayı unuttuğunda build o satırda kırılır:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

Hata şudur: index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. Ele alınmayan durumu adıyla söyler. case "cancelled": ekleyin, kod derlenir.

! ve as Kullanmaktan Kaçının

Non-null assertion x! ve type assertion x as T, derleyiciye kontrolü bırakmasını söyler. İkisi de çalışma zamanında değeri değiştirmez, bu yüzden yanlış bir assertion daha sonra, nedeninden uzakta bir çökmeye dönüşür:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

! yerine ?., ??, erken bir return ya da faydalı bir mesajla fırlatılan bir hata kullanın. as yerine değeri gerçekten test eden bir type guard kullanın. Her zaman güvenli olan tek assertion as const'tur, çünkü bir tipi yalnızca daraltır ve salt okunur yapar. İyi bir lint kurulumu (typescript-eslint'in no-non-null-assertion ve no-explicit-any kuralları) geri kalanını işaretler.

Veriyi readonly Yapın

Kodun değiştirmemesi gereken özellikleri ve dizileri readonly olarak işaretleyin. Derleyici bu durumda push, sort ve atamaları reddeder ve fonksiyonlar girdilerini değiştirmek yerine yeni değerler döndürür:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly yalnızca derleme zamanında ve yalnızca bir seviye derinlikte kontrol edilir: nesneyi çalışma zamanında dondurmaz. Yine de bu hataların çoğuna yol açan paylaşılan durumun kazara değiştirilmesini yakalamaya yeter.

Sıkça Sorulan Sorular

TypeScript'te any kullanmalı mıyım?

Uygulama kodunda neredeyse hiçbir zaman. any, değer ve ondan türetilen her şey için kontrolü kapatır. Tipini henüz bilmediğiniz değerler için unknown kullanın ve onları kontrollerle daraltın; any'yi nadir kaçış yolları için, nedenini açıklayan bir yorumla birlikte saklayın.

TypeScript'te her değişkene tip yazmalı mıyım?

Hayır. Yerel değişkenlerin ve callback parametrelerinin tipini TypeScript çıkarsın. Fonksiyon parametrelerini (çıkarılamazlar) ve export edilen fonksiyonların dönüş tiplerini işaretleyin; böylece fonksiyonun içindeki bir değişiklik public tipini sessizce değiştiremez.

TypeScript enum'ları kötü bir uygulama mı?

Yanlış değiller, ama birçok ekip onlardan kaçınır. Bir enum çalışma zamanı kodu üretir, Node'un type stripping'i altında çalışamaz ve sayısal bir enum parametresi, tuttuğu değer ne olursa olsun herhangi bir number değişkenini kabul eder. String literal'lerinden oluşan bir union ya da türetilmiş bir tipe sahip bir as const dizisi, hiç kod üretmeden aynı otomatik tamamlamayı ve kontrolleri verir.

as ile type assertion ne zaman kullanılmalı?

Yalnızca derleyicinin bilemeyeceği bir şeyi bildiğinizde ve tercihen bunu kanıtlayan bir kontrolün hemen ardından. as çalışma zamanında hiçbir değeri değiştirmez, bu yüzden {} as User derlenir ve sonra hiçbir name içermez. Çoğu durumda değeri test eden bir type guard daha güvenli bir araçtır.

Yeni bir TypeScript projesi için en iyi tsconfig ayarları nelerdir?

strict'i açık tutun (TypeScript 7'nin varsayılanı) ve noUncheckedIndexedAccess ekleyin. Birçok proje ayrıca noImplicitOverride, noFallthroughCasesInSwitch ve verbatimModuleSyntax seçeneklerini açar. tsc --init'in yazdığı config, diğerlerinin yanında strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes ve verbatimModuleSyntax ayarlar.

İlgili kavramlar