Back to Details

zodipus

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zodipus

Zodipus

Type-safe Zod schema generator for Prisma with composable Query Engine.
为Prisma打造的支持可组合查询引擎的类型安全Zod Schema生成器。

When to Apply

适用场景

  • User mentions "zodipus" anywhere in conversation
  • User wants Zod schemas generated from Prisma
  • User needs runtime validation for Prisma queries
  • User asks about type-safe query builders
  • User has Prisma + Zod integration questions
  • User mentions "prisma-zod" or similar terms
  • 用户在对话中任何位置提及"zodipus"
  • 用户需要从Prisma生成Zod Schema
  • 用户需要为Prisma查询提供运行时验证
  • 用户询问类型安全的查询构建器相关内容
  • 用户有Prisma + Zod集成相关问题
  • 用户提及"prisma-zod"或类似术语

Quick Routing

快速路由指引

User IntentSkill
Install, setup, configure generator
zodipus-setup
Query engine, createRegistry, type-safe queries
zodipus-query-engine
JSON fields, @zodSchema, custom schemas
zodipus-custom-schemas
Errors, validation failed, not working
zodipus-troubleshooting
Migrate from other generators
zodipus-migration
用户意图对应技能
安装、设置、配置生成器
zodipus-setup
查询引擎、createRegistry、类型安全查询
zodipus-query-engine
JSON字段、@zodSchema、自定义Schema
zodipus-custom-schemas
错误、验证失败、功能异常
zodipus-troubleshooting
从其他生成器迁移
zodipus-migration

Core Concepts

核心概念

1. Generator

1. 生成器

Zodipus is a Prisma generator that outputs Zod schemas:
prisma
generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}
Zodipus是一款Prisma生成器，可输出Zod Schema：
prisma
generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

2. Clean Schemas

2. 精简Schema

Generated schemas contain scalar fields only (no relations). This keeps validation fast and focused:
typescript
// Generated UserSchema validates: id, email, name, role, createdAt, updatedAt
// Does NOT include: posts, comments, profile (relations)
const user = UserSchema.parse(data);
生成的Schema仅包含标量字段（不包含关联关系）。这能让验证更快速、更聚焦：
typescript
// 生成的UserSchema会验证：id、email、name、role、createdAt、updatedAt
// 不包含：posts、comments、profile（关联关系）
const user = UserSchema.parse(data);

3. Query Engine

3. 查询引擎

Build composable queries with automatic validation:
typescript
import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

const registry = createRegistry({ models, relations: modelRelations });
const userQuery = registry.createQuery('user');

const query = userQuery({
  select: { id: true, email: true },
  posts: { select: { title: true } }
});

const result = query.parse(await prisma.user.findFirst(query.query));
// Fully typed: { id: string; email: string; posts: { title: string }[] }
通过自动验证构建可组合查询：
typescript
import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

const registry = createRegistry({ models, relations: modelRelations });
const userQuery = registry.createQuery('user');

const query = userQuery({
  select: { id: true, email: true },
  posts: { select: { title: true } }
});

const result = query.parse(await prisma.user.findFirst(query.query));
// 完全类型化：{ id: string; email: string; posts: { title: string }[] }

4. Custom JSON Schemas

4. 自定义JSON Schema

Type Prisma JSON fields with 
@zodSchema
:
prisma
model Post {
  /// @zodSchema PostMetadataSchema
  metadata Json?
}
使用
@zodSchema
为Prisma JSON字段定义类型：
prisma
model Post {
  /// @zodSchema PostMetadataSchema
  metadata Json?
}

Minimal Working Example

最小可用示例

Step 1: Install

步骤1：安装

bash
npm install zodipus zod
bash
npm install zodipus zod

Step 2: Configure

步骤2：配置

prisma
generator client {
  provider = "prisma-client-js"
}

generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

model User {
  id    String @id @default(cuid())
  email String @unique
  name  String?
  posts Post[]
}

model Post {
  id       String  @id @default(cuid())
  title    String
  author   User    @relation(fields: [authorId], references: [id])
  authorId String
}
prisma
generator client {
  provider = "prisma-client-js"
}

generator zodipus {
  provider = "zodipus"
  output   = "./generated"
}

model User {
  id    String @id @default(cuid())
  email String @unique
  name  String?
  posts Post[]
}

model Post {
  id       String  @id @default(cuid())
  title    String
  author   User    @relation(fields: [authorId], references: [id])
  authorId String
}

Step 3: Generate

步骤3：生成

bash
npx prisma generate
bash
npx prisma generate

Step 4: Use

步骤4：使用

typescript
import { UserSchema, PostSchema } from './generated';
import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

// Direct validation
const user = UserSchema.parse(userData);

// Query with validation
const registry = createRegistry({ models, relations: modelRelations });
const query = registry.createQuery('user')({
  select: { id: true, email: true, name: true }
});

const users = await prisma.user.findMany(query.query);
const validated = query.array().parse(users);
typescript
import { UserSchema, PostSchema } from './generated';
import { createRegistry } from 'zodipus/queryEngine';
import { models, modelRelations } from './generated/generated-index';

// 直接验证
const user = UserSchema.parse(userData);

// 带验证的查询
const registry = createRegistry({ models, relations: modelRelations });
const query = registry.createQuery('user')({
  select: { id: true, email: true, name: true }
});

const users = await prisma.user.findMany(query.query);
const validated = query.array().parse(users);

Generated Files

生成的文件

After running 
prisma generate
, Zodipus creates:
FileContents
enums.ts
Prisma enums as Zod schemas
models.ts
Clean model schemas (no relations)
custom-schemas.ts
Placeholder for @zodSchema definitions
generated-relations.ts
Relation metadata for Query Engine
generated-index.ts
Re-exports and convenience exports
运行
prisma generate
后，Zodipus会创建以下文件：
文件内容
enums.ts
以Zod Schema形式呈现的Prisma枚举
models.ts
精简的模型Schema（无关联关系）
custom-schemas.ts
@zodSchema定义的占位文件
generated-relations.ts
供查询引擎使用的关联关系元数据
generated-index.ts
重导出及便捷导出内容

Priority Reference

优先级参考

PriorityFeatureWhen to Use
Critical
UserSchema.parse()
Validate any model data
Critical
createRegistry()
Set up Query Engine
High
query.array().parse()
Validate findMany results
High
query.safeParse()
Handle errors without throwing
Medium
@zodSchema
annotation		Type JSON fields
Medium
relationDepth
config		Deep nested queries
LowCLI inspect commandDebug schema issues
优先级功能适用场景
关键
UserSchema.parse()
验证任意模型数据
关键
createRegistry()
配置查询引擎
高
query.array().parse()
验证findMany查询结果
高
query.safeParse()
处理错误但不抛出异常
中
@zodSchema
注解		为JSON字段定义类型
中
relationDepth
配置		深度嵌套查询
低CLI inspect命令调试Schema问题

Quick Reference

快速参考

See references/QUICK-REFERENCE.md for a complete cheat sheet.
完整速查表请查看references/QUICK-REFERENCE.md。