@kood/claude-code 0.1.0

package/templates/tanstack-start/docs/library/zod/complex-types.md

@@ -0,0 +1,204 @@
+# Zod - 복합 타입
+
+> **상위 문서**: [Zod](./index.md)
+
+## 객체
+
+```typescript
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.email(),  // v4 새 API
+  age: z.number().optional(),  // 선택적 필드
+})
+
+// 검증
+const result = UserSchema.parse({
+  name: 'john',
+  email: 'john@example.com',
+  age: 25,
+})
+
+// 안전한 검증
+const safeResult = UserSchema.safeParse(data)
+if (safeResult.success) {
+  console.log(safeResult.data)
+} else {
+  console.log(safeResult.error)
+}
+```
+
+### 객체 메서드
+
+```typescript
+// 부분 객체 (모든 필드가 optional)
+const PartialUser = UserSchema.partial()
+
+// 필수 객체 (모든 필드가 required)
+const RequiredUser = UserSchema.required()
+
+// 필드 선택
+const UserName = UserSchema.pick({ name: true })
+
+// 필드 제외
+const UserWithoutEmail = UserSchema.omit({ email: true })
+
+// 확장
+const ExtendedUser = UserSchema.extend({
+  role: z.enum(['admin', 'user']),
+})
+
+// 병합
+const MergedSchema = UserSchema.merge(AnotherSchema)
+```
+
+### Strict/Loose 객체 (v4)
+
+```typescript
+// v3
+z.object({ name: z.string() }).strict()     // 추가 키 에러
+z.object({ name: z.string() }).passthrough() // 추가 키 통과
+
+// v4 - 새로운 API
+z.strictObject({ name: z.string() })  // 추가 키 에러
+z.looseObject({ name: z.string() })   // 추가 키 통과
+```
+
+## 배열
+
+```typescript
+z.array(z.string())
+z.array(z.number()).min(1)     // 최소 1개
+z.array(z.number()).max(10)    // 최대 10개
+z.array(z.number()).length(5)  // 정확히 5개
+z.array(z.number()).nonempty() // 비어있지 않음
+```
+
+## 튜플
+
+```typescript
+const tuple = z.tuple([
+  z.string(),  // 첫 번째 요소
+  z.number(),  // 두 번째 요소
+])
+
+type Tuple = z.infer<typeof tuple>
+// [string, number]
+```
+
+## 유니온
+
+```typescript
+const StringOrNumber = z.union([z.string(), z.number()])
+// 또는
+const StringOrNumber = z.string().or(z.number())
+
+type StringOrNumber = z.infer<typeof StringOrNumber>
+// string | number
+```
+
+## Discriminated Union
+
+```typescript
+const Shape = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('circle'), radius: z.number() }),
+  z.object({ type: z.literal('rectangle'), width: z.number(), height: z.number() }),
+])
+
+type Shape = z.infer<typeof Shape>
+// { type: 'circle'; radius: number } | { type: 'rectangle'; width: number; height: number }
+```
+
+### v4 향상된 Discriminated Union
+
+```typescript
+// 유니온 및 파이프 discriminator 지원
+const MyResult = z.discriminatedUnion("status", [
+  // 단순 리터럴
+  z.object({ status: z.literal("aaa"), data: z.string() }),
+  // 유니온 discriminator
+  z.object({ status: z.union([z.literal("bbb"), z.literal("ccc")]) }),
+  // 파이프 discriminator
+  z.object({ status: z.literal("fail").transform(val => val.toUpperCase()) }),
+])
+
+// 중첩 discriminated union
+const BaseError = z.object({ status: z.literal("failed"), message: z.string() })
+
+const MyResult2 = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("success"), data: z.string() }),
+  z.discriminatedUnion("code", [
+    BaseError.extend({ code: z.literal(400) }),
+    BaseError.extend({ code: z.literal(401) }),
+    BaseError.extend({ code: z.literal(500) })
+  ])
+])
+```
+
+## Enum
+
+```typescript
+// 문자열 enum
+const FishEnum = z.enum(['Salmon', 'Tuna', 'Trout'])
+
+FishEnum.parse('Salmon') // => "Salmon"
+FishEnum.parse('Swordfish') // => ❌ throws
+
+type Fish = z.infer<typeof FishEnum>
+// 'Salmon' | 'Tuna' | 'Trout'
+
+// Native enum
+enum Fruits {
+  Apple,
+  Banana,
+}
+const FruitSchema = z.nativeEnum(Fruits)
+```
+
+## Record
+
+```typescript
+const UserStore = z.record(z.string(), z.object({
+  name: z.string(),
+}))
+
+type UserStore = z.infer<typeof UserStore>
+// { [key: string]: { name: string } }
+
+// 사용
+const userStore: UserStore = {}
+userStore['77d2586b-9e8e-4ecf-8b21-ea7e0530eadd'] = {
+  name: 'Carlotta',
+} // passes
+
+userStore['77d2586b-9e8e-4ecf-8b21-ea7e0530eadd'] = {
+  whatever: 'Ice cream sundae',
+} // TypeError
+```
+
+## Map & Set
+
+```typescript
+// Map
+const stringNumberMap = z.map(z.string(), z.number())
+type StringNumberMap = z.infer<typeof stringNumberMap>
+// Map<string, number>
+
+// Set
+const numberSet = z.set(z.number())
+type NumberSet = z.infer<typeof numberSet>
+// Set<number>
+```
+
+## 재귀 스키마 (JSON)
+
+```typescript
+const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()])
+type Literal = z.infer<typeof literalSchema>
+type Json = Literal | { [key: string]: Json } | Json[]
+
+const jsonSchema: z.ZodType<Json> = z.lazy(() =>
+  z.union([literalSchema, z.array(jsonSchema), z.record(jsonSchema)])
+)
+
+jsonSchema.parse({ foo: [1, 2, { bar: 'baz' }] })
+```

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

