@kood/claude-code 0.1.6 → 0.1.7

package/templates/tanstack-start/docs/library/zod/index.md

@@ -1,21 +1,25 @@
 # Zod
 
-> **Version**: 4.x | TypeScript Schema Validation
+> **v4** | TypeScript Schema Validation
+
+@basic-types.md
+@complex-types.md
+@transforms.md
+@validation.md
 
 ---
 
-## 🚀 Quick Reference (복사용)
+## Quick Reference
 
 ```typescript
 // 기본 스키마
 const schema = z.object({
-  email: z.email(),              // v4 (string().email() 아님!)
+  email: z.email(),              // v4! (string().email() 아님)
   name: z.string().min(1).trim(),
-  website: z.url().optional(),   // v4 (string().url() 아님!)
+  website: z.url().optional(),   // v4! (string().url() 아님)
   age: z.number().int().positive(),
 })
 
-// 타입 추출
 type Input = z.infer<typeof schema>
 
 // 파싱
@@ -28,159 +32,27 @@ export const createUser = createServerFn({ method: 'POST' })
   .handler(async ({ data }) => prisma.user.create({ data }))
 ```
 
-### v4 새 API (⚠️ 중요)
+### ⚠️ v4 새 API
 
 ```typescript
-// ✅ v4 사용
-z.email()
-z.url()
-z.uuid()
-z.iso.date()
-z.iso.datetime()
+// ✅ v4
+z.email()          z.url()          z.uuid()
+z.iso.date()       z.iso.datetime()
 
-// ❌ v3 (deprecated)
-z.string().email()
-z.string().url()
+// ❌ v3 deprecated
+z.string().email()  z.string().url()
 ```
 
----
-
-## 문서 구조
-
-- [기본 타입](./basic-types.md) - 문자열, 숫자, 불리언, 날짜
-- [복합 타입](./complex-types.md) - 객체, 배열, 튜플, 유니온, Enum
-- [변환](./transforms.md) - Transform, Coerce, Preprocess
-- [검증](./validation.md) - Refinement, Superrefine, 커스텀 검증
-
-## 빠른 시작
-
-```bash
-yarn add zod
-```
-
-### 기본 사용법
+### v4 주요 변경
 
 ```typescript
-import { z } from 'zod'
-
-// 스키마 생성
-const mySchema = z.string()
-
-// parsing (실패 시 에러 throw)
-mySchema.parse('tuna') // => "tuna"
-mySchema.parse(12) // => throws ZodError
-
-// safe parsing (에러를 던지지 않음)
-mySchema.safeParse('tuna') // => { success: true; data: "tuna" }
-mySchema.safeParse(12) // => { success: false; error: ZodError }
-```
-
-### 타입 추론
-
-```typescript
-import { z } from 'zod'
-
-const Player = z.object({
-  username: z.string(),
-  xp: z.number(),
-})
-
-// 스키마에서 타입 추출
-type Player = z.infer<typeof Player>
-
-// 타입 안전하게 사용
-const player: Player = { username: 'billie', xp: 100 }
-```
-
-## v4 주요 변경사항
-
-### 에러 커스터마이징 통합
-
-```typescript
-// v3 (deprecated)
-z.string().min(5, { message: "Too short." })
-z.string({ invalid_type_error: "Not a string", required_error: "Required" })
-
-// v4 - error 파라미터로 통합
+// 에러 커스텀: message → error
 z.string().min(5, { error: "Too short." })
-z.string({
-  error: (issue) => issue.input === undefined
-    ? "This field is required"
-    : "Not a string"
-})
-```
-
-### 새로운 최상위 문자열 포맷 API
-
-```typescript
-// v3 (deprecated)
-z.string().email()
-z.string().uuid()
-
-// v4 - 최상위 API (더 나은 tree-shaking)
-z.email()
-z.uuid()
-z.url()
-z.base64()
-z.nanoid()
-z.cuid()
-z.cuid2()
-z.ulid()
-z.ipv4()
-z.ipv6()
-z.iso.date()
-z.iso.time()
-z.iso.datetime()
-```
-
-### Strict/Loose 객체
-
-```typescript
-// v3
-z.object({ name: z.string() }).strict()
-z.object({ name: z.string() }).passthrough()
-
-// v4
-z.strictObject({ name: z.string() })
-z.looseObject({ name: z.string() })
-```
 
-### Refinements가 스키마 내부에 저장
+// Strict/Loose 객체
+z.strictObject({ name: z.string() })  // 추가 키 에러
+z.looseObject({ name: z.string() })   // 추가 키 통과
 
