Introduce the common-resolver

common-resolver is a lightweight, universal library designed to solve recurring validation and error-handling problems in a simple and consistent way across different environments. It provides adapter interfaces for validation libraries such as zod (v3, v4), yup, and superstruct so you can swap and reuse validation logic with minimal changes. Its modular design makes it quick to integrate and easy to extend, while keeping configuration minimal.

Installation#

You can install common-resolver using any of the methods shown below.

npm install @ilokesto/common-resolver
pnpm add @ilokesto/common-resolver
yarn add @ilokesto/common-resolver
bun add @ilokesto/common-resolver

Features#

common-resolver provides the following features. Along with resolvers for each schema validation library, it exposes type-safe helper functions that validate schemas. The getResolver function automatically detects the type of the provided schema and selects the appropriate resolver, so switching validation libraries requires minimal code changes.

Additionally, type definitions such as ValidateSchema and Resolver offer complete TypeScript safety, enabling IDE autocompletion and compile-time error checks. These features let developers focus on business logic instead of the intricacies of schema validation.

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"

Below is a simple example using a Zod schema. The schema defines a string type with a minimum length of 1. Passing an empty string ("") to the validate method will fail the length check and produce an error object that includes a message ("zSchema is required") under the special "root" property. This example is for a single value, so errors are recorded on the "root" property instead of on a specific field. For complex object structures, errors are mapped to each field path accordingly.

const zSchema = z.string({ message: "string이어야 합니다" }).min(1, "zSchema는 필수입니다");

zodResolver(zSchema).validate("").error // {root: "zSchema는 필수입니다"}

Using common-resolver in the global state manager caro-kann#

The code below demonstrates a middleware in the caro-kann global state manager that performs validation. The validate function accepts the initial state and a schema validator, and automatically validates whenever state changes. By using getResolver, the middleware can handle different schema types through the same interface. If the state is invalid, the middleware logs the error and blocks the state update, ensuring the application state always conforms to the schema.

import { getResolver } from "@ilokesto/common-resolver/getResolver";
import { ValidateSchema } from "@ilokesto/common-resolver/types";

export const validate: Middleware["validate"] = <T>(initState: T | MiddlewareStore<T>, validator: ValidateSchema<T>["zod" | "yup" | "superstruct"]) => {
  const Store = getStoreFromInitState(initState);
  const validateScheme = getResolver(validator);

  const setStore = (nextState: T | ((prev: T) => T)) => {
    const newState = typeof nextState === "function" ? (nextState as (prev: T) => T)(Store.getStore()) : nextState;

    const { valid, error } = validateScheme.validate(newState);

    if (!valid) {
      console.error(`[Validation Error] Invalid state:`, error);
      return;
    }

    Store.setStore(newState);
  };

  return {
    store: { ...Store, setStore },
    [storeTypeTag]: "validate"
  };
};

Regardless of which validation library you use, passing a schema as the second argument to validate allows caro-kann to detect and pick the appropriate resolver via common-resolver. getResolver inspects the provided schema (Zod, Yup, Superstruct, etc.) and returns the matching resolver, so caro-kann users can replace schema objects without changing other code. This flexibility is especially useful when project requirements change or when experimenting with different validation libraries.

import { create } from "caro-kann"
import { z } from "zod";

const zSchema = z.string({ message: "string이어야 합니다" });

const useNumber = create(validate("", zSchema))

Using common-resolver in the form manager sicilian#

The Validate class inside sicilian receives a state store, an error setter, and a Resolver object from common-resolver. Its doValidate method runs validation in response to user input events and sets field-specific error messages when validation fails. This structure provides immediate per-field feedback while maintaining overall form consistency.

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 re-exposes common-resolver functionality through its own API, simplifying the developer experience and reducing direct dependencies on the common-resolver package.

export { zodResolver } from "@ilokesto/common-resolver/zod";
export { yupResolver } from "@ilokesto/common-resolver/yup";
export { superstructResolver } from "@ilokesto/common-resolver/superstruct";

The example below shows a complex signup form validated by a Zod schema. The schema includes rules for email, nickname, password, password confirmation, and terms agreement. It uses zod's refine method for cross-field checks such as ensuring password and passwordCheck match. The zodResolver passes this schema to the sicilian form controller so all rules are enforced declaratively and user input is validated automatically.

import { CreateForm } from "sicilian"
import { zodResolver } from "sicilian/resolver"
import { z } from "zod";

const zSchema = z.object({
  email: z.string()
    .email('유효한 이메일 주소를 입력해 주세요')
    .min(1, '이메일은 필수 입력 항목입니다'),
  
  nickname: z.string()
    .min(2, '닉네임은 2글자 이상이어야 합니다')
    .max(20, '닉네임은 20글자 이하여야 합니다'),
  
  password: z.string()
    .max(100, '비밀번호는 100자 이하여야 합니다')
    .regex(/[a-z]/, '최소 하나의 소문자를 포함해야 합니다')
    .regex(/[0-9]/, '최소 하나의 숫자를 포함해야 합니다')
    .regex(/[^a-zA-Z0-9]/, '최소 하나의 특수문자를 포함해야 합니다')
    .min(8, '비밀번호는 8자 이상이어야 합니다'),
  
  passwordCheck: z.string()
    .min(1, '비밀번호 확인은 필수 입력 항목입니다'),
  
  agreeToTerms: z.boolean()
    .refine(val => val === true, {
      message: '이용약관에 동의해 주세요'
    })
}).refine(data => {
  return data.password === data.passwordCheck
}, {
  message: '비밀번호가 일치하지 않습니다',
  path: ['passwordCheck']
});

const signFormController = new CreateForm({
  initState: {
    email: "",
    nickname: "",
    password: "",
    passwordCheck: "",
    agreeToTerms: false,
  },
  resolver: zodResolver(zSchema)
})