mcpField
P
prisma-json-types-generator

prisma-json-types-generator

github.com/arthurfiorette开发57156 次安装2 周前更新
代码仓库

关于 prisma-json-types-generator

这是一项为 Prisma 字段指定 TypeScript 类型的编码技能，通过 schema 注释实现。它指导字段与命名空间声明的修改、类型生成和检查，也涵盖 TypedSQL 注解。

主要功能

  1. 01为 Json、String、String[]、Int 和 Float 字段设类型
  2. 02使用命名空间或内联 TypeScript 类型
  3. 03通过三斜线注释标注字段
  4. 04为 TypedSQL 结果和参数设类型
  5. 05提供配置与故障排查指导

适用场景

  1. 01为 Prisma JSON 字段添加 TypeScript 类型
  2. 02在多个 schema 字段间复用命名类型
  3. 03标注 TypedSQL 列和参数
  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 字段设为取自 schema 注释的 TypeScript 类型。它只会重写 prisma generate 生成的类型。运行时和数据库都不会进行任何检查。

工作流

  1. 阅读相关的 Prisma schema；如果存在，还要阅读声明 PrismaJson 命名空间的文件。只有在未拾取命名空间声明时，才阅读 tsconfig.json。
  2. 如果尚未安装此生成器，或其配置看起来有问题，请先阅读 references/setup.md，再编辑字段。
  3. 为字段选择命名空间类型或内联类型。
  4. 在字段正上方添加或修正 /// 注释。
  5. 如果使用命名空间类型，请添加或更新其声明。
  6. 尽可能运行 prisma generate（如果项目使用 TypedSQL，则运行 prisma generate --sql）以及项目的类型检查。

只修改用户要求处理的字段。

命名空间类型或内联类型

/// [TypeName] 会在配置的命名空间中引用 TypeName，默认命名空间为 PrismaJson。此方式适用于对象、多个字段共享的类型，以及之后可能需要 Zod schema 的类型。

/// ![Type] 使用写在 schema 中的 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;
  }
}

不含任何导入语句的声明文件需要添加 export {};，才能保持为模块。

字段规则

  • 注释使用 ///。Prisma 不会将普通的 // 注释纳入生成器读取的 DMMF。
  • 注释必须紧挨在对应字段的上方。
  • Prisma 会保留可空性和列表包装，因此类型描述的是单个元素。使用 tags Json[] 并添加 /// [Tag]。/// ![Tag[]] 这样的数组类型应放在普通的 Json 字段上，该字段存储的是 JSON 数组。
  • 可空字段（Json?、String?、Int?、Float?）和 String[] 使用相同的注释。
  • MongoDB 复合 type 块中的字段也可以像模型字段一样设置类型。
  • 未设置类型的 Json 字段会解析为 unknown，除非生成器设置了 allowAny 或 useType。

TypedSQL

使用 prisma generate --sql 时，生成器还会为 TypedSQL 的结果和参数设置类型，适用于 prisma-client 和 prisma-client-js。

在 PostgreSQL 上，直接从表列读取的结果列会获得对应 schema 字段的类型，此规则适用于别名、联接、子查询和 CTE。匹配时，生成器会向数据库查询每列的来源，不会比较名称。此功能需要 pg 包和 DATABASE_URL 中的连接 URL，或者需要在 typedSqlUrlEnv 选项指定的变量中提供连接 URL。若未提供，生成器会发出警告，并且只应用 .sql 注释。

计算列以及其他数据库中的所有列，都需要在 .sql 文件中使用 -- 注释来指定类型：沿用常规语法，并在后面加上返回列的名称。这些注释会覆盖 schema 字段类型。参数类型需写在其 @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），注释必须使用返回的名称。如果查询不在 schema 同级的 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