TypeScript Template Literal Types: Sözdizimi ve Örnekler

Template literal tip, bir JavaScript template string'iyle aynı backtick sözdizimiyle string literal tipler oluşturur. `on${Capitalize<"click" | "focus">}`, derleyicinin hesapladığı "onClick" | "onFocus" tipidir:

type DomEvent = "click" | "focus" | "blur";

type HandlerName = `on${Capitalize<DomEvent>}`;
// "onClick" | "onFocus" | "onBlur"

const handlers: Record<HandlerName, () => string> = {
  onClick: () => "clicked",
  onFocus: () => "focused",
  onBlur: () => "blurred",
};

console.log(handlers.onFocus()); // focused
// @ts-expect-error: "onHover" is not one of the handler names
handlers.onHover;

Template literal tipler yalnızca derleme zamanında vardır. Siz kod yazarken string literal'leri ve tipli değerleri kontrol ederler; JavaScript çıktısına hiçbir şey eklemezler. Yukarıdaki handler tablosu, her ad için bir fonksiyonu zorunlu kılmak için Record kullanıyor.

Sözdizimi

Backtick'lerin içine literal metin ve ${...} yer tutucuları yazarsınız. Bir yer tutucu bir değer değil bir tip tutar: bir string, number, bigint ya da boolean literal tipi, bunların bir union'ı ya da string, number, bigint, boolean, null ve undefined geniş tiplerinden biri.

type Greeting = `hello ${string}`;   // any string that starts with "hello "
type Version = `v${number}`;         // "v1", "v2.5", ...
type Toggle = `is-${boolean}`;       // "is-true" | "is-false"

const g: Greeting = "hello Ada";
const v: Version = "v3";
const t: Toggle = "is-false";

// @ts-expect-error: Type '"hi Ada"' is not assignable to type '`hello ${string}`'
const wrong: Greeting = "hi Ada";

console.log(g, v, t); // hello Ada v3 is-false

string veya number gibi geniş bir tipe sahip bir yer tutucu bir kalıp oluşturur: tip `hello ${string}` olarak kalır ve uyan her string kabul edilir. boolean gibi sonlu bir union'a sahip bir yer tutucu ise üyelerine açılır.

Union'lar Çoğalır

Birden fazla union olduğunda sonuç her kombinasyondur:

type Size = "sm" | "md" | "lg";
type Tone = "primary" | "danger";

type ButtonClass = `btn-${Size}-${Tone}`;
// "btn-sm-primary" | "btn-sm-danger" | "btn-md-primary" | ... (6 members)

function button(cls: ButtonClass): string {
  return `<button class="${cls}">`;
}

console.log(button("btn-lg-danger")); // <button class="btn-lg-danger">
// button("btn-xl-danger") would be error TS2345

Üç boyut çarpı iki ton altı üye eder. Sayı hızla büyür: her biri on harflik bir union tutan beş yer tutucu 100.000 üye ederdi ve TypeScript error TS2590: Expression produces a union type that is too complex to represent ile reddeder. Her kesin değere ihtiyacınız yoksa ${string} gibi geniş bir yer tutucu kullanın.

Uppercase, Lowercase, Capitalize, Uncapitalize

Dört yerleşik tip, string literal tiplerin büyük küçük harf durumunu değiştirir. Bunlar intrinsic'tir: TypeScript ile yazılmamış, derleyicinin içinde implement edilmiştir.

Yalnızca tipleri değiştirirler. Eşleşen çalışma zamanı string'ini oluşturmak için yine toUpperCase() çağırır ya da kendiniz bölüp büyük harfe çevirirsiniz ve TypeScript'e sonucun kesin tipte olduğunu söylersiniz:

function capitalize<S extends string>(s: S): Capitalize<S> {
  return (s.charAt(0).toUpperCase() + s.slice(1)) as Capitalize<S>;
}

