TypeScipt - zod 라이브러리

zod 라이브러리란?

Zod는 TypeScript 및 JavaScript 프로젝트에서 입력 데이터를 *스키마로 정의한 후 이를 기반으로 유효성 검사를 가능하게 도와주는 라이브러리이다. Zod를 사용하면 간단한 문법을 통해 데이터 검증과 변환을 동시에 작동할 수 있다. 주로 API 요청과 서버 응답, 폼 데이터 등의 데이터를 안정적으로 검증할 때 사용할 수 있다. 그렇다면 사용 방법에 대해 알아보자 

*스키마란 데이터를 구조화하고 해당 데이터에 대한 규칙과 제약을 정의한 것이다. 

기본 스키마 정의 및 유효성 검사

기본 타입 스키마 정의

Zod를 통해 여러 기본 타입을 검증할 수 있는 스키마를 정의할 수 있다.  또한 예시와 같이 기본 타입에 추가적인 검증 규칙을 정의할 수 있다.

import { z } from 'zod';

const stringSchema = z.string();       // 문자열
const numberSchema = z.number();       // 숫자
const booleanSchema = z.boolean();     // 불리언
const dateSchema = z.date();           // 날짜
const bigintSchema = z.bigint();       // BigInt
const undefinedSchema = z.undefined(); // undefined
const nullSchema = z.null();           // null

const ageSchema = z.number().min(18).max(99); // 18에서 99까지의 숫자만 허용하게 된다
const passwordSchema = z.string().min(8);     // 최소 8자 이상의 문자열만 허용하게 된다

객체 스키마

z.object()를 사용하면 객체를 정의하고 객체 내에서의 각 필드의 타입 또한 정의하며 유효성 검사가 가능하다. 하지만 이때 partial()를 추가적으로 사용하면 모든 필드를 선택적으로 설정할 수도 있다. 

const userSchema = z.object({
  name: z.string(),                   // 문자열 필드
  age: z.number().min(18),            // 최소 18세 이상의 숫자 필드
  isActive: z.boolean().optional(),   // 선택적 Boolean 필드
});

const partialUserSchema = userSchema.partial(); // 모든 필드가 선택적으로 설정된다

배열 스키마

z.array()를 사용하면 배열을 정의하고 배열의 요소에 대한 유효성 검사도 함께 설정할 수 있다.

const stringArraySchema = z.array(z.string()); // 문자열 배열
const numberArraySchema = z.array(z.number().min(0)); // 0 이상의 숫자 배열
const limitedArraySchema = z.array(z.string()).min(1).max(5); // 최소 1개, 최대 5개의 문자열

Enum 및 Literal

문자열 또는 숫자 열거형(Enum) 및 리터럴 값을 검증할 때 설정할 수 있다. 

const roleSchema = z.enum(['admin', 'user', 'guest']); // 특정 값들만 허용한다
const statusSchema = z.literal('success');  // 'success'만 허용한다

사용자 정의 유효성 검사

.refine() 메서드를 사용하여 사용자 정의 유효성 검사를 추가할 수 있는데, .refine() 메서드는 특정 조건에 따라 데이터를 검증할 수 있다. 

const passwordSchema = z.string().refine((val) => val.includes("*"), {
  message: "비밀번호는 '*'를 포함해야해요!."
});

 

스키마 기반의 타입 추론

타입 추론

z.infer를 사용하면 Zod 스키마에서 정의한 타입을 TypeScript에서 타입 추론하게 설정할 수 있다. 이를 통해 스키마에서 정의된 구조에 따라 TypeScript 타입을 생성할 수 있는 장점이 있다. 

import { z } from 'zod';

// 스키마 정의
const userSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email()
});

// z.infer를 사용하여 스키마에서 타입 추론
type User = z.infer<typeof userSchema>;

const validUser: User = {
  name: "Benjie",
  age: 24,
  email: "1234@gmail.com"
};

유효성 검사 에러 처리

ZodError는 Zod에서 스키마 유효성 검사를 수행할 때 발생할 수 있는 에러를 관리하는 클래스로, 유효성 검사에 실패한 경우, 아래 코드와 같이 error.errors를 통해  ZodError는 어떤 필드에서 에러가 발생했는지, 어떤 규칙이 어긋났는지 알 수 있다.

import { z } from 'zod';

// 스키마 정의
const userSchema = z.object({
  name: z.string(),
  age: z.number().min(100),
  email: z.string().email()
});

const invalidUserData = {
  name: "Benjie",
  age: 24,               // 잘못된 값(100 미만)
  email: "no-email"   // 잘못된 이메일 형식
};

// 유효성 검사
try {
  userSchema.parse(invalidUserData);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.log(error.errors); // 에러 목록 출력
  }
}

// 결과 값 예시
[
  { path: ['age'], message: '100을 넘어야지!', code: 'too_small' },
  { path: ['email'], message: '이메일이 아니다', code: 'invalid_string' }
]

 

데이터 변환

const stringToNumberSchema = z.string().transform((val) => parseInt(val, 10));

const result = stringToNumberSchema.parse("42");
console.log(result);  // 결과: 42

 

 

자세한 내용은 공식문서를 보는걸 추천 드립니다:)

https://zod.dev/

GitHub - colinhacks/zod: TypeScript-first schema validation with static type inference