TypeScriptのテンプレートリテラル型: 構文と例

テンプレートリテラル型は、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;

テンプレートリテラル型はコンパイル時にしか存在しません。コードを書いている間に文字列リテラルと型付きの値をチェックし、JavaScriptの出力には何も加えません。上のハンドラーの表は、名前ごとに1つの関数を要求するために Record を使っています。

構文

バッククォートの中には、リテラルのテキストと ${...} のプレースホルダーを書きます。プレースホルダーに入るのは値ではなく型です。文字列、数値、bigint、boolean のリテラル型、それらのユニオン型、または広い型 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}` のまま残り、一致する任意の文字列を受け付けます。boolean のような有限のユニオン型のプレースホルダーは、メンバーに展開されます。

ユニオン型は掛け合わされる

ユニオン型が複数あると、結果はすべての組み合わせになります:

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

3つのサイズと2つのトーンで6つのメンバーになります。数はすぐに増えます。それぞれ10文字のユニオン型を持つプレースホルダーが5つあれば100,000個のメンバーになり、TypeScriptは error TS2590: Expression produces a union type that is too complex to represent で拒否します。すべての正確な値が必要でなければ、${string} のような広いプレースホルダーを使いましょう。

Uppercase、Lowercase、Capitalize、Uncapitalize

4つの組み込みの型が、文字列リテラル型の大文字と小文字を変えます。これらは組み込み（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

toUpperCase() は普通の string を返すと型付けされているので、as が必要です。呼び出し側に見えるのは関数のシグネチャなので、capitalize("report") はリテラル型 "Report" になります。

文字列のパターン: ${number}px など

パターンの型は、決まった形のすべての文字列を受け付けます。CSSの値や、決まった接頭辞を持つ ID やキーに便利です:

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" はどれも型チェックを通ります。こうしたパターンは完全な検証ではなく、リテラルの打ち間違いを防ぐものとして扱いましょう。

マップ型と組み合わせたテンプレートリテラル

テンプレートリテラル型がいちばん役立つのは、マップ型の as 句として、あるプロパティ名から別のプロパティ名を生成するときです:

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 は数値やシンボルを受け付けないので、string & K で文字列のキーだけを残しています。各コールバックは、監視するプロパティから引数の型を得ます。

infer で文字列を解析する

条件型の中では、テンプレートリテラルで文字列と照合し、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 に広がる

普通のコードのテンプレート文字列の式は、すべての部分がリテラル型であっても string と型付けされます。テンプレートリテラル型を保つには as const を付けます:

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 は何でもありうるからです。