TypeScript template literal types: תחביר ודוגמאות

Template literal type בונה טיפוסי string literal באותו תחביר של גרשיים הפוכים כמו template string ב-JavaScript. `on${Capitalize<"click" | "focus">}` הוא הטיפוס "onClick" | "onFocus", שהקומפיילר מחשב:

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 types קיימים רק בזמן קומפילציה. הם בודקים string literals וערכים עם טיפוס בזמן כתיבת הקוד, ולא מוסיפים דבר לפלט ה-JavaScript. טבלת ה-handlers שלמעלה משתמשת ב-Record כדי לחייב פונקציה אחת לכל שם.

תחביר

בתוך הגרשיים ההפוכים כותבים טקסט ליטרלי ומצייני מקום ${...}. מציין מקום מחזיק טיפוס, לא ערך: טיפוס ליטרלי של string, number, bigint או boolean, union שלהם, או אחד הטיפוסים הרחבים string, number, bigint, boolean, null ו-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

מציין מקום עם טיפוס רחב כמו string או number יוצר תבנית: הטיפוס נשאר `hello ${string}` וכל מחרוזת שמתאימה לו מתקבלת. מציין מקום עם union סופי, כמו boolean, מורחב לאיברים שלו.

Unions מוכפלים

עם כמה unions, התוצאה היא כל הצירופים:

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

שלושה גדלים כפול שני גוונים נותנים שישה איברים. המספר גדל מהר: חמישה מצייני מקום שכל אחד מהם מחזיק union של עשר אותיות יתנו 100,000 איברים, ו-TypeScript מסרב עם error TS2590: Expression produces a union type that is too complex to represent. השתמשו במציין מקום רחב כמו ${string} כשלא צריך כל ערך מדויק.

Uppercase, Lowercase, Capitalize, Uncapitalize

ארבעה טיפוסים מובנים משנים את האותיות הגדולות והקטנות בטיפוסי string literal. הם intrinsic: ממומשים בתוך הקומפיילר, ולא כתובים ב-TypeScript.

הם משנים רק טיפוסים. כדי לבנות את המחרוזת המתאימה בזמן ריצה, עדיין קוראים ל-toUpperCase() או חותכים ומגדילים את האות הראשונה בעצמכם, ואומרים ל-TypeScript שלתוצאה יש את הטיפוס המדויק:

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 נחוץ כי toUpperCase() מוגדרת כמחזירה string רגיל. החתימה של הפונקציה היא מה שהקוראים לה רואים, ולכן ל-capitalize("report") יש את הטיפוס הליטרלי "Report".

תבניות מחרוזת: ${number}px ודומיו

טיפוס תבנית מקבל כל מחרוזת בצורה מסוימת. הוא שימושי לערכי CSS, למזהים ולמפתחות עם קידומת ידועה:

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 קורא כמספר, וזה מתירני יותר ממה שנראה: "-3px", "1e3px" ו-"0x10px" כולם עוברים את בדיקת הטיפוסים. התייחסו לתבניות האלה כהגנה מפני שגיאות הקלדה בליטרלים, לא כבדיקת תקינות מלאה.

Template literals עם mapped types

Template literal types שימושיים במיוחד כפסוקית as של mapped type, שם הם יוצרים שמות מאפיינים משמות מאפיינים אחרים:

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 משאיר רק מפתחות מסוג string, כי Capitalize לא מקבל מספרים או symbols. כל callback מקבל את טיפוס הפרמטר שלו מהמאפיין שהוא עוקב אחריו.

פירוק מחרוזות עם infer

ב-conditional type, template literal יכול להתאים למחרוזת ולתפוס חלקים ממנה עם infer. כך מחלצים את שמות הפרמטרים מתבנית של נתיב:

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

אם משמיטים את postId בקריאה, הקומפיילר מדווח שהוא חסר.

ביטויי תבנית מורחבים ל-string

ביטוי template string בקוד רגיל מקבל את הטיפוס string, גם כשכל החלקים שלו הם טיפוסים ליטרליים. הוסיפו as const כדי לשמור את ה-template literal type:

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, השמה של loose ל-`log:${Level}` נכשלת, כי string יכול להיות כל דבר.