TypeScriptの型をJSONに変換!

TypeScriptのinterfaceを入力するとサンプルJSONを作ります!TypeScript interface, type 対応。API ドキュメントやテスト用のリクエストボディ(sample JSON)に。
TypeScript
結果
 

TypeScriptの型をJSONに変換!

TypeScript の interface、type エイリアス、enum、クラスの宣言を貼り付けると、それを満たす例の JSON ドキュメントが得られます。リテラルのユニオン、Record、Pick・Omit・Partial のようなユーティリティ型、extends でつないだインターフェースもすべてたどって埋めます。

API ができる前に MSW や json-server のモックデータを用意するとき、Storybook の props を作るとき、バックエンドのチームに送ってほしい形を正確に示すときに使ってください。

使い方

  1. types.ts のようなファイルから型宣言を貼り付けます。export、import、関数宣言が混ざっていても構わず、読み取るのは型宣言だけです。
  2. 参照している型や enum も含めると値が埋まります。入力にない型名は null になります。
  3. オプションはありません。他の宣言から参照されていない最初のオブジェクト型がルートになるので、目的の型を先頭に置いてください。type UserPage = Page<User> のようにジェネリクスを埋めたエイリアスは、ジェネリクスの宣言そのものより優先されます。
  4. 結果をコピーして MSW ハンドラーの HttpResponse.json(...)、テストフィクスチャ、Storybook の args に入れ、値を調整します。

例

入力 (TypeScript)
type Channel = "email" | "sms" | "push";

enum Priority { Low = "low", High = "high" }

interface Notification {
  id: string;
  channel: Channel;
  priority: Priority;
  recipient: { userId: number; locale?: string };
  payload: Record<string, string>;
  readAt: Date | null;
  meta: Pick<Audit, "createdBy">;
}

interface Audit { createdBy: string; createdAt: Date }
出力 (JSON)
{
  "id": "",
  "channel": "email",
  "priority": "low",
  "recipient": {
    "userId": 0,
    "locale": ""
  },
  "payload": {
    "key": ""
  },
  "readAt": "1970-01-01T00:00:00.000Z",
  "meta": {
    "createdBy": ""
  }
}

Channel は文字列リテラルのユニオンなので最初の値 "email" を、文字列 enum の Priority は最初のメンバーの値 "low" を取ります。Record<string, string> は "key" を1つだけ持つオブジェクトになり、Date | null は null でない側に解決されて ISO 文字列になり、Pick<Audit, "createdBy"> は選んだキーだけを残します。省略可能な locale? も含まれています。

対応機能

  • プリミティブ: string → ""、number/bigint → 0、boolean → false、any/unknown → null、Date → 1970-01-01T00:00:00.000Z(Date.toJSON() の形式)。
  • リテラル型はその値を使い、ユニオンは null/undefined でない最初のメンバーを取り、交差型(A & B)と interface ... extends はプロパティをまとめます。
  • enum は最初のメンバーの値を使い、初期化子のない数値 enum なら 0 を使います。
  • 配列、Array<T>、Set<T> は要素を1つ持ち、タプルは位置ごとに値を持ちます。Record<K, V>、Map、インデックスシグネチャは {"key": V} になります。
  • ユーティリティ型の Partial、Required、Readonly、NonNullable、Pick、Omit に対応しています。
  • メソッドや関数型のプロパティは JSON に存在しないので落とします。クラスでは、static フィールド、get/set アクセサー、@Exclude() のフィールドを除外します。
  • 自己参照する配列(children: TreeNode[])は空の配列で打ち切ります。

利用シーン

MSW や json-server のモックレスポンス

バックエンドの準備ができる前に、API レスポンスの型からモックデータを生成できます。UI を先に作っておけて、あとで本物の API に切り替えても同じ型のままです。

Storybook やテスト用の props

コンポーネントの props の型から、ストーリーの args や React Testing Library の描画データに使うデフォルトのオブジェクトを作れます。必須のプロパティがすべてそろっているので、型エラーを追いかける必要がありません。

リクエスト形式をバックエンドとすり合わせる

フロントエンドのリクエスト型を JSON にして API 設計書や Issue に貼り付ければ、TypeScript を使わないバックエンドの開発者もすぐに構造を読み取れます。

注意点と制限

  • 省略可能なプロパティ(?)は常に含めます。それがない場合のレスポンスを試すときは、キーを自分で削除してください。
  • ジェネリクスのパラメーターは型が使われる場所で置き換えます。type UserPage = Page<User> なら items: T[] が User で埋まり、引数がなければ <T = string> のようなデフォルトが適用されます。ただし、ジェネリクス内の条件型は評価しません。
  • T["key"] のようなインデックスアクセス型、条件型、テンプレートリテラル型は評価しません。
  • 単一のリテラルで初期化したクラスのフィールド(name = "kim"、retries = 3)はその値を使い、new Date() のようなその他の初期化子は型のヒントとしてだけ使います。
  • Zod や io-ts のような実行時のスキーマコードは読み取りません。z.infer で推論される型を、普通のインターフェースとして書き出してください。
  • Map と Set はオブジェクトと配列で表示しますが、JSON.stringify はどちらも {} にしてしまうので、レスポンスの型には Record や配列を使うほうがよいでしょう。

よくある質問

Date が文字列で出てくるのは正しいですか?

正しいです。JSON.stringify は Date をその toJSON() の結果、つまり ISO 8601 の文字列に置き換えます。受け取る側にも文字列で届くので、string で型を付けるか、パースしてください。

status: "active" | "inactive" のようなユニオンにはどの値が入りますか?

宣言順で最初のリテラルである "active" です。別の値を見せたい場合はユニオンの順序を入れ替えてください。

NestJS の DTO クラスでも使えますか?

クラス宣言とデコレーターも解析するので、class-validator のデコレーターを付けた DTO も問題なく変換でき、class-transformer の @Exclude() のフィールドは除外されます。

JSON から TypeScript の型を作るには?

逆方向には JSON → TypeScript のページを使ってください。TypeORM、Sequelize、Mongoose のモデルから JSON を作る別のページもあります。