M

MLOG

日本語

TypeScriptのBranded Typeを探求します。これは、構造的型システムで公称的型付けを実現するための強力な手法です。型安全性とコードの明確性を向上させる方法を学びましょう。

TypeScriptのBranded Type: 構造的型システムにおける公称的型付け

TypeScriptの構造的型システムは柔軟性を提供しますが、時に予期せぬ動作を引き起こすことがあります。Branded Typeは、公称的型付けを強制する方法を提供し、型安全性とコードの明確性を向上させます。この記事では、Branded Typeを詳細に探求し、その実装のための実践的な例とベストプラクティスを提供します。

構造的型付けと公称的型付けの理解

Branded Typeに深く入る前に、構造的型付けと公称的型付けの違いを明確にしましょう。

構造的型付け（ダックタイピング）

構造的型システムでは、2つの型が同じ構造（つまり、同じプロパティを同じ型で持つ）を持つ場合、互換性があると見なされます。TypeScriptは構造的型付けを使用しています。この例を考えてみましょう。


interface Point {
  x: number;
  y: number;
}

interface Vector {
  x: number;
  y: number;
}

const point: Point = { x: 10, y: 20 };
const vector: Vector = point; // TypeScriptでは有効

console.log(vector.x); // 出力: 10

PointとVectorが別個の型として宣言されているにもかかわらず、TypeScriptはそれらが同じ構造を共有しているため、PointオブジェクトをVector変数に代入することを許可します。これは便利な場合もありますが、偶然同じ形状を持つ論理的に異なる型を区別する必要がある場合には、エラーにつながる可能性があります。例えば、画面のピクセル座標と偶然一致する可能性のある緯度・経度の座標を考える場合などです。

公称的型付け

公称的型システムでは、型は同じ名前を持つ場合にのみ互換性があると見なされます。2つの型が同じ構造を持っていても、名前が異なれば別個のものとして扱われます。JavaやC#のような言語は公称的型付けを使用しています。

Branded Typeの必要性

TypeScriptの構造的型付けは、値がその構造に関係なく特定の型に属することを保証する必要がある場合に問題となることがあります。例えば、通貨を表現する場合を考えてみましょう。USDとEURに異なる型があるかもしれませんが、どちらも数値として表現される可能性があります。これらを区別する仕組みがなければ、誤って異なる通貨で操作を行ってしまうかもしれません。

Branded Typeは、構造的には似ているが型システムによって異なると扱われる、明確な型を作成できるようにすることで、この問題に対処します。これにより、型安全性が向上し、そうでなければ見過ごされる可能性のあるエラーを防ぐことができます。

TypeScriptでのBranded Typeの実装

Branded Typeは、交差型と一意のシンボルまたは文字列リテラルを使用して実装されます。その考え方は、型に「ブランド」を追加して、同じ構造を持つ他の型と区別することです。

シンボルの使用（推奨）

シンボルは一意であることが保証されているため、ブランディングにシンボルを使用することが一般的に推奨されます。


const USD = Symbol('USD');
type USD = number & { readonly [USD]: unique symbol };

const EUR = Symbol('EUR');
type EUR = number & { readonly [EUR]: unique symbol };

function createUSD(value: number): USD {
  return value as USD;
}

function createEUR(value: number): EUR {
  return value as EUR;
}

function addUSD(a: USD, b: USD): USD {
  return (a + b) as USD;
}

const usd1 = createUSD(10);
const usd2 = createUSD(20);
const eur1 = createEUR(15);

const totalUSD = addUSD(usd1, usd2);
console.log("USD合計:", totalUSD);

// 次の行のコメントを解除すると、型エラーが発生します
// const invalidOperation = addUSD(usd1, eur1);

この例では、USDとEURはnumber型に基づくBranded Typeです。unique symbolは、これらの型が明確に異なることを保証します。createUSDおよびcreateEUR関数はこれらの型の値を作成するために使用され、addUSD関数はUSD値のみを受け入れます。EUR値をUSD値に加算しようとすると、型エラーが発生します。