@@ -0,0 +1,186 @@
+# Zod
+
+> **Version**: 4.x | TypeScript Schema Validation
+
+---
+
+## 🚀 Quick Reference (복사용)
+
+```typescript
+// 기본 스키마
+const schema = z.object({
+  email: z.email(),              // v4 (string().email() 아님!)
+  name: z.string().min(1).trim(),
+  website: z.url().optional(),   // v4 (string().url() 아님!)
+  age: z.number().int().positive(),
+})
+
+// 타입 추출
+type Input = z.infer<typeof schema>
+
+// 파싱
+schema.parse(data)              // 실패 시 throw
+schema.safeParse(data)          // { success, data/error }
+
+// TanStack Start 연동
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(schema)
+  .handler(async ({ data }) => prisma.user.create({ data }))
+```
+
+### v4 새 API (⚠️ 중요)
+
+```typescript
+// ✅ v4 사용
+z.email()
+z.url()
+z.uuid()
+z.iso.date()
+z.iso.datetime()
+
+// ❌ 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
+```
+
+### 기본 사용법
+
+```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 파라미터로 통합
+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가 스키마 내부에 저장
+
+```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 })
+  })
+```
+
+## 참고 자료
+
+- [Zod 공식 문서](https://zod.dev)
+- [Zod GitHub](https://github.com/colinhacks/zod)

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

@@ -0,0 +1,174 @@
+# Zod - 변환
+
+> **상위 문서**: [Zod](./index.md)
+
+## Transform
+
+입력값을 다른 형태로 변환합니다.
+
+```typescript
+const stringToLength = z.string().transform((val) => val.length)
+
+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
+```
+
+### 검증 후 변환
+
+```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 // 타입에 영향 없이 에러 반환
+  }
+})
+```
+
+## 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으로 변경됨
+```
+
+### Coerce 예시
+
+```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 권장)
+
+`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
+```
+
+## 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(
+  (val) => typeof val === 'string' ? val.trim() : val,
+  z.string()
+)
+
+// coerce - 내장 변환만
+const coercedString = z.coerce.string()
+```
+
+## 입력/출력 타입 분리
+
+```typescript
+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
+```