Branded Type ベストプラクティス 検索

皆さんこんにちは。これは[株式会社カオナビ Advent Calendar 2024](https://qiita.com/advent-calendar/2024/kaonavi)の18日目の記事です。

今回は、TypeScriptにおける**Branded Type**について、筆者が考えるベストプラクティスを紹介します。Branded Typeという概念はTypeScriptエンジニアの間で比較的広く知られていますが、（筆者的には）ベストではないやり方が紹介されていることが多いと感じます。この記事では筆者が一番いいと思っている方法を説明しますので、そうだなと思った方はいいねや拡散をしていただけると嬉しいです。

既存の記事でも、筆者の考えるベストプラクティスに近いものが説明されているいい記事はすでにたくさんあります。なので、未だにそれ以外の説明が使われることがあるのは少し不思議なのですが、状況をさらに改善するために筆者も記事を書くことにしました。

そのため、この記事が特段新しい知識を提供するわけではありませんが、自分の言葉で説明している文章があると便利で、ついでに自分のスタンスも明確にできるのでこの記事を用意しました。よろしければお付き合いください。

既存のいい記事の例

- [Branded Types | Effect Documentation](https://effect.website/docs/code-style/branded-types/)
- [Branded Type について理解する](https://qiita.com/yamatai12/items/e972833b3105883202a3)
- [TypeScript の Type Branding をより便利に活用する方法のまとめ](https://zenn.dev/noshiro_piko/articles/typescript-branded-type-int)

## 結論

unique symbol型を使う。

## Branded Typeとは

まず、**Branded Type**というテクニックについて改めて説明します。これは、文字列などのプリミティブの型を加工して、プリミティブなのに互いに区別可能な型を作る手法のことです。

例えば、記事投稿システムでIDを文字列で表現している場合、「ユーザーID」と「記事ID」を型で区別したくなるかもしれません。ユーザーIDを受け付ける関数に記事IDを渡すようなコードがあったらそれはバグでしょうから、型チェックで弾けたら嬉しいですね。

そのような場合に採用を検討できるのがBranded Typeです。

やり方は後回しにして先に使用例を見てみましょう。

```ts
import type { UserId } from "./user";
import type { PostId, Post } from "./post";

/**
 * 記事IDを受け取って記事を返す
 */
async function getPost(id: PostId): Promise<Post> {
  const dbPost = await db.post.findOne({
    id, // ← idはランタイムには文字列なのでそのまま検索条件に使える
  });
  // （略）
}

// セッション情報からユーザーIDを取得
const userId: UserId = session.user.id;

console.log(userId); // "uhyo" （ユーザーIDは実際には文字列）

// 間違ってgetPostにuserIdを渡しちゃった！
await getPost(userId);
```

この例は、最後の行でユーザーIDを誤って記事IDとして使用してしまっています。`UserId`も`PostId`も実際には（ランタイムには）文字列です。そのため`string`としてもいいのですが、その場合はこのミスを型チェックで検出することができません。

しかし、`UserId`や`PostId`をBranded Typesのテクニックでいい感じに定義しておけば、最後の行を型エラーで弾くことができます。

![サンプルコードの最後の行で、userIdに赤い波線が引かれていて型エラーがあることを示している。](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/233667/df19b1cc-5f94-359c-749f-6cabfb80f58f.png)

また、`await getPost("mypost")`のように、`PostId`ではないただの文字列を`PostId`に渡そうとするのも型エラーとなります。

## Branded Typeの基本形

unique symbolを使ってBranded Typeを実装する場合、以下の形が基本形となります。

```ts:Branded Typeの基本形
const userIdBrand = Symbol();

export type UserId = string & { [userIdBrand]: unknown };

export function createUserId(rawId: string): UserId {
  return rawId as UserId;
}
```

このように、Branded Type（この例では`UserId`）は、プリミティブ型（`string`）と何らかのオブジェクト型のインターセクション型として定義します。こうすることで、ただの`string`はオブジェクト型のところに適合しないため、`UserId`に代入しようとしても型エラーとなります。

この例で、変数`userIdBrand`の型がunique symbol型です。これは特別なsymbol型であり、ひとつひとつのunique symbolは別々の型として認識されます。これは`Symbol()`のように新しいシンボルを生成する式に対して推論される特別な型です。

つまり、unique symbol型はすでに、Branded Typeのような性質（どちらもsymbol型だけど区別できる）を持っていることになります。この性質を応用したのが文字列に対するBranded Typeだと考えることができます。

```ts:unique symbolの性質
const userIdBrand = Symbol();
const postIdBrand = Symbol();

// これは型エラー（異なるSymbolであるため）
let a: typeof userIdBrand = postIdBrand;
// これも型エラー（異なるSymbolであるため）
const another: typeof postIdBrand = Symbol();
// これはOK
const b: typeof userIdBrand = userIdBrand;
```

そもそもシンボルは「オブジェクトのキーとして使える文字列以外の値」として導入されたもので、異なるシンボルは異なるキーとして扱われます。その性質をTypeScriptの型システムで再現するために、unique symbolという仕組みが導入されています。先ほどお見せしたBranded Typeの実装でも、unique symbolはオブジェクト型のキーとして使われています。

先ほどの説明のとおり、2つの異なるBranded Typeがある場合、互いに代入することはできません。

```ts
const userIdBrand = Symbol();
const postIdBrand = Symbol();
type UserId = string & { [userIdBrand]: unknown };
type PostId = string & { [postIdBrand]: unknown };

// 説明用にUserIdを作る
const myId = "uhyo" as UserId;

// これは型エラーになる
const postId: PostId = myId;
```

これは、`UserId`と`PostId`のオブジェクト型の部分が一致しないからです。`userIdBrand`と`postIdBrand`は異なるシンボルであり、つまりオブジェクトのキーとして異なるということです。これは例えるならば、`{a: unknown}`と`{b: unknown}`を比較しているようなものです。

## unique symbolを使わない（ベストではない）やり方

以上のようにunique symbolを使うのが筆者が考えるベストプラクティスですが、では逆に、そうではないやり方も見ておきましょう。一つは、このようなやり方が見られます。

```ts
type UserId = string & { __userIdBrand__: unknown };
type PostId = string & { __postIdBrand__: unknown };
```

要するに、シンボルを使うのをやめて、代わりに文字列のオブジェクトのキーを使う方法です。これでも、`UserId`と`PostId`は互いに区別されるようになるため、Branded Typeでやりたいことは達成できています。

このようなシンボルを使わないやり方がベストではないと筆者が考える理由は、主に2つあります。

一つは、単純に補完で余計なものが出てしまうことです。

![コードエディタで`userId.`と入力したときに表示される補完候補。一番上に`__userIdBrand__`がある。](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/233667/0dd82915-4445-a38e-9741-53272da1cdd8.png)

unique symbolを使うやり方であれば補完候補に余計なものが増えません。シンボルそのもの（`userIdBrand`）を持っていないとアクセスできませんからね。

もう一つの理由は、これが嘘だからです。

このようなBranded Typeの定義だと、「`UserId`は文字列であって、かつ`__userIdBrand__`というプロパティを持っているよ」という意味になります。しかし、実際（ランタイム）には`__userIdBrand__`というプロパティを持っていませんから、型が嘘をついていることになります。

型はランタイムの値を正しく反映しているというのが、型を信頼してコーディングをするための前提条件です。Branded Typeのためとはいえ、それを崩してしまうようなやり方はあまり気に入りません。

ただし、上の定義はまだ「マシな嘘」ではあります。なぜなら、実際にランタイムにユーザーID（ただの文字列）に対して`__userIdBrand__`にアクセスすると`undefined`になるはずですが、型の`unknown`は`undefined`の可能性も含んでいますから、万が一`__userIdBrand__`にアクセスしても型安全性が破壊される状況にはならないでしょう。

どうしても型で嘘をつく必要があるときは、最低限守るべきラインとして、このように型安全性を壊さない程度の嘘を心がけるといいでしょう。

### unique symbolは嘘ではないのか？

実を言うと、unique symbolを使うベストなやり方として紹介したものも、実は嘘ではあります。しかし、`__userIdBrand__`よりもさらにマシな嘘であると考え、ベストプラクティスとして紹介しています。

unique symbolを使うのがさらにマシな嘘である理由は、**カプセル化**と関係しています。

そもそも、シンボルという機能自体が、カプセル化の道具として使い勝手がいいものです。

オブジェクトのキーとして見たとき、シンボルと文字列の決定的な違いは何でしょうか。文字列がキーとなっているオブジェクトは、オブジェクトを持っていれば誰でもそのキーにアクセスできます。一方で、シンボルがキーとなっている場合、オブジェクトに加えて、そのシンボルそのものを持っていないと中身にアクセスできません。

:::note warn
メタプログラミング（ `Object.getOwnPropertySymbols` ）をすれば抜け穴があるのですが、正直メタプログラミングは設計と直交するもので、TSの型システムの範疇外でもあるためここでは考えないことにします。
:::

unique symbolを使うBranded Typeの例を再掲します。`userIdBrand`が`export`されていない点に特に注目してください。

```ts
const userIdBrand = Symbol();

export type UserId = string & { [userIdBrand]: unknown };

export function createUserId(rawId: string): UserId {
  return rawId as UserId;
}
```

この例では`userIdBrand`をエクスポートせず、`UserId`と`createUserId`だけをエクスポートしています。

この型定義では「`UserId`は文字列だけど、`userIdBrand`というシンボルをキーとしたプロパティがあるんだよ」という主張がされていますが、肝心の`userIdBrand`はモジュールの中に秘匿されているため、モジュールの外からはそれが本当かどうか確認する術がありません。

つまり、この`UserId`モジュールの中身を見られると嘘がばれるけど、モジュールの外からは嘘かどうか分からないのです。つまり、unique symbolを使うBranded Typeでは、嘘の範囲をアプリケーション全体から、1つのモジュールの中だけに抑えることができます。

この「外から見たら分からない」という考え方は、クラスのプライベートフィールドにも通ずるところがありますね。TypeScriptでは、プライベートフィールドを持つクラスの型も名前的型付けのような挙動をするようになり、Branded Typeに近い効果が得られます。実際、プライベートフィールドも、クラスの外からは存在に干渉できないという点で「秘匿されたシンボルをキーとするフィールド」と似ています。逆に言えば、Branded Typeは、クラスを使わずに同じような挙動を再現するテクニックだとも言えます。

ちなみに、`createUserId`の中身を見ると`as`が使われていますね。`as`もまた、TypeScriptにおいて嘘をつく手段のひとつです。このようなBranded Typeでは、その型がついた値を得るために`as`は不可欠なのですが、`createUserId`関数を提供することで、モジュールの外で`as UserId`する必要が無くなります。

このように、`userIdBrand`をエクスポートしないことで、`UserId`に関する嘘を1モジュールにしまい込むことができます。これはある種のカプセル化であり、これがうまくできるやり方だからこそ、筆者はunique symbolによるBranded Typeを支持しています。

:::note warn
今度は`createUserId`の使用者が嘘をついていないか（ユーザーIDではない文字列を`createUserId`で`UserId`に変換しちゃっていないか）をチェックをしなければならず、問題のレイヤーが移動しただけだということに気づいた聡明な読者もいるかもしれません。

それはその通りで、そこをどうするのかもまた設計の腕の見せ所だし、筆者はそういう点からそもそもBranded Type自体あまり好きではありません。

しかし、何はともあれ型システムのレイヤーでは問題が改善されたのでこの記事ではOKとします。
:::

### unique symbolを使わない他の例

先ほどはunique symbolを使わない（ベストではない）例として`__userIdBrand__: unknown` というやり方を紹介しましたが、unique symbolを使わない他のバリエーションも存在します。それがこちらです。

```ts
type UserId = string & { __brand__: "UserId" };
type PostId = string & { __brand__: "PostId" };
```

このようなやり方でもBranded Typeになりますが、これは先ほどの例よりもさらにおすすめしません。お察しのとおり、型安全性に影響を与えるタイプの嘘となっているからです。

## unique symbolを使う亜種

一方で、unique symbolを使うやりも、冒頭で示した1種類だけではありません。他にもやり方が考えられています。

一応紹介しますが、筆者としては、冒頭で紹介したものが若干優位だと考えています。その理由は、この記事で述べたような「嘘」をunique symbolの力で「カプセル化」することについては冒頭のやり方が最も優れています。

そのため、以下で紹介するようなやり方は、unique symbolを使わないものに比べればマシですが、強い理由がなければ採用しなくてもいいと思います。

### ブランドを表すシンボルを1つにする

```ts
const brand = Symbol();
type UserId = string & { [brand]: "UserId" };
type PostId = string & { [brand]: "PostId" };
```

unique symbolをキーとして活用しつつ、値部分の型でブランドを区別する方法です。

この方法だと、複数モジュールでBranded Typeを作りたい場合に`brand`を複数のモジュール間で共有しなければならず`export`が必要となってしまい、カプセル化のメリットが薄れてしまうので若干おすすめ度が低いです。

また、複数のブランドに属するBranded Typeを作れないという問題もあります。つまり、`UserId & PostId`として「ユーザーIDであり記事IDでもある文字列」を表せるかどうかという問題です。このユースケースではそんな型を考えないでしょうが、Branded Typeをバリデーションのために使うユースケースでは問題となります。

つまり、次のような場合です。

```ts
const brand = Symbol();
type NonEmptyString = string & { [brand]: "NonEmptyString" };
type LessThan100CharactersString = string & { [brand]: "LessThan100Characters" };

type GoodString = NonEmptyString & LessThan100CharactersString;
```

この定義だと、`GoodString`が`never`になってしまい合成できていません。

ブランドごとに個別にシンボルを使用する定義であれば合成できます、

```ts
const nonEmptyBrand = Symbol();
const lessThan100CharactersBrand = Symbol();

type NonEmptyString = string & { [nonEmptyBrand]: unknown; };
type LessThan100CharactersString = string & { [lessThan100CharactersBrand]: unknown };
// 合成できる！
type GoodString = NonEmptyString & LessThan100CharactersString;
```

### シンボル1つのままで合成の問題を解決する

ただし、シンボル1つのままで合成可能にする方法もあります。それは、共通のシンボルの中をオブジェクトにする方法です。

```ts
const brand = Symbol();

type NonEmptyString = string & { [brand]: { NonEmpty: unknown } };
type LessThan100CharactersString = string & { [brand]: { LessThan100Characters: unknown } };

type GoodString = NonEmptyString & LessThan100CharactersString;
```

この方法では、カプセル化の問題は良くなっていないものの、合成の問題は無くなります。

そこまでしてこのやり方を取っている例が[Effect TSのドキュメント](https://effect.website/docs/code-style/branded-types/#generalizing-branded-types)で見つかります。この例では、`Brand<K>`という型を作っています。

```ts:記事から引用
const BrandTypeId: unique symbol = Symbol.for("effect/Brand")

interface Brand<in out K extends string | symbol> {
  readonly [BrandTypeId]: {
    readonly [k in K]: K
  }
}
```

この型を使うことで、Branded Typeを手軽に定義できます。

```ts
type NonEmptyString = string & Brand<"NonEmpty">;
type LessThan100CharactersString = string & Brand<"LessThan100Characters">;
```

このように、unique symbolをライブラリの中に隠して、利用者側はシンボルを意識せずに`Brand`を使えるようにしたい場合に、このやり方が有効です。

### `declare const`を使う方法

これまでの例ではunique symbol型を得るために`Symbol()`でシンボルを作成する方法を説明していました。

しかし、型上でしか使わないのにランタイムで実際に`Symbol()`を作るのはオーバーヘッドがある気がします。

その場合は、実際にシンボルを作らずにunique symbol型だけを得るために`declare const`構文を使うこともできます。

```ts:declare const構文を使う
declare const userIdBrand: unique symbol;

export type UserId = string & { [userIdBrand]: unknown };

export function createUserId(rawId: string): UserId {
  return rawId as UserId;
}
```

これについては、筆者はどちらでもいいと考えています。`Symbol()`のオーバーヘッドは微々たるものだからそこまで意識しなくてもいいでしょうし、`declare const`はランタイムの実態がないのに変数を宣言できてしまうので若干危険な構文なので、絶対に使わなければならないというほどではないでしょう。

とはいえ、`declare const`で余計なオーバーヘッドを消せるのも事実ですから、気になる場合はこちらを採用してもいいでしょう。

## まとめ

この記事では、TypeScriptのBranded Typeの定義について、筆者がベストプラクティスだと考えるやり方を紹介し、他のやり方と比較しながら理由を説明しました。

```ts:Branded Typeのベストプラクティス
const userIdBrand = Symbol();

export type UserId = string & { [userIdBrand]: unknown };

export function createUserId(rawId: string): UserId {
  return rawId as UserId;
}
```

シンボルは、TypeScriptにおけるカプセル化の道具として特に有用です。Branded Typeもその活用例と考えることができます。臆せずシンボルを活用していきましょう。