1
.transform(fn)              // 校验之后变形
2
z.preprocess(fn, schema)    // 校验之前预处理
3
.pipe(nextSchema)           // 把上一步的输出接给下一个 schema

1
const TagsSchema = z.string().transform(
2
  s => s.split(',').map(t => t.trim())
3
)
4

5
TagsSchema.parse('ai, zod, hono')
6
// ['ai', 'zod', 'hono']

1
type Tags = z.infer<typeof TagsSchema>
2
// string[]  ← 不是 string！

01
// 这是个 bad smell：把校验逻辑塞进 transform
02
const BadEmail = z.string().transform(s => {
03
  if (!s.includes('@')) throw new Error('not email')  // ❌ 不该在这里做
04
  return s.toLowerCase()
05
})
06

07
// 正确做法：校验用 refine 或内置方法，变形用 transform
08
const GoodEmail = z.string()
09
  .email()                        // 校验
10
  .transform(s => s.toLowerCase()) // 变形

01
const UserIdSchema = z.string().transform(
02
  async (id) => {
03
    const user = await db.user.findUnique({ where: { id } })
04
    return user
05
  }
06
)
07

08
// 含异步 transform 的 schema 必须用 parseAsync
09
const user = await UserIdSchema.parseAsync('u_xxx')
10
// user 的类型是 await 之后的结果类型

1
const PageSchema = z.preprocess(
2
  v => Number(v),     // 第一步：预处理
3
  z.number().int()    // 第二步：用这个 schema 校验
4
)
5

6
PageSchema.parse('2')    // ✅ 2
7
PageSchema.parse('abc')  // 💥 Number('abc') 是 NaN，schema 会拒绝

1
z.coerce.number()
2
// 等价于：
3
z.preprocess(v => Number(v), z.number())

1
const FeaturesSchema = z.preprocess(
2
  v => typeof v === 'string' ? JSON.parse(v) : v,
3
  z.array(z.enum(['chat', 'rag', 'agent']))
4
)
5

6
// process.env.FEATURES = '["chat","rag"]'
7
FeaturesSchema.parse(process.env.FEATURES)
8
// ['chat', 'rag']

1
const schema = z.string()
2
  .pipe(z.coerce.number().int().min(0))
3

4
// 输入必须先是字符串，然后被 coerce 成数字并校验
5
schema.parse('42')   // ✅ 42
6
schema.parse(42)     // 💥 第一段就挂了（不是字符串）
7
schema.parse('abc')  // 💥 coerce 成 NaN，被 z.number() 拒绝（NaN 不合法）

1
const NormalizedEmail = z.string()
2
  .transform(s => s.trim().toLowerCase())   // 第一步：清洗
3
  .pipe(z.string().email())                 // 第二步：校验清洗后的结果

1
type In  = z.input<typeof schema>   // parse 能接受的类型
2
type Out = z.output<typeof schema>  // parse 返回的类型
3
// z.infer<T> 是 z.output<T> 的别名

01
const A = z.string()
02
// input: string, output: string
03

04
const B = z.string().default('anon')
05
// input: string | undefined, output: string
06

07
const C = z.string().transform(s => s.length)
08
// input: string, output: number
09

10
const D = z.preprocess(v => Number(v), z.number())
11
// input: unknown, output: number
12

13
const E = z.coerce.number()
14
// input: unknown, output: number

01
const CreatePostSchema = z.object({
02
  title: z.string(),
03
  tags: z.string().transform(s => s.split(',').map(t => t.trim())),
04
  publishAt: z.coerce.date().default(() => new Date()),
05
})
06

07
// 前端要发的 JSON 长这样：
08
type CreatePostRequest = z.input<typeof CreatePostSchema>
09
// { title: string; tags: string; publishAt?: string | number | Date | undefined }
10

11
// 业务函数内部拿到的对象长这样：
12
type CreatePost = z.output<typeof CreatePostSchema>
13
// { title: string; tags: string[]; publishAt: Date }

1
const CleanEmail = z.string()
2
  .transform(s => s.trim().toLowerCase())
3
  .pipe(z.string().email())

1
const TagsFromCsv = z.string()
2
  .transform(s => s.split(',').map(t => t.trim()).filter(Boolean))
3
  .pipe(z.array(z.string().min(1)))

1
const JsonConfig = <T extends z.ZodTypeAny>(schema: T) =>
2
  z.preprocess(
3
    v => typeof v === 'string' ? JSON.parse(v) : v,
4
    schema
5
  )
6

7
const Features = JsonConfig(z.array(z.string()))
8
Features.parse('["chat","rag"]')  // ['chat', 'rag']

01
const stripFence = (s: string) =>
02
  s.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '').trim()
03

04
const LLMJsonSchema = <T extends z.ZodTypeAny>(shape: T) =>
05
  z.string()
06
    .transform(stripFence)
07
    .transform(s => JSON.parse(s))
08
    .pipe(shape)
09

10
// 用法：
11
const AnalysisSchema = LLMJsonSchema(z.object({
12
  summary: z.string(),
13
  keywords: z.array(z.string()),
14
}))
15

16
AnalysisSchema.parse('```json\n{"summary":"hi","keywords":["a"]}\n```')
17
// { summary: 'hi', keywords: ['a'] }