TypeScriptのブランド型: 公称型をサンプルで解説

TypeScriptは型を形で比較するので、string の2つのエイリアスは交換可能です。ブランド型は型システムの中にしか存在しないタグ string & { readonly __brand: "UserId" } を加え、UserId を普通の文字列ともほかのすべてのブランドとも互換性のない型にします:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const userId = "u_42" as UserId;
const orderId = "ord_7" as OrderId;

loadUser(userId); // loading user u_42

// @ts-expect-error: an OrderId is not a UserId
loadUser(orderId); // loading user ord_7 (the error is suppressed, and types do not exist at runtime)

実行時には userId はただの文字列 "u_42" です。ブランドはコンパイル時のラベルで、その役割は ID、単位、検証済みの文字列の取り違えを防ぐことだけです。

問題: エイリアスは名前にすぎない

型エイリアスは新しい型を作りません。既存の型に2つ目の名前を付けるだけで、コンパイラーはどちらの名前も同じものとして扱います:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: both are just string
// cancelling u_42  (the bug ships)

これが構造的型付けです。TypeScriptは形が合うかをチェックし、string は string に合います。オブジェクトならたいてい形が違いますが、ID、メールアドレス、通貨、単位では形が違うことはありません。ブランドはそのケースだけを解決します。

ブランドの仕組み

string & { readonly __brand: "UserId" } は交差型です。値は文字列であり、さらに "UserId" 型の __brand プロパティも持たなければなりません。本物の文字列はそのプロパティを持たないので、普通の文字列は代入できません:

// This does not compile: a plain string, and a different brand, are both rejected
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const orderId = "ord_7" as OrderId;
loadUser("u_42");
loadUser(orderId);

index.ts(10,10): error TS2345: Argument of type 'string' is not assignable to parameter of type 'UserId'.
  Type 'string' is not assignable to type '{ readonly __brand: "UserId"; }'.
index.ts(11,10): error TS2345: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.
  Type 'OrderId' is not assignable to type '{ readonly __brand: "UserId"; }'.
    Types of property '__brand' are incompatible.
      Type '"OrderId"' is not assignable to type '"UserId"'.

大事な方向は引き続き動きます。UserId は文字列なので、文字列を受け取るものなら何にでも渡せ、.startsWith() を呼んだりテンプレートに入れたりできます。ブランドがふさぐのは入り口だけです。

検証するコンストラクター関数

入り口は as UserId のアサーションだけで、アサーションは何もチェックしません。これを入力を検証する1つの関数に入れておけば、プログラムの中のブランド付きの値はすべて、そのチェックを通ったことがわかります:

type Email = string & { readonly __brand: "Email" };

function toEmail(input: string): Email {
  const trimmed = input.trim().toLowerCase();
  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(trimmed)) {
    throw new Error(`not an email: ${input}`);
  }
  return trimmed as Email; // the only "as Email" in the codebase
}

function sendWelcome(to: Email) {
  console.log("sending to", to);
}

sendWelcome(toEmail("  Ada@Example.com ")); // sending to ada@example.com

try {
  sendWelcome(toEmail("ada at example"));
} catch (e) {
  console.log((e as Error).message); // not an email: ada at example
}

sendWelcome は入力を二度とチェックしません。引数の型が、チェックはすでに済んでいると言っているからです。これが「検証ではなくパースせよ（parse, don't validate）」という考え方です。境界でチェックし、その証明を型で持ち運びます。例外より boolean のほうがよければ、型ガード もコンストラクターとして使えます: function isEmail(s: string): s is Email。

汎用の Brand ヘルパー

型ごとに交差型を手で書くのは繰り返しになります。小さなジェネリクスで一度だけ書きましょう:

type Brand<T, Name extends string> = T & { readonly __brand: Name };

type ProductId = Brand<string, "ProductId">;
type Cents = Brand<number, "Cents">;

const cents = (n: number): Cents => {
  if (!Number.isInteger(n)) throw new Error("cents must be whole");
  return n as Cents;
};

function price(id: ProductId, amount: Cents): string {
  return `${id}: $${(amount / 100).toFixed(2)}`;
}

console.log(price("p_1" as ProductId, cents(1999))); // p_1: $19.99

数値のブランド化も文字列と同じように動きます。amount / 100 は普通の number であることに注意してください。ブランド付きの数値の算術演算はブランドのない結果になります。これについては下で説明します。

unique symbol のブランド

__brand のような文字列のプロパティ名は、本物のプロパティのように見えます。userId.__brand は "UserId" として型チェックを通りますが、実行時には undefined で、2つのライブラリが同じ名前を選ぶかもしれません。unique symbol のキーならどちらも避けられます:

declare const brand: unique symbol;

type Brand<T, Name extends string> = T & { readonly [brand]: Name };

type Meters = Brand<number, "Meters">;
type Feet = Brand<number, "Feet">;

function toMeters(feet: Feet): Meters {
  return (feet * 0.3048) as Meters;
}

const height = 10 as Feet;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048

// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

declare const brand: unique symbol は型チェッカーのためだけに存在するシンボルを宣言します。declare キーワードがあるので、これに対するJavaScriptは出力されません。シンボルはそのモジュールから export されていないので、ほかのファイルのコードはブランドのプロパティに名前を付けることすらできず、そのモジュールの外で Meters を得る方法は、export した関数か as Meters のアサーションだけです。

ブランドの実行時のコストはゼロ

コンパイル後の出力にはブランドの痕跡はありません。次は Meters の例で、コンパイラーが追加するモジュールのヘッダーの下に出力される行です。declare、2つの型エイリアス、すべての as は消え、最後の行の抑制された呼び出しはそのまま実行されます。

function toMeters(feet) {
    return (feet * 0.3048);
}
const height = 10;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048
// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

ブランド付きの値は普通のプリミティブです。typeof は "string" や "number" を返し、JSON.stringify はいつもどおりに書き出し、比較も以前と同じように動きます。裏を返せば、コンストラクター関数がチェックしない限り、実行時には何もチェックされません。JSON、データベース、URL からパースしたデータは string として届き、その関数を通したときに初めて UserId になります。

算術演算とメソッドはブランドを落とす

ブランド付きの値に対する演算は基本の型を返します。ブランドは + や .slice() が作るものの一部ではないからです:

type Cents = number & { readonly __brand: "Cents" };

const a = 500 as Cents;
const b = 250 as Cents;

const sum = a + b;           // number, not Cents
const total: Cents = a + b;  // error TS2322: Type 'number' is not assignable to type 'Cents'
const fixed = (a + b) as Cents; // re-brand when the result is still valid

たいていはこれが望ましい動きです。セント単位の2つの金額を足すとセントになりますが、セントとセントを掛けてもセントにはならず、どの演算が意味を保つかを知っているのはあなただけです。addCents(a: Cents, b: Cents): Cents のように、コードが必要とする演算の小さなヘルパーを書きましょう。

ブランド型を使う場面

同じプリミティブ型の2つの値を取り違えることが現実のリスクで、ほかにコンパイラーの助けがない場所でブランドを使います:

取り違えることのない値や、すでに形の違うオブジェクト型には使う必要はありません。検証ライブラリはスキーマからブランド型を作れます。Zod では z.string().brand<"UserId">() で、parse がブランド付きの UserId を返すスキーマが得られ、コンストラクター関数を手で書く手間が省けます。