文字列リテラルの使用

ブランディングに文字列リテラルを使用することもできますが、文字列リテラルは一意であることが保証されていないため、このアプローチはシンボルを使用するよりも堅牢ではありません。


type USD = number & { readonly __brand: 'USD' };
type EUR = number & { readonly __brand: 'EUR' };

function createUSD(value: number): USD {
  return value as USD;
}

function createEUR(value: number): EUR {
  return value as EUR;
}

function addUSD(a: USD, b: USD): USD {
  return (a + b) as USD;
}

const usd1 = createUSD(10);
const usd2 = createUSD(20);
const eur1 = createEUR(15);

const totalUSD = addUSD(usd1, usd2);
console.log("USD合計:", totalUSD);

// 次の行のコメントを解除すると、型エラーが発生します
// const invalidOperation = addUSD(usd1, eur1);

この例は前の例と同じ結果を達成しますが、シンボルの代わりに文字列リテラルを使用しています。よりシンプルですが、ブランディングに使用される文字列リテラルがコードベース内で一意であることを確認することが重要です。

実践的な例とユースケース

Branded Typeは、構造的な互換性を超えて型安全性を強制する必要があるさまざまなシナリオに適用できます。

ID

UserID、ProductID、OrderIDなど、さまざまな種類のIDを持つシステムを考えてみましょう。これらのIDはすべて数値または文字列として表現されるかもしれませんが、異なる種類のIDが誤って混同されるのを防ぎたいとします。


const UserIDBrand = Symbol('UserID');
type UserID = string & { readonly [UserIDBrand]: unique symbol };

const ProductIDBrand = Symbol('ProductID');
type ProductID = string & { readonly [ProductIDBrand]: unique symbol };

function getUser(id: UserID): { name: string } {
  // ... ユーザーデータを取得
  return { name: "Alice" };
}

function getProduct(id: ProductID): { name: string, price: number } {
  // ... 製品データを取得
  return { name: "サンプル製品", price: 25 };
}

function createUserID(id: string): UserID {
  return id as UserID;
}

function createProductID(id: string): ProductID {
  return id as ProductID;
}

const userID = createUserID('user123');
const productID = createProductID('product456');

const user = getUser(userID);
const product = getProduct(productID);

console.log("ユーザー:", user);
console.log("製品:", product);

// 次の行のコメントを解除すると、型エラーが発生します
// const invalidCall = getUser(productID);

この例は、Branded TypeがProductIDをUserIDを期待する関数に渡すことを防ぎ、型安全性を向上させる方法を示しています。

ドメイン固有の値

Branded Typeは、制約を持つドメイン固有の値を表現するのにも役立ちます。例えば、常に0から100の間でなければならないパーセンテージの型を持つことができます。


const PercentageBrand = Symbol('Percentage');
type Percentage = number & { readonly [PercentageBrand]: unique symbol };

function createPercentage(value: number): Percentage {
  if (value < 0 || value > 100) {
    throw new Error('パーセンテージは0から100の間でなければなりません');
  }
  return value as Percentage;
}

function applyDiscount(price: number, discount: Percentage): number {
  return price * (1 - discount / 100);
}

try {
  const discount = createPercentage(20);
  const discountedPrice = applyDiscount(100, discount);
  console.log("割引後価格:", discountedPrice);

  // 次の行のコメントを解除すると、実行時エラーが発生します
  // const invalidPercentage = createPercentage(120);
} catch (error) {
  console.error(error);
}

この例は、実行時にBranded Typeの値に制約を強制する方法を示しています。型システムはPercentageの値が常に0から100の間であることを保証できませんが、createPercentage関数は実行時にこの制約を強制できます。io-tsのようなライブラリを使用して、Branded Typeの実行時検証を強制することもできます。

日付と時刻の表現

日付や時刻の扱いは、さまざまな形式やタイムゾーンがあるため、厄介なことがあります。Branded Typeは、異なる日付と時刻の表現を区別するのに役立ちます。


