【テクニカル・上級編】プリミティブ型のサブタイプ化：リテラル型で実現するドメイン駆動設計の第一歩 – TypeScript コア・型システムの基礎解析バイブル

プリミティブの迷妄を断つ：リテラル型によるコンパイル時ドメイン防壁の構築

TypeScriptを単なる「JavaScriptに型アノテーションをつけるための安全弁」と考えているうちは、この言語の真の底力には到達できない。TypeScriptの型システムは、コードが1バイトたりともV8のヒープにロードされる前、すなわちAST（抽象構文木）の構築から型検査のフェーズにおいて、純粋な論理演算を行う「静的コンパイル時メタプログラミング環境」である。

今回は、最も身近であり、かつ最も無防備に使われがちである「プリミティブ型（`string`や`number`）」を題材にする。これらを如何にして厳密な「リテラル型」へと昇華させ、ドメイン駆動設計（DDD）におけるビジネスロジックの破綻をコンパイルエラーとして完全封鎖するか。その極限の知見を紐解く。

—

1. プリミティブ型という「トロイの木馬」

次のようなコードを見慣れていないだろうか。

type UserId = string;
type OrderStatus = string;

function processOrder(userId: UserId, status: OrderStatus): void {
// …
}

// 呼び出し側
const currentStatus = “SHIPPED”;
const userId = “usr_9981273”;

processOrder(currentStatus, userId); // 💥 引数の順番が逆だが、コンパイルは完璧に通る

何が起きているか。`UserId`も`OrderStatus`も、実体は単なる`string`のエイリアス（名目上の別名ではなく、単なる構造的互換の別名）に過ぎない。TypeScriptの型チェッカーは、これらを全く同一のプリミティブとして評価する。結果として、引数の順序間違いや、ドメイン概念の異なる文字列の混入は、ランタイムエラー（あるいはサイレントバグ）として本番環境へ直行する。

これはV8のメモリレイアウト上、すべての文字列がポインタとしてヒープ上にアロケートされ、型システムがその意味論（Semantics）を完全に放棄していることに起因する。我々はこの怠惰を断ち切らねばならない。

—

2. ブランテッド型（Branded Types）による名目型シミュレーション

TypeScriptは本質的に「構造的型付け（Structural Subtyping）」を採用している。しかし、ドメイン駆動設計における「ID」や「ステータス」は、値の構造（stringであること）ではなく、その文脈における一意性（Identity）が重要である。

ここで、リテラル型と交差型（Intersection Types）を組み合わせた「ブランテッド型（Branded Types / Tagged Types）」を導入する。

// コンパイル時の型検査でのみ存在する「ブランド（烙印）」を定義
declare const __brand: unique symbol;

type Brand = T & { [__brand]: TBrand };

// ドメインプリミティブの厳密な定義
type UserId = Brand;
type OrderId = Brand;
type OrderStatus = Brand<"PENDING" | "PAID" | "SHIPPED" | "CANCELLED", "OrderStatus">;

この型評価の裏側

`unique symbol` は、プログラム全体で決して重複しない一意のメモリ参照キーを生成する。これにより、通常の`string`と交差されたオブジェクトは、ランタイム上は単なるプリミティブのままでありながら、コンパイラにとっては完全に隔離された別個の型として認識される。

ランタイムでのオーバーヘッドはゼロである。V8エンジンはこれを通常の文字列プリミティブ（あるいは最適化されたV8 String）として扱い、余計なオブジェクト生成によるGC（ガベージコレクション）のプレッシャーを与えることはない。

—

3. 型ガードとファクトリー関数による安全な境界防御

ブランテッド型を導入した場合の課題は、「ただの文字列（外部からのAPI入力やDBからのフェッチ結果）を、どうやって安全にブランド型へ昇格させるか」である。

ここで、TypeScriptのユーザー定義型ガード（User-Defined Type Guards）とアサーション関数を駆使する。

// 値の検証とブランディングを行うファクトリー関数
function createUserId(value: string): UserId {
// 厳密なUUID v4の正規表現検証
const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
if (!uuidV4Regex.test(value)) {
throw new TypeError(`Invalid UserId format: ${value}`);
}
// コンパイラを欺きつつ、ランタイムの型安全性を担保するキャスト
return value as unknown as UserId;
}

