CRES

common-resolver first transforms each raw error object into a CEF (Common ErrorObject Format). This normalizes different error shapes into a consistent structure, and then converts that structure into a user-friendly CRES (Common-Resolver ErrorObject Structure). These converters are defined inside each resolver, and the CEF has the form { [path: string]: string }.

const CEF = {
  agreeToTerms: "모든 약관에 동의해야 합니다",
  agreeToTerms.marketingTerms: "마케팅 수신 동의에 동의해야 합니다",
  email: "이메일 형식이 아닙니다",
  root: '비밀번호가 일치하지 않습니다'
}

CRES is the canonical error response format provided by common-resolver. It standardizes errors from various sources, allowing developers to manage disparate error shapes without writing custom parsing logic. Given an input value and the schema that validates it, CRES shows where errors occurred in a predictable layout.

const value = {
  email: "test",
  nickname: "test",
  password: "test1234!",
  passwordCheck: "test1234",
  agreeToTerms: {
    theTerms: true,
    personalTerms: true,
    marketingTerms: false,
  },
}
 
const zSchema = z.object({
  email: z.string().email("이메일 형식이 아닙니다").min(1, "이메일은 필수입니다"),
  nickname: z.string().min(1, "닉네임은 필수입니다"),
  password: z.string().min(1, "비밀번호는 필수입니다"),
  passwordCheck: z.string().min(1, "비밀번호 확인은 필수입니다"),
  agreeToTerms: z.object(
    {
      theTerms: z.boolean().refine(val => val, { message: "이용약관에 동의해야 합니다" }),
      personalTerms: z.boolean().refine(val => val, { message: "개인정보 수집 및 이용에 동의해야 합니다" }),
      marketingTerms: z.boolean().refine(val => val, { message: "마케팅 수신 동의에 동의해야 합니다" }),
    }
  ).refine(val => val.theTerms && val.personalTerms && val.marketingTerms, { message: "모든 약관에 동의해야 합니다" }),
}).refine(data => {
  if (data.password !== data.passwordCheck) {
    return false;
  }
  return true;
}, "비밀번호가 일치하지 않습니다")

CRES is shaped as shown below. Each entry may include a root property that represents an error for the object or array itself. If root is omitted, it can be difficult to express a top-level object error for nested entries like agreeToTerms.marketingTerms. The root field allows conveying both specific sub-property errors and general object-level errors, resulting in simpler and more flexible error handling.

const CRES = {
  agreeToTerms: {
    marketingTerms: { root: '마케팅 수신 동의에 동의해야 합니다' },
    root: '모든 약관에 동의해야 합니다'
  },
  email: { root: '이메일 형식이 아닙니다' },
  root: '비밀번호가 일치하지 않습니다'
}

common-resolver wraps CRES with a Proxy object. The Proxy does several helpful things: when accessing a path it can automatically return a root value for that path, and if a nested object exists it will return another Proxy so accesses are recursive. This lets developers navigate nested error structures without checking each level manually. The Proxy also prevents modifications or deletions of error properties, preserving the immutability of error messages. In cases where a property is present, the Proxy may synthesize a virtual entry to make lookups consistent and convenient.

type CRES<T> = RecursivePartial<T> & { "root"?: string };
 
export type RecursivePartial<T> = {
  [P in keyof T]?: T[P] extends object
    ? RecursivePartial<T[P]>
    : string;
};

Regarding the CRES type definition: only the top level may optionally contain root, while nested entries are treated as if they do not have root. At runtime TypeScript may consider the root field to be an object instead of a string, which is inconvenient when trying to read it directly. Although not ideal, the pragmatic approach is to use an explicit cast (as string) when accessing root values.

Consider a modification to RecursivePartial below. With this shape, deep property access using dot notation requires checking whether each step is a string or an object, otherwise TypeScript will complain. Rather than encoding precise runtime shapes, the practical choice is to assert the root value as string at the call site to avoid repeated type checks.

export type RecursivePartial<T> = {
  [P in keyof T]?: T[P] extends object
    ? RecursivePartial<T[P]> | string
    : string;
};