TypeORMのエンティティをJSONに変換!

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

TypeORMのエンティティをJSONに変換!

TypeORM のエンティティクラスを貼り付けると、そのエンティティを API から返したときにできる JSON の形を、仮の値で埋めて表示します。エンティティをそのままレスポンスで返している NestJS や Express のプロジェクトで、Swagger の例や、フロントエンドとすり合わせるリクエスト/レスポンスのサンプルが必要な場合を想定しています。

値は @Column のオプションではなく、各プロパティの TypeScript の型から作ります。そのため @Column({ type: "decimal" }) で宣言して price: number としたカラムは、数値の 0 で出力されます。

使い方

  1. TypeORM 欄にエンティティのファイルを貼り付けます。ネストしたオブジェクトを埋められるよう、関連エンティティや enum も含めてください。
  2. 結果 欄は入力に合わせて更新されます。他のエンティティから参照されていないエンティティがトップレベルの JSON オブジェクトになり、無関係なエンティティが複数あれば、それぞれがクラス名の下に表示されます。
  3. 結果の右上にあるコピーボタンか、Ctrl/⌘+Enter で JSON を取得します。

例

入力 (TypeORM)
enum Genre { Novel = "novel", Essay = "essay" }

@Entity()
export class Author {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;
}

@Entity()
export class Book {
  @PrimaryGeneratedColumn("uuid")
  id: string;

  @Column({ type: "enum", enum: Genre })
  genre: Genre;

  @Column({ type: "decimal", nullable: true })
  price: number | null;

  @ManyToOne(() => Author)
  author: Author;

  @Exclude()
  @Column()
  internalCode: string;
}
出力 (JSON)
{
  "id": "",
  "genre": "novel",
  "price": 0,
  "author": {
    "id": 0,
    "name": ""
  }
}

Book が Author を参照しているので Book がルートになり、author はその中にネストされます。internalCode は @Exclude() によって除外され、number | null 型の price は null 以外の最初の型に従って 0 になります。uuid の主キーは string 型なので空文字列です。

対応機能

  • @ManyToOne と @OneToOne のリレーションはネストしたオブジェクトに、@OneToMany や @ManyToMany の Post[] は要素1つの配列になります。
  • lazy リレーション(Promise<Post[]>)や ESM の Relation<User> ラッパーは、内側の型に展開します。
  • TypeScript の enum は最初のメンバーの値を使い、文字列 enum なら文字列、数値 enum なら数値になります。
  • class-transformer の @Exclude() を付けたフィールド、static フィールド、メソッド、getter は除外します。
  • (@CreateDateColumn などの)Date プロパティは 1970-01-01T00:00:00.000Z のような ISO 文字列になります。
  • Record<string, number> のように jsonb カラムでよく使う型は {"key": 0} として表示します。
  • エンティティが互いに参照している場合、ネストが有限で止まるよう、2回目の訪問は null や空の配列で打ち切ります。

利用シーン

NestJS コントローラーの Swagger の例

エンティティを直接返すコントローラーでも、@ApiResponse には例のペイロードが必要です。エンティティのファイルを貼り付けて、結果の仮の値を現実的なものに置き換えてください。

読み込んだリレーションの見え方を確認する

relations: ["author"] でクエリするとき、フロントエンドはレスポンスがどれだけ深くネストするかを知りたがります。出力を見れば、どのリレーションのフィールドがオブジェクトで、どれが配列かが一目瞭然です。

e2e テストのフィクスチャ

出力を supertest の POST 呼び出しのリクエストボディの骨組みに使えます。id やタイムスタンプのような生成されるフィールドを削除してから、残りを埋めてください。

注意点と制限

  • nullable、default、length のような @Column のオプションは読み取らず、値はプロパティの型かリテラルの初期化子(status = "draft")から作ります。カラムが null になりうるなら、その値を自分で null に変えてください。
  • 互いに参照していない複数の @Entity クラスはすべて変換し、クラス名をキーにして出力します({ "Book": {...}, "Author": {...} })。互いに参照しているエンティティは、引き続きネストしたルート1つになります。
  • 貼り付けずに import しているクラスはツールからは見えないため、null で表示されます。
  • ClassSerializerInterceptor と組み合わせて使う @Expose、シリアライズのグループ、@Transform は反映されません。

よくある質問

@PrimaryGeneratedColumn("uuid") が空文字列になるのはなぜですか?

値を決めるのはプロパティの型だけです。id: string なら "" になり、デコレーターの "uuid" 引数は読み取りません。ドキュメント用には、あとで UUID 形式の値に差し替えてください。

エンティティを送ったとき、API は本当にこれを返しますか?

すべて読み込まれたエンティティを JSON.stringify した結果と一致します。relations で読み込まなかったリレーションは実際のレスポンスには含まれないので、出力のリレーションのフィールドは読み込んだ場合のものとして扱ってください。

decimal のカラムが数値で表示されるのに、API は文字列を返します。なぜですか?

PostgreSQL や MySQL のドライバーは、精度の低下を避けるため decimal の値を文字列で返します。エンティティでプロパティを price: string と宣言すれば、出力も実際のデータと同じく文字列になります。