Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, related_branches, related_projects, tags, created, last_reviewed

title

source_type

url

archive_url

status

confidence

related_branches

related_projects

Zod — TypeScript-first Schema Validation (parse / safeParse runtime contract)

Layer: raw/official-docs/ — Zod 공식 문서(zod.dev)의 스키마 정의·.parse()/.safeParse() 런타임 계약 원문 발췌. ca-skeleton-frontend 가 plain-JavaScript(컴파일 타임 TypeScript 타입 없음) 스켈레톤에서 zod 를 API 응답/폼 입력 등 경계(boundary)의 런타임 스키마 검증 계층으로 채택하는 근거.

Parent / 활용 branch (필수)

Parent	이 자료가 정당화하는 결정
raw/project-notes/ca-skeleton-frontend-operational-contract	plain-JavaScript ca-skeleton-frontend 스켈레톤에서 zod 를 API 응답·폼 입력 등 경계의 런타임 스키마 검증 계층으로 채택하는 근거 (컴파일 타임 타입 부재를 런타임 `.parse()`/`.safeParse()` 로 보완)

출처 / Source

원본 URL: https://zod.dev/ (Intro 페이지) + https://zod.dev/basics (Basic usage 페이지 — .parse()/.safeParse()/에러 처리 상세)
아카이브 URL: (미수집)
저자 / 조직: Colin McDonnell (@colinhacks) — Zod 프로젝트 메인테이너, zod.dev 는 프로젝트 공식 문서 사이트
발행일: 명시 없음 (페이지 배너 기준 "Zod 4 is now stable" — Zod 4 시점 문서, 정확한 발행일은 문서에 없음)
마지막 확인일: 2026-07-18

왜 저장했는지 / Why archived

ca-skeleton-frontend 는 plain JavaScript(컴파일 타임 타입 없음) 스켈레톤이므로, API 응답이나 폼 입력처럼 신뢰할 수 없는 외부 데이터가 들어오는 경계에서 컴파일러가 형태를 보장해줄 수 없다. zod 의 .parse()/.safeParse() 는 "스키마를 먼저 정의하고, 그 스키마로 실제 데이터를 런타임에 검증한다"는 계약을 공식 API로 제공하므로, 이 경계 검증 계층 채택의 1차 근거로 보관.

핵심 인용 / Key quotes (verbatim, 5문장)

[Intro §Introduction] "Zod is a TypeScript-first validation library. Using Zod, you can define schemas you can use to validate data, from a simple string to a complex nested object." — https://zod.dev/ (fetched text line 8)

[Intro §Features] "Works with TypeScript and plain JS" — https://zod.dev/ (fetched text line 25)

[Basics §Parsing data] "Given any Zod schema, use .parse to validate an input. If it's valid, Zod returns a strongly-typed deep clone of the input." — https://zod.dev/basics (fetched text line 102)

[Basics §Handling errors] "When validation fails, the .parse() method will throw a ZodError instance with granular information about the validation issues." — https://zod.dev/basics (fetched text line 108)

[Basics §Handling errors] "To avoid a try/catch block, you can use the .safeParse() method to get back a plain result object containing either the successfully parsed data or a ZodError. The result type is a discriminated union, so you can handle both cases conveniently." — https://zod.dev/basics (fetched text line 131)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
ZOD-VALID-C1	Zod 는 스스로를 "TypeScript-first validation library"로 정의하며, 단순 string 부터 복잡한 nested object 까지 스키마를 먼저 정의(schema-first)한 뒤 그 스키마로 데이터를 검증하는 사용 방식을 공식 소개한다	[Intro §Introduction] "Zod is a TypeScript-first validation library. Using Zod, you can define schemas you can use to validate data, from a simple string to a complex nested object."	`official-vendor-doc`	zod 를 schema-first 검증 라이브러리로 채택하는 모든 근거	이 진술 자체는 "TypeScript-first"가 TypeScript 없이도(plain JS) 동일 가치를 준다는 것까지는 증명 안 함 — 그건 C2 근거 필요
ZOD-VALID-C2	Zod 는 공식 Features 목록에 "Works with TypeScript and plain JS"를 명시한다 — TypeScript 컴파일 타입이 없는 환경에서도 라이브러리가 동작함을 공식 문서가 직접 진술	[Intro §Features] "Works with TypeScript and plain JS"	`official-vendor-doc`	plain-JavaScript(컴파일 타임 타입 없음) 프로젝트에서 zod 를 런타임 검증 라이브러리로 쓰는 기술적 정당성	plain JS 환경에서의 DX(자동완성·타입추론 부재로 인한 개발 경험 저하) 비교, 또는 Yup/ajv/io-ts 등 대안 대비 우위는 증명 안 함 — 비교 진술 없음
ZOD-VALID-C3	`.parse()` 는 스키마로 입력을 검증하고, 유효하면 "strongly-typed deep clone of the input"을 반환한다 — 즉 원본 입력이 아니라 검증을 통과한 복제본을 돌려주는 런타임 강제(enforcement) 지점	[Basics §Parsing data] "Given any Zod schema, use .parse to validate an input. If it's valid, Zod returns a strongly-typed deep clone of the input."	`official-reference`	API 응답/폼 입력 등 경계에서 `.parse()` 를 단일 검증 관문(gate)으로 쓰는 설계	"parse, don't validate" 라는 용어 자체는 이 원문에 등장하지 않음 — 이는 이 branch/문서의 해석적 이름 붙이기이며 zod 공식 문서의 직접 주장이 아님. 대량 트래픽에서 deep clone 의 성능 비용도 증명 안 함
ZOD-VALID-C4	검증 실패 시 `.parse()` 는 "validation issues에 대한 세분화된 정보"를 담은 `ZodError` 인스턴스를 throw 한다 (path/code/message 단위)	[Basics §Handling errors] "When validation fails, the .parse() method will throw a ZodError instance with granular information about the validation issues."	`official-reference`	throw-기반 실패 신호로 잘못된 API 응답/폼 입력을 경계에서 즉시 차단(fail-fast)하는 패턴의 근거	특정 프레임워크(React error boundary 등)와의 통합 동작은 이 문서 범위 밖 — 별도 확인 필요
ZOD-VALID-C5	`.safeParse()` 는 try/catch 없이 `{success, data}` 또는 `{success:false, error}` 형태의 discriminated union 결과 객체를 반환한다	[Basics §Handling errors] "To avoid a try/catch block, you can use the .safeParse() method to get back a plain result object containing either the successfully parsed data or a ZodError. The result type is a discriminated union, so you can handle both cases conveniently."	`official-reference`	폼 필드별 검증처럼 예외를 던지지 않고 결과를 분기 처리해야 하는 경계(non-throwing) 검증 패턴의 근거	`.parse()`(throw) vs `.safeParse()`(non-throw) 중 어느 쪽이 API 응답과 폼 입력 각각에 "권장"되는지는 이 문서가 규정하지 않음 — 프로젝트 자체 결정 사항