-```typescript
-// v3 - ZodEffects로 래핑되어 .min() 호출 불가
-z.string()
-  .refine(val => val.includes("@"))
-  .min(5) // ❌ Property 'min' does not exist on type ZodEffects
-
-// v4 - 스키마 내부에 저장되어 체이닝 가능
-z.string()
-  .refine(val => val.includes("@"))
-  .min(5) // ✅
-```
-
-## TanStack Start와 함께 사용
-
-```typescript
-import { createServerFn } from '@tanstack/react-start'
-import { zodValidator } from '@tanstack/react-start/validators'
-import { z } from 'zod'
-
-const createUserSchema = z.object({
-  email: z.email(),  // v4 새 API
-  name: z.string().min(1).max(100).trim(),
-  bio: z.string().max(500).optional(),
-})
-
-export const createUser = createServerFn({ method: 'POST' })
-  .inputValidator(zodValidator(createUserSchema))
-  .handler(async ({ data }) => {
-    // data는 타입 안전함
-    return prisma.user.create({ data })
-  })
+// Refinement 체이닝 가능
+z.string().refine(val => val.includes("@")).min(5)  // ✅ v4
 ```
-
-## 참고 자료
-
-- [Zod 공식 문서](https://zod.dev)
-- [Zod GitHub](https://github.com/colinhacks/zod)

package/templates/tanstack-start/docs/library/zod/transforms.md

@@ -1,148 +1,56 @@
 # Zod - 변환
 
-> **상위 문서**: [Zod](./index.md)
-
 ## Transform
 
-입력값을 다른 형태로 변환합니다.
-
 ```typescript
 const stringToLength = z.string().transform((val) => val.length)
+stringToLength.parse('hello')  // => 5
 
-stringToLength.parse('string') // => 6
-
-type MySchemaIn = z.input<typeof stringToLength>   // string
-type MySchemaOut = z.output<typeof stringToLength> // number
-```
-
-### 체인으로 변환
-
-```typescript
-const emailToLower = z.string()
-  .email()
-  .transform((email) => email.toLowerCase())
-
-emailToLower.parse('User@Example.COM') // => "user@example.com"
-```
-
-## Pipe를 사용한 Transform
-
-```typescript
-const stringToLength = z.string().pipe(z.transform(val => val.length))
-
-stringToLength.parse('hello') // => 5
+type In = z.input<typeof stringToLength>   // string
+type Out = z.output<typeof stringToLength> // number
 ```
 
-### 검증 후 변환
+## Pipe (검증 후 변환)
 
 ```typescript
 const stringToNumber = z.string()
   .transform((val) => parseInt(val, 10))
   .pipe(z.number().min(0).max(100))
 
-stringToNumber.parse('50') // => 50
-stringToNumber.parse('150') // => throws
-```
-
-## Transform 내에서 검증
-
-```typescript
-const coercedInt = z.transform((val, ctx) => {
-  try {
-    const parsed = Number.parseInt(String(val))
-    return parsed
-  } catch (e) {
-    ctx.issues.push({
-      code: 'custom',
-      message: 'Not a number',
-      input: val,
-    })
-    return z.NEVER // 타입에 영향 없이 에러 반환
-  }
-})
+stringToNumber.parse('50')  // => 50
+stringToNumber.parse('150') // throws
 ```
 
 ## Coerce (강제 변환)
 
-입력값을 자동으로 해당 타입으로 변환합니다.
-
-```typescript
-z.coerce.string()   // 모든 값을 문자열로
-z.coerce.number()   // 모든 값을 숫자로
-z.coerce.boolean()  // 모든 값을 불리언으로
-z.coerce.date()     // 모든 값을 날짜로
-z.coerce.bigint()   // 모든 값을 BigInt로
-```
-
-### v4 Coerce 입력 타입 변경
-
 ```typescript
-const schema = z.coerce.string()
-type schemaInput = z.input<typeof schema>
-// v3: string
-// v4: unknown  // ⚠️ 주의: 입력 타입이 unknown으로 변경됨
-```
+z.coerce.string()   // 모든 값 → 문자열
+z.coerce.number()   // 모든 값 → 숫자
+z.coerce.boolean()  // 모든 값 → 불리언
+z.coerce.date()     // 모든 값 → 날짜
+z.coerce.bigint()   // 모든 값 → BigInt
 
-### Coerce 예시
+z.coerce.number().parse("42")  // => 42
+z.coerce.date().parse("2021-01-01")  // => Date
 
-```typescript
-// string coercion
-z.coerce.string().parse(123)     // => "123"
-z.coerce.string().parse(true)    // => "true"
-z.coerce.string().parse(null)    // => "null"
-
-// number coercion
-z.coerce.number().parse("42")    // => 42
-z.coerce.number().parse(true)    // => 1
-z.coerce.number().parse(false)   // => 0
-
-// boolean coercion
-z.coerce.boolean().parse("true") // => true
-z.coerce.boolean().parse("")     // => false
-z.coerce.boolean().parse(1)      // => true
-
-// date coercion
-z.coerce.date().parse("2021-01-01") // => Date
-z.coerce.date().parse(1609459200000) // => Date
+// ⚠️ v4: 입력 타입이 unknown으로 변경됨
+type In = z.input<typeof z.coerce.string()>  // unknown
 ```
 
 ### 환경변수 불리언 (v4 권장)
 
-`z.coerce.boolean()` 대신 더 정교한 `z.stringbool()` 사용:
-
 ```typescript
-const strbool = z.stringbool()
-
-strbool.parse("true")     // => true
-strbool.parse("yes")      // => true
-strbool.parse("1")        // => true
-strbool.parse("false")    // => false
-strbool.parse("no")       // => false
-strbool.parse("0")        // => false
+z.stringbool()  // "true"/"yes"/"1" → true
+                // "false"/"no"/"0" → false
 ```
 
 ## Preprocess
 
-검증 전에 데이터를 전처리합니다.
-
-```typescript
-const castToString = z.preprocess((val) => String(val), z.string())
-
-castToString.parse(123) // => "123"
-castToString.parse(null) // => "null"
-```
-
-### Preprocess vs Coerce
-
 ```typescript
-// preprocess - 커스텀 로직 가능
-const trimmedString = z.preprocess(
+const trimmed = z.preprocess(
   (val) => typeof val === 'string' ? val.trim() : val,
   z.string()
 )
-
-// coerce - 내장 변환만
-const coercedString = z.coerce.string()
 ```
 
 ## 입력/출력 타입 분리
@@ -152,23 +60,6 @@ const Schema = z.object({
   createdAt: z.string().transform((str) => new Date(str)),
 })
 
-type SchemaInput = z.input<typeof Schema>
-// { createdAt: string }
-
-type SchemaOutput = z.output<typeof Schema>
-// { createdAt: Date }
-```
-
-## 조건부 변환
-
-```typescript
-const conditionalTransform = z.string().transform((val) => {
-  if (val === 'null') return null
-  if (val === 'undefined') return undefined
-  return val
-})
-
-conditionalTransform.parse('hello')     // => "hello"
-conditionalTransform.parse('null')      // => null
-conditionalTransform.parse('undefined') // => undefined
+type SchemaInput = z.input<typeof Schema>   // { createdAt: string }
+type SchemaOutput = z.output<typeof Schema> // { createdAt: Date }
 ```

package/templates/tanstack-start/docs/library/zod/validation.md

@@ -1,208 +1,92 @@
 # Zod - 검증
 
-> **상위 문서**: [Zod](./index.md)
-
-## Refinement (커스텀 검증)
+## Refinement
 
 ```typescript
-// v4 - error 파라미터 사용 (message는 deprecated)
+// v4: message → error
 const PasswordSchema = z.string()
   .min(8)
-  .refine((val) => /[A-Z]/.test(val), {
-    error: '대문자가 포함되어야 합니다',  // v4: message → error
-  })
-  .refine((val) => /[0-9]/.test(val), {
-    error: '숫자가 포함되어야 합니다',
-  })
-```
+  .refine((val) => /[A-Z]/.test(val), { error: '대문자 필수' })
+  .refine((val) => /[0-9]/.test(val), { error: '숫자 필수' })
 
-### v4 Refinement 체이닝 개선
+// v4: refinement 후 체이닝 가능
+z.string().refine(val => val.includes("@")).min(5)  // ✅
 
-```typescript
-// v3 - ZodEffects로 래핑되어 .min() 호출 불가
-z.string()
-  .refine(val => val.includes("@"))
-  .min(5) // ❌ 에러
-
-// v4 - 스키마 내부에 저장되어 체이닝 가능
-z.string()
-  .refine(val => val.includes("@"))
-  .min(5) // ✅ 정상 작동
-```
-
-### Async Refinement
-
-```typescript
+// Async
 const schema = z.string().refine(async (val) => val.length <= 8)
-
-await schema.parseAsync('hello') // => "hello"
-```
-
-### 이메일 중복 검사 예시
-
-```typescript
-const EmailSchema = z.email()  // v4 새 API
-  .refine(async (email) => {
-    const exists = await checkEmailExists(email)
-    return !exists
-  }, {
-    error: '이미 사용 중인 이메일입니다',  // v4: message → error
-  })
+await schema.parseAsync('hello')
 ```
 
-## Superrefine (고급 검증)
-
-여러 이슈를 추가하거나 경로를 지정할 수 있습니다.
-
-> **v4 변경**: `ctx.path`는 더 이상 사용할 수 없습니다 (성능 향상을 위해 제거됨)
+## Superrefine (고급)
 
 ```typescript
-const Schema = z.object({
+z.object({
   password: z.string(),
   confirmPassword: z.string(),
 }).superRefine((data, ctx) => {
   if (data.password !== data.confirmPassword) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
-      message: '비밀번호가 일치하지 않습니다',
+      message: '비밀번호 불일치',
       path: ['confirmPassword'],
     })
   }
-  // ctx.path // ❌ v4에서 더 이상 사용 불가
 })
+// ⚠️ v4: ctx.path 사용 불가
 ```
 
-### 복잡한 검증 로직
+## 커스텀 스키마
 
 ```typescript
-const UserSchema = z.object({
-  username: z.string(),
-  email: z.string().email(),
-  age: z.number(),
-}).superRefine((data, ctx) => {
-  // 여러 조건 검증
-  if (data.age < 13 && data.email.includes('work')) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.custom,
-      message: '13세 미만은 업무용 이메일을 사용할 수 없습니다',
-      path: ['email'],
-    })
-  }
+const px = z.custom<`${number}px`>((val) =>
+  typeof val === 'string' && /^\d+px$/.test(val)
+)
 
