Zod는 런타임에 어떻게 타입을 검증하는가? - (1) 직접 Zod를 흉내내보며 이해해보기

const age: number

import * as z from "zod";

// 1. 값: schema를 정의하고
const User = z.object({ name: z.string(), age: z.number() });

// 2. 타입: 그 값에서 꺼내고
type User = z.infer<typeof User>; // { name: string; age: number }

// 3. 런타임: 같은 값이 검증까지 합니다
const user = User.parse(input); // 통과하면 User, 아니면 throw

1. 값에서 타입이 나오는 일은 어떻게 가능한가.

2. 그리고 타입은 컴파일 타임에만 존재한다고 알고 있는데, 런타임에 들어온 값의 타입이 틀렸다는 것은 어떻게 아는가.

일단 만들어 봅니다 — 가장 단순한 형태

// 검증은 그냥 함수입니다
function parseString(value: unknown): string {
  if (typeof value !== "string") throw new Error("string이 아닙니다");
  return value;
}

const name = parseString(JSON.parse(input)); // 통과하면 string, 아니면 throw

// 검증 함수를 담는 공통 그릇 — zod 에서 스키마를 흉내냈습니다.
interface Schema<Output> {
  parse(value: unknown): Output;
}

function string(): Schema<string> {
  return {
    parse(value) {
      if (typeof value !== "string") throw new Error("string이 아닙니다");
      return value;
    },
  };
}

function number(): Schema<number> {
  return {
    parse(value) {
      if (typeof value !== "number") throw new Error("number가 아닙니다");
      return value;
    },
  };
}

// 동작하지 않는 코드입니다 — 제네릭 T는 런타임에 존재하지 않습니다
function primitive<T>(): Schema<T> {
  return {
    parse(value) {
      if (typeof value !== typeof T) throw new Error("T가 아닙니다");
      //                          ^ 'T' only refers to a type
      return value;
    },
  };
}

// typeof 결과 문자열을 키로, 대응하는 타입을 값으로 갖는 조회 테이블입니다
type PrimitiveMap = {
  string: string;
  number: number;
  boolean: boolean;
};

function primitive<K extends keyof PrimitiveMap>(type: K): Schema<PrimitiveMap[K]> {                       
										        // ^^^ 여기서 string | number | boolean 으로 K 가 제약
  return {
    parse(value) {
      if (typeof value !== type) throw new Error(`${type}이 아닙니다`);
      return value as PrimitiveMap[K];
    },
  };
}

const string = () => primitive("string");
const number = () => primitive("number");

import * as z from "zod";

const User = z.object({
  name: z.string(),
  age: z.number().optional(),
  tags: z.array(z.string()),
});

type User = z.infer<typeof User>;
// { name: string; age?: number; tags: string[] }

export type $ZodTypes =
  | $ZodString
  | $ZodNumber
  | $ZodBigInt
  | $ZodBoolean
  | $ZodDate
  | $ZodSymbol
  | $ZodUndefined
  | $ZodNullable
  | $ZodNull
  | $ZodAny
  | $ZodUnknown
  | $ZodNever
  | $ZodVoid
  | $ZodArray
  | $ZodObject
  | $ZodUnion
  | $ZodIntersection
  | $ZodTuple
  | $ZodRecord
  | $ZodMap
  | $ZodSet
  | $ZodLiteral
  | $ZodEnum
  | $ZodFunction
  | $ZodPromise
  | $ZodLazy
  | $ZodOptional
  | $ZodDefault
  | $ZodPrefault
  | $ZodTemplateLiteral
  | $ZodCustom
  | $ZodTransform
  | $ZodNonOptional
  | $ZodReadonly
  | $ZodNaN
  | $ZodPipe
  | $ZodSuccess
  | $ZodCatch
  | $ZodFile;

스키마에서 타입 꺼내기 — 조건부 타입과 infer 키워드

 SomeType extends OtherType ? TrueType : FalseType 

// "S가 어떤 타입 T의 Schema라면, 그 T를 돌려달라"
type Infer<S> = S extends Schema<infer T> ? T : never;

const Name = string();
type Name = Infer<typeof Name>; // string

object — 값에서 타입추론하기

const User = m.object({ name: m.string(), age: m.number() });
type User = Infer<typeof User>; // { name: string; age: number }

// 타입 인자를 적지 않아도 인자 값에서 T가 추론됩니다
declare function identity<T>(value: T): T;
const a = identity("hello"); // T = "hello"

// 둘 다 타입 인자를 적은 적이 없지만 추론은 늘 작동하고 있었습니다
const strs = [1, 2, 3].map((n) => n.toString()); // map<U>의 U = string → string[]
const [count, setCount] = useState(0);           // useState<S>의 S = number

// key와 스키마의 쌍 — Zod가 shape라고 부르는 그 형태입니다
type Shape = Record<string, Schema<unknown>>;

// shape의 각 키에서 Infer를 돌려 객체 타입을 재구성합니다
type ObjectOutput<S extends Shape> = {
  [K in keyof S]: Infer<S[K]>;
};

function object<S extends Shape>(
  shape: S,
): Schema<ObjectOutput<S>> {
  return {
    parse(value) {
      if (typeof value !== "object" || value === null) {
        throw new Error("object가 아닙니다");
      }
      const result: Record<string, unknown> = {};
      for (const key in shape) {
        result[key] = shape[key].parse((value as Record<string, unknown>)[key]);
      }
      return result as ObjectOutput<S>;
    },
  };
}

export const m = { string, number, object };

흉내내기의 한계 — optional은 어떻게 할 건데?

// 순진한 구현 — 타입에 undefined를 합집합으로 더하기
function optional<S extends Schema<unknown>>(
  inner: S,
): Schema<Infer<S> | undefined> {
  return {
    parse(value) {
      if (value === undefined) return undefined;
      return inner.parse(value);
    },
  };
}

const User = m.object({ name: m.string(), age: optional(m.number()) });
type User = Infer<typeof User>;
// { name: string; age: number | undefined }
//                  ^^^ age?: 가 아니라 age: 입니다

const u: User = { name: "kim" }; // 에러: Property 'age' is missing

마무리

참고 자료

• TypeScript Handbook — Conditional Types

• TypeScript Handbook — Mapped Types

• TypeScript Handbook — Generics

• Zod 공식 문서 — Basic usage

• colinhacks/zod — v4 core 소스 (schemas.ts)

• type-challenges

• typia

• ts-to-zod

• zackoverflow — Write your own Zod