common-resolver는 다양한 환경에서 반복되는 문제를 간단하고 일관되게 해결하는 범용 라이브러리입니다. 특히 zod (v3, v4), yup, superstruct 같은 검증 라이브러리를 통일된 어댑터 인터페이스로 적용할 수 있어 검증 로직을 손쉽게 교체·재사용할 수 있으며, 최소한의 설정으로 빠르게 통합되고 모듈화된 설계로 확장성과 유연성을 제공합니다.
common-resolver는 아래와 같은 기능을 제공합니다. 각 스키마 유효성 검증 라이브러리에 대한 resolver와 함께, 스키마를 검증하는 타입 가드 함수를 제공합니다. getResolver 함수는 입력된 스키마의 타입을 자동으로 감지하여 적절한 resolver를 선택하므로, 코드를 전환할 때 최소한의 변경만으로 다른 유효성 검증 라이브러리로 쉽게 마이그레이션할 수 있습니다.
또한 ValidateSchema와 Resolver와 같은 타입 정의를 통해 타입스크립트 환경에서 완벽한 타입 안전성을 제공하므로, 코드 작성 시 자동 완성 및 타입 오류 감지의 이점을 누릴 수 있습니다. 이러한 기능들을 통해 개발자는 복잡한 스키마 검증 로직에 집중하지 않고 비즈니스 로직 구현에 더 집중할 수 있습니다.
import { zodResolver, isZodSchema } from "@ilokesto/common-resolver/zod"
import { yupResolver, isYupSchema } from "@ilokesto/common-resolver/yup"
import { superstructResolver, isSuperStructSchema } from "@ilokesto/common-resolver/superstruct"
import { getResolver } from "@ilokesto/common-resolver/getResolver"
import { ValidateSchema, Resolver } "@ilokesto/common-resolver/types"
다음은 Zod 스키마를 사용하는 간단한 예제입니다. 여기서는 문자열 타입의 스키마를 정의하고 최소 길이가 1 이상이어야 한다는 제약을 설정했습니다. 빈 문자열("")을 validate 메서드에 전달하면 길이 조건을 충족하지 못해 유효성 검사에 실패합니다. 이때 반환되는 error 객체에는 "root" 속성에 오류 메시지("zSchema는 필수입니다")가 포함됩니다. 이 예제는 단일 값에 대한 검증이므로 특정 필드 대신 "root" 속성에 오류가 기록됩니다. 복잡한 객체 구조에서는 각 필드별로 오류 메시지가 해당 필드의 경로에 매핑되어 표시됩니다.
아래의 코드는 전역 상태 관리 도구 caro-kann 에서 유효성 검증을 위한 미들웨어를 구현한 것입니다. validate 함수는 초기 상태와 스키마 유효성 검사기를 인자로 받아 상태가 변경될 때마다 자동으로 검증을 수행합니다. getResolver 함수를 사용하여 스키마 유형에 관계없이 동일한 인터페이스로 검증을 처리하고, 상태 변경이 유효하지 않을 경우 오류를 기록하고 상태 업데이트를 차단합니다. 이 방식으로 애플리케이션의 상태가 항상 스키마를 준수하도록 보장합니다.
어떤 라이브러리를 사용하였는지와 상관 없이 스키마를 validate의 두 번째 아규먼트로 제공하게 되면 caro-kann이 common-resolver의 도움을 통해 적절한 resolver를 자동으로 감지하고 선택합니다. 이는 getResolver 함수가 내부적으로 주어진 스키마의 타입(Zod, Yup, Superstruct 등)을 분석하여 그에 맞는 리졸버를 반환하기 때문입니다. 덕분에 caro-kann을 사용하는 개발자들은 별도의 코드 수정 없이 스키마 객체만 교체할 수 있습니다. 이러한 유연성은 프로젝트 요구사항이 변경되거나 다양한 검증 라이브러리를 실험해보고 싶을 때 특히 유용합니다.
import { create } from "caro-kann"
import { z } from "zod";
const zSchema = z.string({ message: "string이어야 합니다" });
const useNumber = create(validate("", zSchema))
폼 관리 도구 sicilian의 핵심 유효성 검증 로직인 Validate 클래스는 상태 저장소, 오류 설정 함수, 그리고 common-resolver의 Resolver 객체를 받습니다. doValidate 메서드는 사용자 입력 이벤트에 반응하여 현재 폼 상태에 대한 유효성 검사를 실행하고, 오류가 발생하면 해당 필드에 대한 오류 메시지를 설정합니다. 이 구조는 각 입력 필드별로 즉각적인 피드백을 제공하면서도 전체 폼의 일관성을 유지합니다.
import type { Resolver } from "@ilokesto/common-resolver/types";
export class Validate<T extends InitState> implements IValidate {
constructor(
private store: IStore<T>,
private setError: (action: Partial<T>) => void,
private resolver: Resolver<T> | undefined
) {}
public doValidate = ({ target: { name } }: SicilianEvent) => {
const store = this.store.getStore();
if (this.resolver) {
const { valid, error } = this.resolver.validate(store);
if (!valid) {
this.setError({ [name]: typeof error[name] === "string" ? error[name] : "" })
return;
}
}
}
}
sicilian은 common-resolver의 기능을 자체 API로 재노출합니다. 이렇게 함으로써 사용자는 common-resolver 패키지에 대한 직접적인 의존성 없이 사용자 경험을 단순화하고 일관성을 유지합니다.
export { zodResolver } from "@ilokesto/common-resolver/zod";
export { yupResolver } from "@ilokesto/common-resolver/yup";
export { superstructResolver } from "@ilokesto/common-resolver/superstruct";
아래 예시는 복잡한 회원가입 폼에 대한 유효성 검사를 Zod 스키마를 사용하여 구현한 것입니다. 이메일, 닉네임, 비밀번호, 비밀번호 확인, 이용약관 동의 등 다양한 필드에 대한 상세한 검증 규칙을 정의하고 있습니다. 특히 refine 메서드를 사용하여 비밀번호와 비밀번호 확인 필드의 일치 여부와 같은 필드 간 의존성 검증도 수행합니다. 이 스키마는 zodResolver를 통해 sicilian 폼 컨트롤러에 전달되어, 선언적으로 정의된 모든 규칙에 따라 사용자 입력의 유효성을 자동으로 검증합니다.