const UTCDateBrand = Symbol('UTCDate');
type UTCDate = string & { readonly [UTCDateBrand]: unique symbol };

const LocalDateBrand = Symbol('LocalDate');
type LocalDate = string & { readonly [LocalDateBrand]: unique symbol };

function createUTCDate(dateString: string): UTCDate {
  // 日付文字列がUTC形式（例：Z付きのISO 8601）であることを検証
  if (!/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z/.test(dateString)) {
    throw new Error('無効なUTC日付形式です');
  }
  return dateString as UTCDate;
}

function createLocalDate(dateString: string): LocalDate {
  // 日付文字列がローカル日付形式（例：YYYY-MM-DD）であることを検証
  if (!/\d{4}-\d{2}-\d{2}/.test(dateString)) {
    throw new Error('無効なローカル日付形式です');
  }
  return dateString as LocalDate;
}

function convertUTCDateToLocalDate(utcDate: UTCDate): LocalDate {
  // タイムゾーン変換を実行
  const date = new Date(utcDate);
  const localDateString = date.toLocaleDateString();
  return createLocalDate(localDateString);
}

try {
  const utcDate = createUTCDate('2024-01-20T10:00:00.000Z');
  const localDate = convertUTCDateToLocalDate(utcDate);
  console.log("UTC日付:", utcDate);
  console.log("ローカル日付:", localDate);
} catch (error) {
  console.error(error);
}

この例はUTCとローカルの日付を区別し、アプリケーションのさまざまな部分で正しい日付と時刻の表現を使用していることを保証します。実行時の検証により、正しくフォーマットされた日付文字列のみがこれらの型に割り当てられることが保証されます。

Branded Typeを使用するためのベストプラクティス

TypeScriptでBranded Typeを効果的に使用するために、以下のベストプラクティスを検討してください。

Branded Typeの利点

Branded Typeの欠点

Branded Typeの代替案

Branded TypeはTypeScriptで公称的型付けを実現するための強力な手法ですが、検討すべき代替アプローチもあります。

Opaque Type（不透明型）

Opaque TypeはBranded Typeに似ていますが、基になる型をより明示的に隠す方法を提供します。TypeScriptにはOpaque Typeの組み込みサポートはありませんが、モジュールとプライベートシンボルを使用してシミュレートできます。

クラス

クラスを使用すると、明確な型を定義するためのよりオブジェクト指向なアプローチを提供できます。TypeScriptではクラスは構造的に型付けされますが、関心の分離をより明確にし、メソッドを通じて制約を強制するために使用できます。

`io-ts`や`zod`のようなライブラリ

これらのライブラリは、高度な実行時型検証を提供し、Branded Typeと組み合わせてコンパイル時と実行時の両方の安全性を保証することができます。

結論

TypeScriptのBranded Typeは、構造的型システムにおいて型安全性とコードの明確性を向上させるための貴重なツールです。型に「ブランド」を追加することで、公称的型付けを強制し、構造的に似ているが論理的に異なる型の意図しない混同を防ぐことができます。Branded Typeはいくつかの複雑さとオーバーヘッドを導入しますが、型安全性の向上とコードの保守性の向上という利点は、しばしば欠点を上回ります。値がその構造に関係なく特定の型に属することを保証する必要があるシナリオで、Branded Typeの使用を検討してください。

構造的型付けと公称的型付けの背後にある原則を理解し、この記事で概説されたベストプラクティスを適用することで、Branded Typeを効果的に活用して、より堅牢で保守性の高いTypeScriptコードを書くことができます。通貨やIDの表現から、ドメイン固有の制約の強制まで、Branded Typeはプロジェクトの型安全性を向上させるための柔軟で強力なメカニズムを提供します。

TypeScriptを扱う際には、型検証と強制のために利用可能なさまざまなテクニックやライブラリを探求してください。型安全性への包括的なアプローチを実現するために、Branded Typeをio-tsやzodのような実行時検証ライブラリと組み合わせて使用することを検討してください。