zod-error

Zod Error converts Zod’s raw validation issue arrays into a readable, fully customizable string instead of leaving consumers to walk ZodIssue objects by hand. Every part of the output is configurable: which components (code, path, message) are shown, their labels, the delimiter between components and between multiple errors, a prefix/suffix, a cap on how many issues get concatenated, and a per-component or whole-error transform callback for complete control.

On top of the formatter, the library ships drop-in replacements for Zod’s own parsing methods — parse, parseAsync, safeParse, and safeParseAsync — that internally call schema.safeParse/safeParseAsync and translate any ZodError into a plain Error with the formatted message, so downstream code never has to import Zod’s error types directly. Path rendering supports three styles (dot/object notation, raw Zod path arrays, and breadcrumb notation), each with optional square brackets around array indices. The package tracks Zod’s major versions explicitly: 1.x targets Zod 3, 2.x targets Zod 4’s new issue schema.

What You Get

• generateErrorMessage() to format an array of Zod issues into a single string with full control over components, labels, delimiters, prefix/suffix, and max error count
• generateError() to convert any thrown value (ZodError or otherwise) into a plain Error carrying the formatted message
• parse/parseAsync/safeParse/safeParseAsync wrappers that mirror Zod’s own schema methods but throw or return a plain Error instead of a ZodError
• Three path-rendering styles — object notation, raw Zod path array, and breadcrumb notation — each independently configurable
• Per-component (code/path/message) and whole-error transform callbacks for full custom formatting

Common Use Cases

• Formatting Zod validation failures into a single string for API JSON error responses
• Rendering a Zod schema’s validation issues as one user-facing string in a form, modal, or toast
• Validating CLI arguments or config with Zod and throwing one readable error via parse()
• Emitting validation failures in a custom structured-logging format via a transform callback

Under The Hood

Architecture A small, purely functional utility library split into functions/ (the public entry points: parse, parseAsync, safeParse, safeParseAsync, generateError, generateErrorMessage) and utils/ (single-purpose helpers such as get-error-message, get-path-string, get-object-notation, get-breadcrumbs, get-component-delimiter, and get-component-labels). generateErrorMessage orchestrates the pipeline: it slices the issues array to a configurable maximum, maps each issue through getErrorMessage — which assembles the code/path/message components according to per-component enable/transform options — and joins the results with configurable delimiters before applying a prefix and suffix. parse/safeParse wrap Zod’s own schema methods and funnel any failure through this same formatting path, returning a plain Error rather than a ZodError. Path formatting uses a discriminated union (object notation, Zod path array, breadcrumbs) resolved by a small strategy dispatch. There is no shared mutable state, no classes, and no side effects — every file exports one composable function.

Tech Stack Written in TypeScript targeting Zod v4 as a peer dependency (the package’s own major version 2 tracks Zod’s v4 issue schema; version 1.x targets Zod 3). Tests run on Vitest 3 with @vitest/coverage-v8, linting via ESLint 8 with @typescript-eslint (recommended config plus eslint-config-prettier), formatting via Prettier 2.7, and commit messages standardized through commitizen’s conventional-changelog adapter. Builds compile straight to a lib/ directory via tsc; there are no runtime dependencies beyond the Zod peer dependency.

Code Quality Test coverage is extensive and close to 1:1 with source files — nearly every exported function in both functions/ and utils/ has a colocated .test.ts asserting concrete formatted output against real Zod schemas rather than mocks. Error handling is explicit and centralized: both parsing wrappers and the message generator funnel failures through a single formatting path and never swallow errors silently. Types are strict throughout, using discriminated unions to make invalid option combinations (e.g., a disabled component with a label) a compile-time error, and consuming Zod’s own z.core.$ZodIssue type directly rather than redeclaring it. One gap: there is no CI workflow directory in the repository, so tests, linting, and the build script are enforced only when run locally via the build npm script, not automatically on push.

API Design The library’s value is almost entirely in its composability: every message component (code, path, message) can be independently enabled, relabeled, or given a custom transform callback, path rendering supports three interchangeable styles, and a top-level transform escape hatch exposes the raw issue plus all formatted sub-components for cases the built-in options don’t cover. parse/safeParse are designed as near drop-in replacements for Zod’s own methods, so adopting the library requires changing an import rather than writing bespoke formatting logic. The trade-off is a fairly deep options object (ErrorMessageOptions) for anything beyond the defaults — the ergonomics favor flexibility over a minimal API surface.