-  if (data.username.toLowerCase() === 'admin' && data.age < 18) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.custom,
-      message: 'admin 사용자명은 18세 이상만 사용 가능합니다',
-      path: ['username'],
-    })
-  }
-})
+px.parse('42px')  // ✅
+px.parse('42vw')  // throws
 ```
 
-## 커스텀 스키마
+## 에러 처리
 
 ```typescript
-const px = z.custom<`${number}px`>((val) => {
-  return typeof val === 'string' ? /^\d+px$/.test(val) : false
-})
+const result = schema.safeParse(data)
 
-type Px = z.infer<typeof px> // `${number}px`
+if (!result.success) {
+  result.error.errors.forEach((err) => {
+    console.log(err.path, err.message, err.code)
+  })
 
-px.parse('42px')  // '42px'
-px.parse('42vw')  // throws
+  // 평면화
+  const flat = result.error.flatten()
+  // { fieldErrors: { email: ['Invalid email'] } }
+}
 ```
 
-## TanStack Start와 함께 사용
-
-### Server Function 입력 검증
+## TanStack Start 연동
 
 ```typescript
-import { createServerFn } from '@tanstack/react-start'
-import { zodValidator } from '@tanstack/react-start/validators'
-import { z } from 'zod'
-
-const createUserSchema = z.object({
-  email: z.email(),  // v4 새 API
-  name: z.string().min(1).max(100).trim(),
-  bio: z.string().max(500).optional(),
-})
-
+// Server Function
 export const createUser = createServerFn({ method: 'POST' })
   .inputValidator(zodValidator(createUserSchema))
