JSON→TypeScript変換時の日付文字列の扱い方

JSONとTypeScriptにおける日付

JSONにはネイティブの日付型がありません。日付は通常ISO 8601形式（"2024-03-15T10:30:00Z"）の文字列として送信されます。これはTypeScriptに変換する際にギャップを生み出します。

JSON例

{
  "id": 1,
  "title": "Launch v2",
  "createdAt": "2024-03-15T10:30:00Z",
  "dueDate": "2024-04-01",
  "completedAt": null
}

オプション1：プレーンString（デフォルト）

interface Task {
  id: number;
  title: string;
  createdAt: string;
  dueDate: string;
  completedAt: string | null;
}

これは最も安全なデフォルトです。JSON.parse()は日付値に対して文字列を返すためです。情報は失われませんが、日付文字列と他の文字列を型レベルで区別できません。

オプション2：ブランド型

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

interface Task {
  id: number;
  title: string;
  createdAt: ISODateString;
  dueDate: ISODateString;
  completedAt: ISODateString | null;
}

ブランド型は、通常の文字列を日付フィールドに誤って代入することを防ぎます。const d = "2024-03-15T10:30:00Z" as ISODateStringのようなヘルパーで値を作成します。

オプション3：Dateオブジェクト型

interface Task {
  id: number;
  title: string;
  createdAt: Date;
  dueDate: Date;
  completedAt: Date | null;
}

これは、パース後に文字列をDateオブジェクトに変換するデシリアライゼーションステップ（例：Zodスキーマやカスタムreviver）がある場合にのみ機能します。生のJSON.parse()出力はこのinterfaceに一致しません。

推奨事項

生成される型にはプレーンstringを使用し、日付文字列をDateオブジェクトに変換するパース/バリデーション層（Zod、io-ts、またはカスタムトランスフォーマー）を追加してください。これにより、シリアライゼーションの安全性とランタイムの正確性の両方が得られます。