mcpField
P
prisma-json-types-generator

prisma-json-types-generator

github.com/arthurfiorette開発57156 回インストール2 週間前に更新
リポジトリ

prisma-json-types-generator について

Prisma のフィールドにスキーマコメントで TypeScript 型を割り当てるコーディングスキルです。スキーマや名前空間の編集、型生成と確認に加え、TypedSQL の注釈にも対応します。

主な機能

  1. 01Json、String、String[]、Int、Float の型指定
  2. 02名前空間型またはインライン型の利用
  3. 03トリプルスラッシュコメントによるフィールド指定
  4. 04TypedSQL の結果とパラメーターの型指定
  5. 05設定とトラブルシューティングの案内

活用シーン

  1. 01Prisma の JSON フィールドへの型追加
  2. 02複数フィールドで共有する名前付き型の定義
  3. 03TypedSQL の列とパラメーターへの注釈
  4. 04生成型が適用されない原因の調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/arthurfiorette/prisma-json-types-generator --skill prisma-json-types-generator

インストール後、Claude Code で/prisma-json-types-generatorを入力して読み込まれたか確認します。

同梱ファイルreferences/setup.md

詳細

prisma-json-types-generator

このジェネレーターは、スキーマ内のコメントをもとに、Prisma の Json、String、String[]、Int、Float フィールドに TypeScript 型を設定します。prisma generate が出力する型のみを書き換えます。実行時やデータベースでは何も検証されません。

ワークフロー

  1. 該当する Prisma スキーマと、存在する場合は PrismaJson 名前空間を宣言しているファイルを読みます。名前空間の宣言が読み込まれない場合に限り、tsconfig.json を読みます。
  2. ジェネレーターがインストールされていない場合や、設定に問題がある場合は、フィールドを編集する前に references/setup.md を読みます。
  3. フィールドに名前空間の型を使うか、インライン型を使うか選びます。
  4. フィールドの直上に /// コメントを追加するか、修正します。
  5. 名前空間の型を使う場合は、その宣言を追加または更新します。
  6. 可能であれば、prisma generate（プロジェクトで TypedSQL を使う場合は prisma generate --sql）と、プロジェクトの型チェックを実行します。

ユーザーが指定したフィールドのみを変更します。

名前空間の型またはインライン型

/// [TypeName] は、設定された名前空間（デフォルトでは PrismaJson）にある TypeName を参照します。オブジェクト、複数のフィールドで共有する型、後で Zod スキーマを追加する可能性があるものに使います。

/// ![Type] は、スキーマに記述された TypeScript 型式を使います。短いリテラルユニオンや、小規模で一度しか使わないオブジェクトに使います。

model Post {
  /// [PostMeta]
  meta Json

  /// !['draft' | 'published' | 'archived']
  status String

  /// ![1 | 2 | 3]
  rank Int

  /// ![{ width: number; height: number }]
  dimensions Json
}

名前空間の宣言ファイルは、tsconfig.json に含まれるモジュールである必要があります。型自体はどこに定義してもよく、名前空間にエイリアスとして追加できます。

import type { PostMeta as DomainPostMeta } from './domain/post-meta';

declare global {
  namespace PrismaJson {
    type PostMeta = DomainPostMeta;
  }
}

import のない宣言ファイルは、モジュールとして扱われるように export {}; が必要です。

フィールドのルール

  • コメントには /// を使います。Prisma は、ジェネレーターが読み取る DMMF から通常の // コメントを除外します。
  • コメントは、型を指定するフィールドの直上に置きます。
  • Prisma は NULL 許容性とリストのラッパーを維持するため、型には単一の要素を記述します。tags Json[] には /// [Tag] を使います。/// ![Tag[]] のような配列型は、保存値が JSON 配列である通常の Json フィールドに指定します。
  • NULL 許容フィールド（Json?、String?、Int?、Float?）と String[] にも、同じコメントを指定します。
  • MongoDB の複合 type ブロックのフィールドも、モデルフィールドと同じ方法で型を指定できます。
  • 型が指定されていない Json フィールドは、ジェネレーターが allowAny または useType を設定しない限り、unknown に解決されます。

TypedSQL

prisma generate --sql を使うと、ジェネレーターは prisma-client と prisma-client-js の両方で、TypedSQL の結果とパラメーターにも型を設定します。

PostgreSQL では、テーブル列から直接読み取る結果列に、スキーマフィールドの型が設定されます。エイリアス、JOIN、サブクエリ、CTE を通しても適用されます。照合では各列のソースをデータベースに問い合わせ、名前同士を比較することはありません。pg パッケージと、DATABASE_URL または typedSqlUrlEnv オプションで指定された変数内の接続 URL が必要です。これらがない場合、ジェネレーターは警告を表示し、.sql の注釈のみを適用します。

計算列と、その他のデータベース上のすべての列には、.sql ファイルの -- コメントを使って型を指定します。通常の構文の後に、返される列名を記述します。これらの注釈は、スキーマフィールドの型を上書きします。パラメーターの型は、@param の説明の先頭に記述します。

-- [UserStats] stats
-- ![{ total: number }] "Total Count"
-- @param {Json} $1:filter [PostFilter]
SELECT
  json_build_object('posts', count(*)) AS stats,
  json_build_object('total', count(*)) AS "Total Count"
FROM "Post"
WHERE meta @> $1

PostgreSQL は引用符で囲まれていない列名を小文字に変換します（AS Stats は stats を返します）。注釈には、返される名前を使う必要があります。クエリがスキーマと同じ場所の sql/ にない場合は、typedSqlPath オプションを設定します。

トラブルシューティング

フィールドが JsonValue、unknown、または単純なスカラー型のままの場合は、次の順に確認してください。

  1. provider = "prisma-json-types-generator" を指定したジェネレーターブロックが存在すること。
  2. コメントが /// で始まり、フィールドのすぐ上にあること。
  3. namespace オプションが TypeScript で宣言された名前空間と一致していること。
  4. 宣言ファイルがモジュールであり、tsconfig.json に含まれていること。
  5. スキーマの変更後に prisma generate を実行したこと。ジェネレーターのエラーや警告が出力されても、コマンドが正常終了する場合があります。そのため、出力を確認してください。
  6. TypedSQL の場合、--sql が渡されていること、pg がインストールされていること、URL 変数が設定されていること、アノテーション名が返される列名と一致していること。

JsonFilter と JsonWithAggregatesFilter は、意図的に型付けされていません。フィルター入力に型を付けようとしないでください。

作業の仕上げ

  • ワークスペースが利用可能な場合は、変更案を提示するだけでなく、ファイルを編集してください。
  • 差分は、関連するスキーマファイルと型宣言ファイルに限定してください。
  • 変更内容と実行した検証コマンドを報告してください。実行できなかった場合は、その旨を伝えてください。

コメント

Markdown 対応