// ステータスの網羅的検証を伴う型ガード
function isOrderStatus(value: string): value is OrderStatus {
const validStatuses = [“PENDING”, “PAID”, “SHIPPED”, “CANCELLED”] as const;
return (validStatuses as readonly string[]).includes(value);
}

このアプローチにより、境界領域（API GatewayやDBドライバからのレスポンス）で一度バリデーションを通過したデータのみが、ドメイン層の厳格な型安全の世界へと足を踏み入れることが許される。

—

4. 状態遷移マトリクスをリテラル型でコンパイル時に硬化する

ドメイン駆動設計における最大の難所の一つが「ライフサイクルを持つステータス管理」である。例えば、「キャンセル済みの注文を発送することはできない」といったビジネスルールを、if文の迷宮ではなく、型システムそのものに刻み込む。

// 許可される状態遷移の定義（型レベルのマトリクス）
type AllowedTransitions = {
PENDING: “PAID” | “CANCELLED”;
PAID: “SHIPPED” | “CANCELLED”;
SHIPPED: never; // 終端状態
CANCELLED: never; // 終端状態
};

function transitionOrderStatus(
currentStatus: Brand,
nextStatus: AllowedTransitions[TCurrent]
): Brand {
// ランタイムでの遷移処理（実際にはDB更新などが入る）
console.log(`Transitioning from ${currentStatus} to ${nextStatus}`);
return nextStatus as unknown as Brand;
}

// — 使用例のシミュレーション —

// 1. PENDING状態の作成
const initialStatus = “PENDING” as unknown as OrderStatus;

// 2. PENDING -> PAID は許可されているため正常にコンパイル・実行される
const paidStatus = transitionOrderStatus(initialStatus, “PAID”);

// 3. PAID -> SHIPPED も許可されている
const shippedStatus = transitionOrderStatus(paidStatus, “SHIPPED”);

// 4. SHIPPED -> PENDING は不可能なため、コンパイルエラーが発生する！
// 💥 Type ‘”PENDING”‘ is not assignable to type ‘never’.
// const invalidStatus = transitionOrderStatus(shippedStatus, “PENDING”);

なぜこれが強力なのか

`AllowedTransitions[TCurrent]` というインデクストラクト型により、コンパイラは現在のステータス (`TCurrent`) に応じて、次に許可されるリテラル型の範囲を動的に絞り込む。終端状態である `SHIPPED` が渡された場合、許容される次の状態は `never` となり、いかなる文字列を渡そうともコンパイルエラーが即座に火を噴く。

テストコードを書くまでもなく、エディタを開いた瞬間にビジネスロジックの違反が検知される。これが、チーフアーキテクトが目指す「静的保証の極致」である。

—

5. イベントループと非同期境界における型の伝播

最後に、Node.jsのイベントループにおける非同期処理（Promiseやマイクロタスクキュー）を通過する際の型挙動について触れておく。

非同期境界を越える際、TypeScriptの型推論は時にプリミティブの widening（型の広がり、例: `Literal` 型が `string` に格下げされる現象）を引き起こす。

async function fetchUserOrderStatus(userId: UserId): Promise {
// 非同期I/Oのシミュレーション
const rawStatus = await db.query(…);

// ここで単に `return rawStatus as OrderStatus;` と書くのは危険。
// ランタイムの信頼性を担保するため、必ず型ガードを通す必要がある。
if (!isOrderStatus(rawStatus)) {
throw new Error(“Corrupted state detected in storage layer.”);
}

return rawStatus; // この時点で確実に OrderStatus (リテラル共用体) に絞り込まれる
}

V8のイベントループにおいて、マイクロタスクキュー（`Promise.then` や `queueMicrotask`）にプッシュされるクロージャ内であっても、ブランテッド型とリテラル型は厳密に追跡される。非同期処理の上下左右どこを通ろうとも、一度付与されたドメインの防壁が剥がれることはない。

—

総括：コードはドメインの鏡でなければならない

型システムは、単なるバグよけのボルトではない。それは開発チームが共有する「ドメインモデルの共通言語（Ubiquitous Language）」を、機械が理解可能な厳密な物理法則へと翻訳するための装置である。

`string` や `number` というプリミティブの泥沼から脱却し、リテラル型とブランテッド型を組み合わせた鉄壁の型防壁を築き上げること。それこそが、大規模かつ持続可能なシステムアーキテクチャを構築する唯一の道である。

コンパイラを味方につけろ。妥協のない型設計が、あなたのコードベースを永遠の堅牢性へと導くだろう。