const title = capitalize("report"); // type "Report"
const loud: Uppercase<"ok"> = "OK";

console.log(title, loud); // Report OK

as gereklidir, çünkü toUpperCase() düz string döndürecek şekilde tiplenmiştir. Çağıranların gördüğü şey fonksiyonun imzasıdır, bu yüzden capitalize("report") literal "Report" tipine sahiptir.

String Kalıpları: ${number}px ve Benzerleri

Bir kalıp tipi, belirli bir biçimdeki her string'i kabul eder. CSS değerleri, id'ler ve bilinen bir öneke sahip anahtarlar için kullanışlıdır:

type Pixels = `${number}px`;
type UserId = `user_${string}`;
type Semver = `${number}.${number}.${number}`;

function setWidth(w: Pixels) {
  return `width: ${w}`;
}

const id: UserId = "user_42";
const version: Semver = "7.0.2";

console.log(setWidth("120px"), id, version); // width: 120px user_42 7.0.2
// setWidth("120") and setWidth("wide px") would both be error TS2345

${number}, JavaScript'in sayı olarak okuduğu her string'i kabul eder ve bu göründüğünden daha gevşektir: "-3px", "1e3px" ve "0x10px" hepsi tip kontrolünden geçer. Bu kalıpları tam bir doğrulama olarak değil, literal'lerdeki yazım hatalarına karşı bir koruma olarak görün.

Mapped Type'larla Template Literal'ler

Template literal tipler en çok bir mapped type'ın as ifadesi olarak işe yarar; orada başka özellik adlarından yeni özellik adları üretirler:

type Watchers<T> = {
  [K in keyof T as `on${Capitalize<string & K>}Change`]: (value: T[K]) => void;
};

type Form = { email: string; age: number };

// { onEmailChange: (value: string) => void; onAgeChange: (value: number) => void }
const watch: Watchers<Form> = {
  onEmailChange: (v) => console.log("email is now", v),
  onAgeChange: (v) => console.log("age is now", v.toFixed(0)), // v is number
};

watch.onEmailChange("ada@example.com"); // email is now ada@example.com
watch.onAgeChange(37);                  // age is now 37

Capitalize sayı ya da symbol kabul etmediği için string & K yalnızca string anahtarları tutar. Her callback parametre tipini izlediği özellikten alır.

infer ile String Ayrıştırmak

Bir koşullu tipte, bir template literal bir string ile eşleşebilir ve onun parçalarını infer ile yakalayabilir. Bu, bir route kalıbından parametre adlarını çıkarır:

type RouteParams<S extends string> =
  S extends `${string}:${infer Param}/${infer Rest}`
    ? Param | RouteParams<`/${Rest}`>
    : S extends `${string}:${infer Param}`
      ? Param
      : never;

type P = RouteParams<"/users/:userId/posts/:postId">; // "userId" | "postId"

function link<S extends string>(pattern: S, params: Record<RouteParams<S>, string>): string {
  return pattern.replace(/:(\w+)/g, (_, key: string) => params[key as RouteParams<S>]);
}

console.log(link("/users/:userId/posts/:postId", { userId: "7", postId: "42" }));
// /users/7/posts/42

Çağrıda postId değerini atlarsanız derleyici onu eksik olarak bildirir.

Template İfadeleri string'e Genişler

Sıradan koddaki bir template string ifadesi, her parçası literal tip olsa bile string olarak tiplenir. Template literal tipini korumak için as const ekleyin:

type Level = "info" | "warn";

function tag(level: Level) {
  const loose = `log:${level}`;          // string
  const exact = `log:${level}` as const; // "log:info" | "log:warn"
  return { loose, exact };
}

const { exact } = tag("warn");
const again: `log:${Level}` = exact; // OK: the exact type fits
console.log(exact, again);           // log:warn log:warn

as const olmadan loose değerini `log:${Level}` tipine atamak başarısız olur, çünkü string herhangi bir şey olabilir.