zod-validation-error

zod-validation-error wraps the raw issue arrays that Zod schemas throw on failed validation into a single, readable ValidationError with a friendly .message string, while preserving the original issues on .details for programmatic handling or logging. Rather than exposing Zod’s internal issue codes and paths directly to end users, it renders them into natural-language sentences (“Number must be greater than 0 at “id"") that are safe to surface in an API response, form validation UI, or CLI error output.

The library ships a configurable MessageBuilder and createErrorMap factory so teams can control path inclusion, title-casing, issue and union separators, localization of dates/numbers, and how many issues get concatenated into one message. It supports both Zod v3 (via the /v3 subpath export) and Zod v4 (default export) side by side, letting consumers migrate between Zod major versions without rewriting their error-formatting layer. Utility guards like isZodErrorLike and isValidationError let calling code branch safely on error shape without importing Zod’s internal types directly.

What You Get

• fromError/fromZodError helpers that convert any caught error or ZodError into a ValidationError with a readable .message
• A ValidationError class extending native Error, exposing the original Zod issues via .details for logging or programmatic use
• createErrorMap/createMessageBuilder factories with fine-grained formatting options (prefix, separators, path inclusion, title-casing, locale-aware date/number formatting)
• Type guards (isZodErrorLike, isValidationError, isValidationErrorLike) to safely narrow unknown errors without importing Zod’s internal error types
• Parallel /v3 and /v4 (default) subpath exports so the same package supports either major version of Zod

Common Use Cases

• Formatting API request validation failures into a single user-facing message returned in an HTTP error response
• Displaying friendly inline error text under form fields after a Zod schema fails to parse form input
• Wiring createErrorMap() into zod.config({ customError }) so every Zod parse failure across an app already produces readable messages
• Logging or reporting the original structured Zod issues (via .details) to an error tracker while showing a simplified message to the user

Under The Hood

Architecture The package is organized as two structurally identical, version-scoped modules (lib/v3 and lib/v4), each exporting the same public surface (ValidationError, fromError, fromZodError, fromZodIssue, toValidationError, createErrorMap, createMessageBuilder, type guards) built against that Zod major version’s internal issue types, plus a shared lib/utils module (joinPath, joinValues, titleCase, stringify, isPrimitive, NonEmptyArray) used by both. toValidationError is the core dispatcher: it narrows an unknown thrown value with isZodErrorLike, delegates to fromZodErrorWithoutRuntimeCheck for genuine Zod errors, wraps any other Error instance directly, and falls back to a generic ValidationError('Unknown error') otherwise — so the library never throws while formatting an error. createErrorMap’s v4 implementation further composes one small pure-function parser per Zod issue code (invalid_type, too_big, invalid_union, etc.) behind a lookup table, keeping each issue-to-message mapping isolated and independently testable. Nothing in the design would break under swapping the core abstraction — the version split itself is the intentional seam for supporting two incompatible upstream schemas.

Tech Stack Written entirely in TypeScript targeting esnext/nodenext module resolution with erasableSyntaxOnly and allowImportingTsExtensions, compiled to dual CJS/ESM output via tsup and typed via a separate emitDeclarationOnly pass. Its only runtime dependency is a peer dependency on zod itself (^3.25.0 || ^4.0.0), keeping the package dependency-free otherwise. Testing runs on Vitest with the vitest/globals types, releases are managed via Changesets with a GitHub changelog generator, and commit messages are enforced by commitlint plus Husky pre-commit hooks running lint-staged (ESLint + Prettier).

Code Quality Test coverage is extensive and colocated — nearly every source file under lib/v3 and lib/v4 (and each error-map issue parser) has a matching .test.ts file exercising it directly with Vitest. ESLint is configured with @typescript-eslint/recommended, enforced consistent-type-imports, import ordering, and Prettier integration; strict: true is set in tsconfig.json. Error handling favors defensive narrowing (isZodErrorLike, instanceof Error checks) over assuming well-typed input, and a CI workflow builds, typechecks, and runs the unit test suite on every pull request before merge.

What Makes It Unique Rather than a single formatter, the library provides a fully composable, per-issue-code error-map architecture that lets consumers override formatting behavior (locale-aware dates/numbers, quoting of allowed values, union deduplication, title-casing) issue-by-issue while still producing one clean message, and it does so for two incompatible major versions of its host library (Zod v3 and v4) from the same published package via subpath exports — a maintenance approach few small validation-adjacent utilities attempt.