Strength 참고

C1·C2 는 라이브러리의 정체성/기능 목록에 대한 공식 진술이므로 official-vendor-doc, C3~C5 는 API 사용법(reference)에 대한 공식 진술이므로 official-reference 로 구분. 5개 모두 zod 메인테이너가 운영하는 프로젝트 공식 문서(zod.dev)에서 직접 발췌 — 제3자 해설이 아님.

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- ZOD-VALID-C1: zod 는 schema-first 검증 라이브러리로 스스로를 정의
- ZOD-VALID-C2: zod 는 공식적으로 "plain JS" 환경 동작을 지원한다고 명시
- ZOD-VALID-C3: .parse() 가 검증 통과 시 검증된 복제 데이터를 반환하는 런타임 관문 역할
- ZOD-VALID-C4: .parse() 실패 시 세분화된 정보를 담은 ZodError throw
- ZOD-VALID-C5: .safeParse() 는 non-throwing discriminated union 결과를 반환
이 자료가 증명하지 않는 것:
- "parse, don't validate" 라는 용어/원칙 자체 — 원문에 이 표현은 등장하지 않음. 이 phrase 를 이 자료의 공식 주장인 것처럼 branch-note 등에 인용하면 안 됨 (UNSUPPORTED — 해당 용어는 별도 출처 필요)
- zod 가 plain-JS 런타임 검증 라이브러리 중 "최선" 또는 "업계 표준"이라는 비교 우위 — Yup, io-ts, ajv 등과의 비교는 이 문서에 없음
- API 응답 검증과 폼 입력 검증 각각에 .parse() vs .safeParse() 중 무엇을 써야 하는지에 대한 공식 권고 — 문서는 두 API 의 존재와 동작만 설명, 사용처별 권장은 안 함
- React Hook Form 등 특정 폼 라이브러리와의 통합 시 실제 동작 계약(문서는 "Ecosystem" 섹션에서 이름만 언급, 세부 계약 없음)
내 프로젝트(ca-skeleton-frontend)에 적용하려면 추가 확인이 필요한 것:
- 실제 fetch/axios 클라이언트에서 API 응답에 zod 스키마를 어디서(예: 클라이언트 wrapper 레벨 vs 개별 호출 레벨) 적용할지의 아키텍처 결정 — 이 자료는 API 자체 사용법만 제공, wiring 위치는 프로젝트 자체 결정
- 폼 라이브러리 선택 시 zod 와의 실제 통합 동작(에러 메시지 매핑 등) 로컬 검증 필요

메모 / Notes

WebFetch 도구는 소스를 요약/paraphrase 하는 경향이 있어(작은 모델 경유), self-grep 검증이 불가능했다. 대신 curl 로 원본 HTML(SSR)을 직접 가져와 python 으로 태그 제거 후 verbatim 텍스트를 만들고 그 파일에 대해 self-grep 했다 — 이 과정이 이 자료의 유일한 신뢰 가능한 검증 경로였음을 기록.
fetch 한 두 페이지: Intro(/)와 Basic usage(/basics). Defining schemas(/api) 페이지는 이번 dispatch 범위 밖 — 추후 zod 의 세부 타입(z.string(), z.object() 옵션 등) 근거가 필요하면 별도 raw 문서로 추가 조사 권장.
다음 fetch 후보: https://zod.dev/error-customization (에러 메시지 커스터마이징 — 폼 UX 관련 있을 수 있음), https://zod.dev/api (Defining schemas 전체 레퍼런스).

같은 주제 다른 official-doc: (미작성 — 이번 조사 기준 vault 내 zod 관련 최초 raw 문서)
인용하는 project: raw/project-notes/ca-skeleton-frontend-operational-contract
이 자료를 인용한 wiki 요약: (생성 시 추가)

10 KiB Raw Permalink Blame History