{"id":"mJAAl7","createdAt":"2025-08-29T00:22:30.462Z","updatedAt":null,"title":"Zod 핵심 정리 - 런타임 타입 검증 with 타입스크립트","content":"/// message-box --icon=info\n이 글은 Zod 4.1.5 버전을 기준으로 작성되었습니다.\n///\n\n타입스크립트는 컴파일 단계에서 강력한 타입 검사를 제공하지만, 런타임 단계에서의 타입 안전성까지 보장하지는 못합니다.\n[Zod](https://zod.dev/)는 런타임에서 데이터의 유효성을 검증하는 라이브러리로, 타입스크립트의 컴파일 타입 검사와 함께 사용해 더욱 강력한 타입 안전성을 보장할 수 있습니다.\n물론 자바스크립트에서도 사용할 수 있습니다.\n\n## 설치 및 기본 사용\n\n다음과 같이 설치합니다.\n\n```bash\nnpm i zod\n```\n\n설치 후 간단한 테스트를 위해 다음과 같이 사용자 객체 데이터를 준비합니다.\n\n```ts --path=/user.ts\n// 사용자 데이터\nexport const userData = {\n name: 'Neo',\n age: 22\n}\n```\n\n다음으로 사용자 데이터를 검증하기 위한 스키마(Schema)를 정의합니다.\nZod의 `z` 객체에서 `.object()`, `.string()`, `.number()` 등의 다양한 스키마 메소드를 사용할 수 있습니다.\n그리고 원하는 데이터 스키마를 정의했다면, 그 스키마에서 `.parse()` 등의 메소드를 사용해 사용자 데이터를 인수로 전달합니다. \n그러면 런타임에서 사용자 데이터가 정의한 스키마와 일치하는지 유효성을 확인(검증)합니다.\n만약 데이터가 스키마와 일치하지 않으면 런타임에서 에러가 발생합니다.\n\n```js --path=/main.js --caption=JS 코드\nimport { z } from 'zod'\nimport { userData } from './user.js'\n\n// 스키마 정의\nconst userSchema = z.object({\n name: z.string(),\n age: z.number()\n})\n\n// 데이터 검증 및 에러 처리\ntry {\n userSchema.parse(userData)\n} catch (error) {\n if (error instanceof z.ZodError) {\n console.error(error.issues)\n }\n}\n```\n\n타입스크립트를 사용하는 경우 정의한 스키마의 타입이 필요할 수 있습니다.\n`z.infer`을 통해 타입을 추론(Inference)하고 그 결과로 스키마의 타입을 얻을 수 있습니다.\n그리고 타입스크립트의 `satisfies` 키워드를 사용하면 데이터가 타입을 만족하는지 쉽게 확인할 수 있습니다.\n\n```ts --path=/main.ts --line-active=9,13 --caption=TS 코드\nimport { z } from 'zod'\nimport { userData } from './user'\n\n// 스키마 및 타입 정의\nconst userSchema = z.object({\n name: z.string(),\n age: z.number()\n})\ntype UserSchema = z.infer\n\n// 데이터 검증 및 에러 처리\ntry {\n userSchema.parse(userData satisfies UserSchema) // 데이터의 타입 만족 확인\n} catch (error) {\n if (error instanceof z.ZodError) {\n console.error(error.issues) // [...]\n }\n}\n```\n\n## 스키마 검증\n\n스키마 객체에서 사용할 수 있는 여러 검증 메소드를 통해, 제공 데이터가 스키마와 일치하는지 확인할 수 있습니다.\n\n/// message-box --icon=warning\n아래에서 살펴볼 `.parse()`, `.safeParse()` 등의 검증 메소드가 성공 후 반환하는 데이터는 깊게 복사된(Deep Copy) 사본입니다.\n만약 중첩된 참조형의 불변성(Immutability)이 중요한 경우, 반환된 데이터(사본)를 사용하지 않는 것이 좋습니다.\n///\n\n### .parse()\n\n`.parse()` 메소드는 데이터를 검증해, 성공하면 그 데이터를 반환하고 실패하면 에러를 던집니다.\n따라서 `try/catch` 구문으로 에러를 처리해야 할 수 있습니다.\n에러가 발생한 경우, `error` 객체의 `issues` 배열 속성을 조회해 다양한 에러 정보를 확인할 수 있습니다.\n\n/// message-box --icon=info\n에러와 관련된 내용은 [에러 처리](#h2_에러_처리) 파트에서 더 자세하게 살펴봅니다.\n///\n\n```ts --path=/main.ts --line-active=13\nimport { z } from 'zod'\nimport { userData } from './user'\n\n// 정의\nconst userSchema = z.object({\n name: z.string(),\n age: z.number()\n})\ntype User = z.infer\n\ntry {\n // 검증\n const result = userSchema.parse(userData satisfies User)\n\n // 성공\n console.log(result) // { name: 'Neo', age: 22 }\n \n} catch (error) {\n // 실패\n if (error instanceof z.ZodError) {\n console.error(error.issues) // [...]\n }\n}\n```\n\n### .safeParse()\n\n`.safeParse()` 메소드는 데이터를 검증해, 성공이나 실패 정보가 포함된 결과 객체를 반환합니다.\n성공하면 결과(`result`)의 `data` 속성으로 데이터를 조회하고, 실패하면 `error` 속성으로 에러 정보를 처리할 수 있습니다.\n`.safeParse()` 메소드는 검증이 실패해도 에러를 던지지 않으므로 `try/catch` 구문을 사용할 필요가 없습니다.\n\n```ts --path=/main.ts --line-active=4\n// ...\n\n// 검증\nconst result = userSchema.safeParse(userData satisfies User)\n\n// 성공\nconsole.log(result.data) // { name: 'Neo', age: 22 }\n\n// 실패\nif (result.error instanceof z.ZodError) {\n console.error(error.issues) // [...]\n}\n```\n\n### .parseAsync()\n\n`.parseAsync()` 메소드는 앞서 살펴본 `.parse()` 메소드와 비슷하지만, `await` 키워드를 사용해 비동기로 검증합니다.\n스키마를 정의할 때 비동기 처리가 필요한 경우 사용합니다.\n\n다음 예제에서 `isNameExists` 함수는 존재하는 사용자 이름이 있는지 비동기로 확인합니다.\n단순히 1초 뒤에 존재 여부를 반환합니다.\n`resolve` 호출의 인수를 `true/false`로 지정해 테스트할 수도 있습니다.\n\n```ts --path=/user.ts\n// 사용자 데이터\nexport const userData = {\n name: 'Neo',\n age: 22\n}\n\n// 존재하는 이름인지 확인하는 비동기 함수 예시\nexport function isNameExists(name: string) {\n return new Promise(resolve => {\n // fetch(`https://api.heropy.dev/v0/users/exists?name=${name}`)\n // .then(res => res.json())\n // .then(name => setTimeout(() => resolve(Boolean(name)), 1000))\n setTimeout(() => resolve(Boolean(name)), 1000)\n })\n}\n```\n\n다음 예제에서는 사용자 이름(`name`)이 문자 데이터이고 추가로 `isNameExists` 함수로 이미 존재하는 이름인지 검증합니다.\n이때 `isNameExists` 함수는 Promise 인스턴스를 반환하기 때문에, `parseAsync` 메소드를 사용해야 검증을 기다릴 수 있습니다.\n\n/// message-box --icon=info\n스키마를 정의할 때 `refine` 메소드를 사용하면 커스텀 검증을 위한 콜백 함수를 추가할 수 있습니다.\n콜백 함수는 불린 데이터를 반환해야 합니다.\n///\n\n```ts --path=/main.ts --line-active=7-10,17\nimport { z } from 'zod'\nimport { userData, isNameExists } from './user'\n\nconst userSchema = z.object({\n name: z\n .string()\n .refine(\n val => isNameExists(val), \n { error: '이미 사용 중인 이름입니다.' }\n ),\n age: z.number()\n})\ntype User = z.infer\n\ntry {\n // 검증\n const res = await userSchema.parseAsync(userData satisfies User)\n\n // 성공\n console.log(res) // { name: 'Neo', age: 22 }\n \n} catch (error) {\n // 실패\n if (error instanceof z.ZodError) {\n console.error(error.issues[0]) // { code: 'custom', path: ['name'], message: '이미 사용 중인 이름입니다.' }\n }\n}\n```\n\n### .safeParseAsync()\n\n`.safeParseAsync()` 메소드는 앞서 살펴본 `.safeParse()`와 같이 `try/catch` 구문 없이 결과 객체를 반환하고, `.parseAsync()`처럼 `await` 키워드를 사용해 비동기로 호출합니다.\n\n```ts --path=/main.ts --line-active=4\n// ...\n\n// 검증\nconst result = await userSchema.safeParseAsync(userData satisfies User)\n\n// 성공\nconsole.log(result.data) // { name: 'Neo', age: 22 }\n\n// 실패\nif (result.error instanceof z.ZodError) {\n console.error(result.error.issues[0]) // { code: 'custom', path: ['name'], message: '이미 사용 중인 이름입니다.' }\n}\n```\n\n## 스키마 정의\n\n데이터 유효성을 검사하기 위해서는 우선 스키마를 정의해야 합니다.\n스키마는 간단한 원시형부터 복잡한 중첩 객체 등 다양한 타입을 나타낼 수 있습니다.\n\n### 문자 타입\n\n```ts\n// 문자\nz.string()\nz.string().min(2) // 최소 글자수\nz.string().max(10) // 최대 글자수\nz.string().length(7) // 정확한 글자수\nz.string().regex(/^[a-z]+$/) // 정규 표현식\nz.string().startsWith('A') // 문자로 시작\nz.string().endsWith('Z') // 문자로 끝\nz.string().includes('abc') // 문자를 포함\nz.string().uppercase() // 대문자\nz.string().lowercase() // 소문자\n\n// 템플릿 리터럴\nz.templateLiteral(['Hello ', z.string().min(8), '?!'])\n// => `Hello ${'template'}?!`\n// => `Hello ${'world'}?!` // ❌\n\n// 이메일\nz.email() // => 'thesecon@gmail.com'\nz.email({ pattern: /^\\w+@\\w+\\.\\w+$/ }) // 정규표현식\nz.email({ pattern: z.regexes.email }) // 기본 이메일\nz.email({ pattern: z.regexes.html5Email }) // HTML5 이메일\nz.email({ pattern: z.regexes.rfc5322Email }) // RFC 5322 이메일\nz.email({ pattern: z.regexes.unicodeEmail }) // 유니코드 이메일\n\n// URL\nz.url() // => 'https://heropy.dev', 'http://localhost:3000', 'mailto:thesecon@gmail.com'\n\n// 호스트 이름\nz.hostname() // => 'example.com', 'localhost', '127.0.0.1'\n\n// 이모지\nz.emoji() // => '👍'\n\n// Base64\nz.base64() // 표준 버전\nz.base64url() // URL 안전 버전\n// => 'SGVsbG8gd29ybGQ='\n// => 'data:text/plain;base64,SGVsbG8gd29ybGQ=' // ❌\n\n// JSON Web Token\nz.jwt() // => 'eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.e30.'\n\n// UUID\nz.uuid()\nz.uuid({ version: 'v4' }) // v1~8 버전 지정\nz.uuidv4() // v4\nz.uuidv6() // v6\nz.uuidv7() // v7\n// => '123e4567-e89b-12d3-a456-426614174000'\n\n// 랜덤 문자(21자 이상)\nz.nanoid() // => 'abcdefghij12345678901'\n\n// 카드키 식별자(9자 이상)\nz.cuid() // => 'c12345678'\n\n// 128비트 식별자(26자)\nz.ulid() // => '01H7Z8K4P2M9N3Q59V0W1X2Y3Z'\n\n// IPv4, IPv6\nz.ipv4() // => '192.168.1.1'\nz.ipv6() // => '2001:0db8:85a3:0000:0000:8a2e:0370:7334'\nz.cidrv4() // => '192.168.1.0/24'\nz.cidrv6() // => '2001:0db8:85a3:0000:0000:8a2e:0370:7334/64'\n\n// Date\nz.date() // => new Date('2025-12-16')\nz.date().min(new Date('2025-01-01')).max(new Date('2025-12-31')) // 날짜 범위 제한\n// => new Date('2025-12-16')\n// => new Date('2026-04-03') // ❌\n\nz.iso.date() // ISO 8601 날짜\nz.iso.time() // ISO 8601 시간\nz.iso.datetime() // ISO 8601 날짜와 시간\nz.iso.duration() // ISO 8601 기간(Period)\n// =>'2025-04-03'\n// =>'12:00', '12:00:00', '12:00:00.000'\n// =>'2025-04-03T12:00:00Z'\n// =>'P1Y2M3DT4H5M6S'\n```\n\n### 숫자 타입\n\n```ts\n// 숫자\nz.number()\nz.number().gt(5) // 보다 큰 숫자\nz.number().gte(5) // 보다 크거나 같은 숫자\nz.number().min(5) // 최소 숫자, `gte`와 같음\n\nz.number().lt(5) // 보다 작은 숫자\nz.number().lte(5) // 보다 작거나 같은 숫자\nz.number().max(5) // 최대 숫자, `lte`와 같음\n\nz.number().positive() // 양수\nz.number().nonpositive() // 양수가 아닌 숫자\nz.number().negative() // 음수\nz.number().nonnegative() // 음수가 아닌 숫자\n\nz.number().multipleOf(2) // 배수\nz.number().step(2) // 배수, `multipleOf`와 같음\n\n// 안전한 정수\nz.int() // => ~9007199254740991\n\n// 32비트 정수\nz.int32() // => ~2147483647\n\n// 큰 정수\nz.bigint() // => 1234n\nz.int64() // 64비트 정수, `bigint`와 같음\n\n// 부동소수점\nz.float32() // 32비트, 약 7자리 단정밀도\nz.float64() // 64비트, 약 15자리 배정밀도\n\n// Not a Number\nz.nan() // => NaN\n```\n\n### 기타 원시 타입\n\n```ts\n// 불린\nz.boolean()\n\n// 문자 불린\nconst stb1 = z.stringbool()\nstb1.parse('true') // true\nstb1.parse('1') // true\nstb1.parse('yes') // true\nstb1.parse('false') // false\nstb1.parse('0') // false\n// `stringbool`의 기본값은 다음과 같음\nz.stringbool({\n truthy: ['true', '1', 'yes', 'on', 'y', 'enabled'], // 참 문자 목록\n falsy: ['false', '0', 'no', 'off', 'n', 'disabled'], // 거짓 문자 목록\n case: 'insensitive' // 대소문자 구분 없음\n})\n\nconst stb2 = z.stringbool({\n truthy: ['Yes', 'Y'],\n falsy: ['No', 'N'],\n case: 'sensitive' // 대소문자 구분\n}) // 사용자 정의\nstb2.parse('Yes') // true\nstb2.parse('yes') // true\nstb2.parse('N') // false\n\n// 심볼\nz.symbol() // => Symbol('id')\n\n// Null, Undefined\nz.null() // => null\nz.undefined() // => undefined\nz.void() // => void, undefined와 같음\n\n// Undefined 가능 - z.optional(스키마)\nz.optional(z.number())\n// => 123, undefined\n// => null // ❌\n\n// Null 가능 - z.nullable(스키마)\nz.nullable(z.number())\n// => 123, null\n// => undefined // ❌\n\n// Null 또는 Undefined 가능 - z.nullish(스키마)\nz.nullish(z.number())\n// => 123, null, undefined\n```\n\n### 참조 타입\n\n```ts\n// 객체 - 알 수 없는 속성 제외 - z.object(객체_스키마)\nconst obj1 = z.object({\n name: z.string(),\n age: z.number()\n})\nobj1.parse({ name: 'Neo' }) // ❌\nobj1.parse({ name: 'Neo', age: 22 }) // { name: 'Neo', age: 22 }\nobj1.parse({ name: 'Neo', age: 22, isValid: true }) // { name: 'Neo', age: 22 }, isValid 속성 제외됨\n\n// 객체 - 알 수 없는 속성 에러 - z.strictObject(객체_스키마)\nconst obj2 = z.strictObject({\n name: z.string(),\n age: z.number()\n})\nobj2.parse({ name: 'Neo' }) // ❌\nobj2.parse({ name: 'Neo', age: 22 }) // { name: 'Neo', age: 22 }\nobj2.parse({ name: 'Neo', age: 22, isValid: true }) // ❌\n\n// 객체 - 알 수 없는 속성 허용 - z.looseObject(객체_스키마)\nconst obj3 = z.looseObject({\n name: z.string(),\n age: z.number()\n})\nobj3.parse({ name: 'Neo' }) // ❌\nobj3.parse({ name: 'Neo', age: 22 }) // { name: 'Neo', age: 22 }\nobj3.parse({ name: 'Neo', age: 22, isValid: true }) // { name: 'Neo', age: 22, isValid: true }, isValid 속성 포함됨\n\n// 객체 관련 메소드\nconst obj4 = z.object({\n name: z.string(),\n age: z.number().optional() // 선택적 속성으로 정의\n})\nobj4.catchAll(z.boolean()) // 허용하려는 알 수 없는 추가 속성들의 스키마 정의 // => { isValid: z.boolean(), hasEmail: z.boolean() }\nobj4.shape.age // 속성의 스키마 // z.number().optional()\nobj4.keyof() // 객체의 모든 속성 이름 스키마(Enum) // z.enum(['name', 'age'])\nobj4.extend({ isValid: z.boolean() }) // 병합된 새로운 객체 스키마 // z.object({ name: z.string(), age: z.number().optional(), isValid: z.boolean() })\nobj4.pick({ name: true }) // 선택된 속성의 객체 스키마 // z.object({ name: z.string() })\nobj4.omit({ name: true }) // 제외된 속성의 객체 스키마 // z.object({ age: z.number().optional() })\nobj4.partial() // 모든 속성이 선택적인 새로운 객체 스키마 // z.object({ name: z.string().optional(), age: z.number().optional() })\nobj4.required() // 모든 속성이 필수적인 새로운 객체 스키마 // z.object({ name: z.string(), age: z.number() })\n\n// 객체 - Key-Value - z.record(키_스키마, 값_스키마)\nz.record(z.string(), z.number())\n// => { a: 1, b: 2, c: 3 }\n// => { a: '1', b: '2', c: '3' } // ❌\n// => {} // ❌\n\n// 키 타입 제한\nz.record(\n z.union([z.string(), z.number(), z.symbol()]), \n z.number()\n) \n// => { abc: 1, 123: 2, [Symbol('id')]: 3 }\n\n// 키 이름 제한\nz.record(\n z.enum(['name', 'age']), \n z.number()\n)\n// => { name: 1, age: 2 }\n// => { name: 1, age: 2, isValid: 3 } // ❌\n\n// 객체 - 선택적 속성의 Key-Value - z.partialRecord(키_스키마, 값_스키마)\nz.partialRecord(z.string(), z.number())\n// => {}\n// => { a: 1 }\n// => { a: 1, b: 2 }\n// => { a: 1, b: 2, c: 3 }\n\n// 배열 - z.array(아이템_스키마)\nz.array(z.string()) // => ['A', 'B', 'C', 'D']\nz.array(z.number()) // => [1, 2, 3, 4]\nz.array(z.union([z.string(), z.number()])) // => ['A', 1, 'B', 2, 'C', 3, 'D', 4]\n\nz.array(z.string()).min(3) // 최소 아이템 수\nz.array(z.string()).max(2) // 최대 아이템 수\nz.array(z.number()).unwrap() // 배열의 아이템 스키마 확인\n\n// 튜플 - z.tuple(스키마_배열)\nz.tuple([z.string(), z.number()]) // => ['Neo', 22]\n```\n\n### 기타 타입\n\n```ts\n// 리터럴 - z.literal(값)\nz.literal('Hello')\nz.literal(123)\nz.literal(true)\n\n// 모든 타입\nz.any()\n\n// 알 수 없는 타입\nz.unknown()\n\n// 불가능한 타입\nz.never()\n\n// 열거형 - z.enum(문자_배열)\nz.enum(['a', 'b'])\n// => 'a'\n// => 'b'\n// => 'c' // ❌\n\n// 유니온 - z.union(스키마_배열)\nz.union([z.string(), z.number()])\n// => 'Hello'\n// => 123\n// => true // ❌\n\n// 식별 가능 유니온 - z.discriminatedUnion(식별_키, 스키마_배열)\nconst dis1 = z.discriminatedUnion('status', [\n z.object({ status: z.literal('success'), data: z.string() }),\n z.object({ status: z.literal('failed'), error: z.string() })\n])\ntype DU = z.infer\n// DU 타입은 다음과 같음\n// { status: 'success'; data: string } | { status: 'failed'; error: string }\nfunction getData(res: DU) {\n dis1.parse(res)\n return res.status === 'success' ? res.data : res.error\n}\ngetData({ status: 'success', data: 'Hello~' }) // 'Hello~'\ngetData({ status: 'failed', error: 'Error~' }) // 'Error~'\n\n// 인터섹션 - z.intersection(스키마_배열)\nconst obj1 = z.object({\n status: z.string(),\n data: z.string()\n})\nconst obj2 = z.object({\n status: z.string(),\n error: z.string()\n})\nconst int1 = z.intersection(obj1, obj2)\nint1.parse({ status: 'success', data: 'Hello!', error: 'Error!' })\n\n// JSON\nz.json()\n// => 'Hello'\n// => 123\n// => { name: 'Neo', age: 22 }\n// => undefined // ❌\n// => function () {} // ❌\n// => new Date() // ❌\n```\n\n### 클래스 타입\n\n```ts\nclass User {\n constructor(public name: string, public age: number) {}\n}\n\n// 인스턴스 - z.instanceof(클래스)\nconst user = new User('Neo', 22)\nconst date = new Date()\nconst ins1 = z.instanceof(User)\nins1.parse(user)\nins1.parse(date) // ❌\n\n// 속성 - z.property(속성명, 스키마)\nconst pro1 = z.instanceof(User).check(z.property('age', z.number().min(18)))\npro1.parse(new User('Neo', 22))\npro1.parse(new User('Neo', 17)) // ❌\n\n// Map - z.map(키_스미카, 값_스키마)\nconst map = new Map()\nmap.set(200, 'OK')\nmap.set(404, 'Not Found')\nmap.set(500, 'Internal Server Error')\nconst ma1 = z.map(z.number(), z.string())\nma1.parse(map)\n\n// Set - z.set(값_스키마)\nconst set = new Set()\nset.add({ x: 123 })\nconst se1 = z.set(z.object({ x: z.number() }))\nse1.parse(set)\n\n// File\nz.file()\nz.file().min(1024) // 최소 크기(바이트)\nz.file().max(1024) // 최대 크기(바이트)\nz.file().mime('image/png') // MIME 타입\n\nconst file = new File([], 'favicon.png')\nconst fil1 = z.file()\nfil1.parse(file)\n```\n\n### 커스텀 타입\n\n```ts\n// 스키마 전처리 - z.preprocess(전처리_함수, 스키마)\nconst pre1 = z.preprocess(val => {\n return typeof val === 'string' ? val.toUpperCase() : val\n}, z.string())\npre1.parse('abc') // 'ABC'\npre1.parse(123) // ❌\n\n// 스키마 시용자 정의 - z.custom(검증_함수)\nconst cus1 = z.custom(val => {\n return typeof val === 'string' ? /[A-Z]/.test(val) : false\n})\ncus1.parse('ABC') // 'ABC'\ncus1.parse(123) // ❌\n\n// 스키마 변환 - z.transform(변환_함수)\nconst tra1 = z.transform(val => {\n return typeof val === 'string' ? val.toUpperCase() : val\n})\ntra1.parse('abc') // 'ABC'\ntra1.parse(123) // 123\n\n// 스키마.transform(변환_함수)\nconst tra2 = z.string().transform(val => val.toUpperCase())\ntra2.parse('abc') // 'ABC'\ntra2.parse(123) // ❌\n\n// 스미카 연결 - z.pipe(in_스키마, out_스키마)\nconst pip1 = z.pipe(\n z.string(),\n z.transform(val => val.length)\n)\npip1.parse('abc') // 3\npip1.parse(123) // ❌\n\n// in_스키마.pipe(out_스키마)\nconst pip2 = z.string().pipe(z.transform(val => val.length))\npip2.parse('abc') // 3\npip2.parse(123) // ❌\n\n// 스키마 정제 - 스키마.refine(정제_함수, 옵션)\nconst ref1 = z\n .string()\n .refine(val => val.length < 4, {\n error: '글자가 너무 길어요!'\n })\n .refine(val => val.toUpperCase().includes('A'), {\n error: `'A' 혹은 'a'가 포함되어야 해요!`\n })\nref1.parse('abc') // 'abc'\nref1.parse('xyz123') // ❌\n\n// 스키마 정제 - 스키마.superRefine(정제_함수)\nconst sup1 = z.string().superRefine((val, ctx) => {\n if (val.length > 3) {\n ctx.addIssue({\n code: 'custom',\n message: 'Too many letters!'\n })\n }\n if (!val.toUpperCase().includes('A')) {\n ctx.addIssue({\n code: 'custom',\n message: `must include the letter 'A' or 'a'.`\n })\n }\n})\nsup1.parse('abc') // 'abc'\nsup1.parse('xyz123') // ❌\n\n// 스키마 확인 - 스키마.check(확인_함수)\nconst che1 = z.string().check(ctx => {\n if (ctx.value.length > 3) {\n ctx.issues.push({\n code: 'custom',\n input: ctx.value,\n message: 'Too many letters!'\n })\n }\n if (!ctx.value.toUpperCase().includes('A')) {\n ctx.issues.push({\n code: 'custom',\n input: ctx.value,\n message: `must include the letter 'A' or 'a'.`\n })\n }\n})\nche1.parse('abc') // 'abc'\nche1.parse('xyz123') // ❌\n\n// 기본값 - 스키마.default(기본값)\nconst def1 = z\n .number()\n .transform(val => val + 10)\n .default(0)\ndef1.parse(2) // 12\ndef1.parse(undefined) // 0\n\n// 기본값 전처리 - 스키마.prefault(기본값)\nconst pre1 = z\n .number()\n .transform(val => val + 10)\n .prefault(0)\npre1.parse(2) // 12\npre1.parse(undefined) // 10\n\n// 에러 시 기본값\nconst cat1 = z.number().catch(0)\ncat1.parse('Hello~') // 0\n\nconst cat2 = z.number().catch(ctx => {\n console.log(ctx.error.issues[0].message) // 'Invalid input: expected number, received string'\n return 0\n})\ncat2.parse('Hello~') // 0\n\n// 읽기 전용\nconst arr = z.array(z.number()).readonly()\nconst res = schema.parse([1, 2, 3])\nres // [1, 2, 3]\nres.push(4) // ❌ // Error! ts(2339)\n\n// 브랜드 타입\nconst id = z.email().brand<'ID'>()\nconst pw = z.string().min(8).max(20).brand<'PW'>()\ntype Id = z.infer\ntype Pw = z.infer\nconst res1: Pw = id.parse('thesecon@gmail.com') // Error! ts(2322)\nconst res2: Id = pw.parse('qwer1234') // Error! ts(2322)\nres1 // 'thesecon@gmail.com'\nres2 // 'qwer1234'\n```\n\n## 에러 처리\n\n위에서 살펴본 것처럼, `.parse()`, `.safeParse()` 등의 검증 메소드를 사용하고 데이터 검증에 실패하면 에러를 확인할 수 있습니다.\n실패 결과의 에러 객체는 `z.ZodError`의 인스턴스이며, 에러 객체의 `issues` 속성에는 배열의 아이템으로 여러 이슈 객체가 포함됩니다.\n이슈 객체는 `expected`, `code` 등의 속성을 가지고 있으며, 특히 `message` 속성을 통해 에러가 발생한 이유를 확인할 수 있습니다.\n\n```ts\n// .parse() + try/catch\ntry {\n z.number().parse('Hello~') // ❌\n} catch (error) {\n if (error instanceof z.ZodError) {\n console.log(error.issues)\n }\n}\n\n// .safeParse()\nconst result = z.number().safeParse('Hello~') // ❌\nif (result.error instanceof z.ZodError) {\n console.log(result.error.issues)\n}\n\n// 이슈 객체 구조 예시, error.issues[0]\n// => {\n// expected: 'number', // 기대되는 타입\n// code: 'invalid_type', // 에러 코드\n// path: ['age'], // 에러 발생 경로(속성)\n// message: 'Invalid input: expected number, received string' // 에러 메시지\n// }\n```\n\nZod는 국제화를 지원합니다.\n따라서 기본 에러 메시지를 한글로 출력할 수도 있습니다.\n\n그리고 사용자 전용 에러 메시지를 스키마나 검증 메소드에 직접 추가할 수 있습니다. \n참고로 사용자 전용 에러 메시지는 검증 메소드보다 스키마에 적용하는 것이 더 우선합니다.\n\n```ts\nimport { z } from 'zod'\nimport { ko } from 'zod/locales'\n\nz.config(ko()) // 한국어 구성\n\ntry {\n z.number().parse('Hello~')\n // '잘못된 입력: 예상 타입은 number, 받은 타입은 string입니다'\n\n z.number('높은 우선순위').parse('Hello~')\n z.number({ error: '높은 우선순위' }).parse('Hello~')\n z.number({ error: issue => '높은 우선순위' }).parse('Hello~')\n z.number({ error: issue => '높은 우선순위' }).parse('Hello~', { error: issue => '낮은 우선순위' })\n // '높은 우선순위'\n\n z.number().parse('Hello~', { error: issue => '낮은 우선순위' })\n // '낮은 우선순위'\n \n} catch (error) {\n if (error instanceof z.ZodError) {\n console.log(error.issues[0].message)\n }\n}\n```\n\nZod는 에러 정보를 더 유연하게 표시하기 위해서, `.treeifyError()` 등의 유틸리티 메소드를 제공합니다.\n\n멤버 | 설명\n--|--\nerror.issues | 오류 객체를 배열로 표시\nz.treeifyError(error) | 오류 객체를 트리 구조로 표시\nz.prettifyError(error) | 사람이 읽을 수 있는 문자로 표시\nz.flattenError(error) | 깔끔하고 얕은 오류 표시\n\n```ts\nimport { z } from 'zod'\nimport { ko } from 'zod/locales'\n\nz.config(ko())\n\ntry {\n z.strictObject({\n name: z.string(),\n age: z.number()\n }).parse({\n name: 123,\n age: 'Neo',\n isValid: true\n })\n} catch (error) {\n if (error instanceof z.ZodError) {\n console.log(error.issues)\n // 오류 객체를 배열로 표시\n // => [\n // {\n // expected: 'string',\n // code: 'invalid_type',\n // path: [ 'name' ],\n // message: '잘못된 입력: 예상 타입은 string, 받은 타입은 number입니다'\n // },\n // {\n // expected: 'number',\n // code: 'invalid_type',\n // path: [ 'age' ],\n // message: '잘못된 입력: 예상 타입은 number, 받은 타입은 string입니다'\n // },\n // {\n // code: 'unrecognized_keys',\n // keys: [ 'isValid' ],\n // path: [],\n // message: '인식할 수 없는 키: \"isValid\"'\n // }\n // ]\n\n console.log(z.treeifyError(error))\n // 오류 객체를 트리 구조로 표시\n // => {\n // errors: [ '인식할 수 없는 키: \"isValid\"' ],\n // properties: {\n // name: {\n // errors: [ '잘못된 입력: 예상 타입은 string, 받은 타입은 number입니다' ]\n // },\n // age: {\n // errors: [ '잘못된 입력: 예상 타입은 number, 받은 타입은 string입니다' ]\n // }\n // }\n // }\n\n console.log(z.prettifyError(error))\n // 사람이 읽을 수 있는 문자로 표시\n // => ✖ 인식할 수 없는 키: 'isValid'\n // ✖ 잘못된 입력: 예상 타입은 string, 받은 타입은 number입니다\n // → at name\n // ✖ 잘못된 입력: 예상 타입은 number, 받은 타입은 string입니다\n // → at age\n\n console.log(z.flattenError(error))\n // 깔끔하고 얕은 오류 표시\n // => {\n // formErrors: [ '인식할 수 없는 키: \"isValid\"' ],\n // fieldErrors: {\n // name: [ '잘못된 입력: 예상 타입은 string, 받은 타입은 number입니다' ],\n // age: [ '잘못된 입력: 예상 타입은 number, 받은 타입은 string입니다' ]\n // }\n // }\n }\n}\n```\n\n## 예제\n\n### 로그인 양식 검증\n\n/// message-box --icon=info\n다음은 [React 프로젝트 시작하기 w. Vite](https://www.heropy.dev/p/6iFzkB)를 기반으로 하는 예제입니다.\n///\n\n![로그인 양식 검증 예제 출력](https://somwpkzlplaovldnfahk.supabase.co/storage/v1/object/public/heropy.dev_posts/mJAAl7/0LEA \"--451x250\")\n\n```tsx --path=/src/App.tsx\nimport { useState } from 'react'\nimport { z } from 'zod'\n\nconst schema = z.object({\n id: z.email({ error: '이메일 형식이 올바르지 않습니다.' }),\n pw: z.string().min(5, {\n error: issue => `비밀번호는 ${issue.minimum}자 이상이어야 합니다.`\n })\n})\n\nfunction TextField(\n props: React.InputHTMLAttributes & { error: string }\n) {\n return (\n

\n \n {props.error && (\n

{props.error}

\n )}\n

\n )\n}\n\nexport default function App() {\n const [id, setId] = useState('')\n const [pw, setPw] = useState('')\n const [idError, setIdError] = useState('')\n const [pwError, setPwError] = useState('')\n\n function validateFields() {\n setIdError('')\n setPwError('')\n const result = schema.safeParse({ id, pw })\n if (result.error instanceof z.ZodError) {\n result.error.issues.forEach(issue => {\n switch (issue.path[0]) {\n case 'id':\n setIdError(issue.message)\n break\n case 'pw':\n setPwError(issue.message)\n break\n }\n })\n return false\n }\n return true\n }\n function handleSubmit(e: React.FormEvent) {\n e.preventDefault()\n if (!validateFields()) return\n // 로그인 처리..\n console.log('로그인!')\n }\n\n return (\n <>\n \n setId(e.target.value)}\n error={idError}\n />\n setPw(e.target.value)}\n error={pwError}\n />\n \n 로그인\n \n \n \n )\n}\n```\n","isPublished":true,"isDeleted":false,"group":"Lib","tags":["Zod","TypeScript"],"comments":0,"image":"https://somwpkzlplaovldnfahk.supabase.co/storage/v1/object/public/heropy.dev_posts/mJAAl7/main.jpg","description":"타입스크립트는 컴파일 단계에서 강력한 타입 검사를 제공하지만, 런타임 단계에서의 타입 안전성까지 보장하지는 못합니다. Zod는 런타임에서 데이터의 유효성을 검증하는 라이브러리로 타입스크립트의 컴파일 타입 검사와 함께 사용하면 더욱 강력한 타입 안전성을 보장할 수 있습니다.","postname":"lib-zod","video":[],"like":0,"embeddedAt":null}