-  .handler(async ({ data }) => {
-    // data는 타입 안전함
-    return prisma.user.create({ data })
-  })
-```
-
-### 환경 변수 검증
+  .handler(async ({ data }) => prisma.user.create({ data }))
 
-```typescript
-const envSchema = z.object({
+// 환경 변수
+const env = z.object({
   NODE_ENV: z.enum(['development', 'production', 'test']),
   DATABASE_URL: z.string().url(),
   API_SECRET: z.string().min(32),
-})
-
-export const env = envSchema.parse(process.env)
-```
-
-### Middleware에서 사용
-
-```typescript
-import { createMiddleware } from '@tanstack/react-start'
-import { zodValidator } from '@tanstack/react-start/validators'
-import { z } from 'zod'
-
-const mySchema = z.object({
-  workspaceId: z.string(),
-})
+}).parse(process.env)
 
+// Middleware
 const workspaceMiddleware = createMiddleware({ type: 'function' })
-  .inputValidator(zodValidator(mySchema))
-  .server(({ next, data }) => {
-    console.log('Workspace ID:', data.workspaceId)
-    return next()
-  })
-```
-
-## 에러 처리
-
-```typescript
-const result = UserSchema.safeParse(data)
-
-if (!result.success) {
-  // ZodError 객체
-  const errors = result.error.errors
-
-  errors.forEach((err) => {
-    console.log('Path:', err.path)
-    console.log('Message:', err.message)
-    console.log('Code:', err.code)
-  })
-
-  // 평면화된 에러
-  const flatErrors = result.error.flatten()
-  console.log(flatErrors.fieldErrors)
-  // { email: ['Invalid email'], name: ['Required'] }
-}
+  .inputValidator(zodValidator(z.object({ workspaceId: z.string() })))
+  .server(({ next, data }) => next())
 ```
 
-## Zod Mini (경량 버전)
-
-v4에서 새롭게 추가된 경량 API:
+## Zod Mini (v4 경량)
 
 ```typescript
 import * as z from "zod/mini"
 
-// regular Zod
-z.string().min(5).max(10).trim()
-
-// Zod Mini - check 메서드로 통합
-z.string().check(
-  z.minLength(5),
-  z.maxLength(10),
-  z.toLowerCase(),
-  z.trim(),
-)
+z.string().check(z.minLength(5), z.maxLength(10), z.trim())
 ```