Template Literal Type di TypeScript: Sintaks dan Contoh

Template literal type membangun string literal type dengan sintaks backtick yang sama seperti template string JavaScript. `on${Capitalize<"click" | "focus">}` adalah tipe "onClick" | "onFocus", yang dihitung oleh compiler:

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 type hanya ada saat kompilasi. Tipe ini mengecek string literal dan nilai bertipe selama kamu menulis kode; ia tidak menambahkan apa pun ke output JavaScript. Tabel handler di atas memakai Record untuk mewajibkan satu fungsi untuk setiap nama.

Sintaks

Di dalam backtick, kamu menulis teks literal dan placeholder ${...}. Placeholder berisi tipe, bukan nilai: literal type string, number, bigint atau boolean, union dari tipe-tipe itu, atau salah satu tipe lebar string, number, bigint, boolean, null dan undefined.

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

Placeholder dengan tipe lebar seperti string atau number membentuk pola: tipenya tetap `hello ${string}` dan string apa pun yang cocok akan diterima. Placeholder dengan union yang terbatas, seperti boolean, dijabarkan menjadi anggota-anggotanya.

Union Berlipat Ganda

Dengan beberapa union, hasilnya adalah setiap kombinasinya:

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

Tiga ukuran dikali dua warna menghasilkan enam anggota. Jumlahnya cepat membesar: lima placeholder yang masing-masing berisi union sepuluh huruf akan menjadi 100.000 anggota, dan TypeScript menolaknya dengan error TS2590: Expression produces a union type that is too complex to represent. Pakai placeholder lebar seperti ${string} kalau kamu tidak butuh setiap nilai yang persis.

Uppercase, Lowercase, Capitalize, Uncapitalize

Empat tipe bawaan mengubah huruf besar kecil pada string literal type. Keempatnya intrinsik: diimplementasikan di dalam compiler, bukan ditulis dalam TypeScript.

Tipe-tipe ini hanya mengubah tipe. Untuk membangun string runtime yang sesuai, kamu tetap memanggil toUpperCase() atau memotong string dan mengubah huruf pertamanya sendiri, lalu memberi tahu TypeScript bahwa hasilnya punya tipe yang persis:

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 diperlukan karena toUpperCase() diberi tipe yang mengembalikan string biasa. Signature fungsinya itulah yang dilihat pemanggil, jadi capitalize("report") punya literal type "Report".

Pola String: ${number}px dan Sejenisnya

Tipe pola menerima setiap string dengan bentuk tertentu. Ini praktis untuk nilai CSS, id, dan key dengan prefix yang sudah diketahui:

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} menerima string apa pun yang dibaca JavaScript sebagai angka, dan itu lebih longgar daripada kelihatannya: "-3px", "1e3px" dan "0x10px" semuanya lolos pengecekan tipe. Anggap pola ini sebagai penjaga terhadap salah ketik di literal, bukan validasi yang lengkap.

Template Literal dengan Mapped Type

Template literal type paling berguna sebagai klausa as di mapped type, tempat ia membuat nama property dari nama property lain:

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

string & K hanya mempertahankan key string, karena Capitalize tidak menerima number atau symbol. Setiap callback mendapat tipe parameternya dari property yang diawasinya.

Mem-parse String dengan infer

Di conditional type, template literal bisa mencocokkan sebuah string dan menangkap bagian-bagiannya dengan infer. Contoh ini mengambil nama-nama parameter dari pola route:

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

Hilangkan postId di pemanggilan, dan compiler melaporkannya sebagai yang hilang.

Ekspresi Template Dilebarkan Menjadi string

Ekspresi template string di kode biasa bertipe string, walaupun setiap bagiannya adalah literal type. Tambahkan as const untuk mempertahankan template literal type-nya:

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

Tanpa as const, meng-assign loose ke `log:${Level}` gagal, karena string bisa berupa apa saja.