gem-hunter
Language: TypeScript
Wrap zod validation errors in user-friendly readable messages
Wrap zod validation errors in user-friendly readable messages.
error.details;Note: This version of zod-validation-error works with zod v4. If you are looking for zod v3 support, please refer to the v3 documentation
npm install zod-validation-error
import { z as zod } from 'zod'; import { fromError, createErrorMap } from 'zod-validation-error'; // configure zod to use zod-validation-error's error map // this is optional, you may also use your own custom error map or zod's native error map // we recommend using zod-validation-error's error map for better user-friendly messages // see https://zod.dev/error-customization for further details zod.config({ customError: createErrorMap(), }); // create zod schema const zodSchema = zod.object({ id: zod.int().positive(), email: zod.email(), }); // parse some invalid value try { zodSchema.parse({ id: 1, email: 'coyote@acme', // note: invalid email }); } catch (err) { const validationError = fromError(err); // the error is now readable by the user // you may print it to console console.log(validationError.toString()); // or return it as an actual error return validationError; }
Zod errors are difficult to consume for the end-user. This library wraps Zod validation errors in user-friendly readable messages that can be exposed to the outer world, while maintaining the original errors in an array for dev use.
[
{
"origin": "number",
"code": "too_small",
"minimum": 0,
"inclusive": false,
"path": ["id"],
"message": "Number must be greater than 0 at \"id\""
},
{
"origin": "string",
"code": "invalid_format",
"format": "email",
"pattern": "/^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$/",
"path": ["email"],
"message": "Invalid email at \"email\""
}
]Validation error: Number must be greater than 0 at "id"; Invalid email at "email"
Main ValidationError class, extending JavaScript's native Error.
message - string; error message (required)options - ErrorOptions; error options as per JavaScript definition (optional)
options.cause - any; can be used to hold the original zod error (optional)import { ValidationError } from 'zod-validation-error'; const error = new ValidationError('foobar'); console.log(error instanceof Error); // prints true
import { z as zod } from 'zod'; import { ValidationError } from 'zod-validation-error'; const error = new ValidationError('foobar', { cause: new zod.ZodError([ { origin: 'number', code: 'too_small', minimum: 0, inclusive: false, path: ['id'], message: 'Number must be greater than 0 at "id"', input: -1, }, ]), }); console.log(error.details); // prints issues from zod error
Creates zod-validation-error's errorMap, which is used to format issues into user-friendly error messages.
We think that zod's native error map is not user-friendly enough, so we provide our own implementation that formats issues into human-readable messages.
Note: zod-validation-error's errorMap is an errorMap like all others and thus can also be used directly with zod (see https://zod.dev/error-customization for further details), e.g.
options - Object; formatting options (optional)| Name | Type | Description |
|---|---|---|
displayInvalidFormatDetails |
boolean |
Indicates whether to display invalid format details (e.g. regexp pattern) in the error message (optional, defaults to false) |
reportInput |
false | "type" | "typeAndValue" |
Indicates whether to report the user input in the error message (optional, defaults to "type") |
maxAllowedValuesToDisplay |
number |
Max number of allowed values to display (optional, defaults to 10). Allowed values beyond this limit will be hidden. |
allowedValuesSeparator |
string |
Used to concatenate allowed values in the message (optional, defaults to ", ") |
allowedValuesLastSeparator |
string | undefined |
Used to concatenate last allowed value in the message (optional, defaults to " or "). Set to undefined to disable. |
wrapAllowedValuesInQuote |
boolean |
Indicates whether to wrap allowed values in quotes (optional, defaults to true). Note that this only applies to string values. |
maxUnrecognizedKeysToDisplay |
number |
Max number of unrecognized keys to display in the error message (optional, defaults to 5) |
unrecognizedKeysSeparator |
string |
Used to concatenate unrecognized keys in the message (optional, defaults to ", ") |
unrecognizedKeysLastSeparator |
string | undefined |
Used to concatenate the last unrecognized key in message (optional, defaults to " and "). Set to undefined to disable. |
wrapUnrecognizedKeysInQuote |
boolean |
Indicates whether to wrap unrecognized keys in quotes (optional, defaults to true). Note that this only applies to string keys. |
dateLocalization |
boolean | Intl.LocalesArgument |
Indicates whether to localize date values (optional, defaults to true). If set to true, it will use the default locale of the environment. You can also pass Intl.LocalesArgument to specify a custom locale. |
numberLocalization |
boolean | Intl.LocalesArgument |
Indicates whether to localize numeric values (optional, defaults to true). If set to true, it will use the default locale of the environment. You can also pass Intl.LocalesArgument to specify a custom locale. |
import { z as zod } from 'zod'; import { createErrorMap } from 'zod-validation-error'; zod.config({ customError: createErrorMap({ // default values are used when not specified displayInvalidFormatDetails: true, }), });
Creates zod-validation-error's default MessageBuilder, which is used to produce user-friendly error messages.
Meant to be passed as an option to fromError, fromZodIssue, fromZodError or toValidationError.
options - Object; formatting options (optional)| Name | Type | Description |
|---|---|---|
maxIssuesInMessage |
number |
Max issues to include in user-friendly message (optional, defaults to 99) |
issueSeparator |
string |
Used to concatenate issues in user-friendly message (optional, defaults to ";") |
unionSeparator |
string |
Used to concatenate union-issues in user-friendly message (optional, defaults to " or ") |
prefix |
string | undefined |
Prefix to use in user-friendly message (optional, defaults to "Validation error"). Pass undefined to disable prefix completely. |
prefixSeparator |
string |
Used to concatenate prefix with rest of the user-friendly message (optional, defaults to ": "). Not used when prefix is undefined. |
includePath |
boolean |
Indicates whether to include the erroneous property key in the error message (optional, defaults to true) |
forceTitleCase |
boolean |
Indicates whether to convert individual issue messages to title case (optional, defaults to true). |
import { createMessageBuilder } from 'zod-validation-error'; const messageBuilder = createMessageBuilder({ maxIssuesInMessage: 3, includePath: false, });
A type guard utility function, based on instanceof comparison.
error - error instance (required)import { z as zod } from 'zod'; import { ValidationError, isValidationError } from 'zod-validation-error'; const err = new ValidationError('foobar'); isValidationError(err); // returns true const invalidErr = new Error('foobar'); isValidationError(err); // returns false
A type guard utility function, based on heuristics comparison.
Why do we need heuristics since we can use a simple instanceof comparison? Because of multi-version inconsistencies. For instance, it's possible that a dependency is using an older zod-validation-error version internally. In such case, the instanceof comparison will yield invalid results because module deduplication does not apply at npm/yarn level and the prototype is different.
tl;dr if you are uncertain then it is preferable to use isValidationErrorLike instead of isValidationError.
error - error instance (required)import { ValidationError, isValidationErrorLike } from 'zod-validation-error'; const err = new ValidationError('foobar'); isValidationErrorLike(err); // returns true const invalidErr = new Error('foobar'); isValidationErrorLike(err); // returns false
A type guard utility function, based on heuristics comparison.
Why do we need heuristics since we can use a simple instanceof comparison? Because of multi-version inconsistencies. For instance, it's possible that a dependency is using an older zod version internally. In such case, the instanceof comparison will yield invalid results because module deduplication does not apply at npm/yarn level and the prototype is different.
error - error instance (required)import { z as zod } from 'zod'; import { ValidationError, isZodErrorLike } from 'zod-validation-error'; const zodValidationErr = new ValidationError('foobar'); isZodErrorLike(zodValidationErr); // returns false const genericErr = new Error('foobar'); isZodErrorLike(genericErr); // returns false const zodErr = new zod.ZodError([ { origin: 'number', code: 'too_small', minimum: 0, inclusive: false, path: ['id'], message: 'Number must be greater than 0 at "id"', input: -1, }, ]); isZodErrorLike(zodErr); // returns true
Converts an error to ValidationError.
What is the difference between fromError and fromZodError? The fromError function is a less strict version of fromZodError. It can accept an unknown error and attempt to convert it to a ValidationError.
error - unknown; an error (required)options - Object; formatting options (optional)
messageBuilder - MessageBuilder; a function that accepts an array of zod.ZodIssue objects and returns a user-friendly error message in the form of a string (optional).Alternatively, you may pass createMessageBuilder options directly as options. These will be used as arguments to create the MessageBuilder instance internally.
Converts a single zod issue to ValidationError.
zodIssue - zod.ZodIssue; a ZodIssue instance (required)options - Object; formatting options (optional)
messageBuilder - MessageBuilder; a function that accepts an array of zod.ZodIssue objects and returns a user-friendly error message in the form of a string (optional).Alternatively, you may pass createMessageBuilder options directly as options. These will be used as arguments to create the MessageBuilder instance internally.
Converts zod error to ValidationError.
Why is the difference between ZodError and ZodIssue? A ZodError is a collection of 1 or more ZodIssue instances. It's what you get when you call zodSchema.parse().
zodError - zod.ZodError; a ZodError instance (required)options - Object; formatting options (optional)
messageBuilder - MessageBuilder; a function that accepts an array of zod.ZodIssue objects and returns a user-friendly error message in the form of a string (optional).Alternatively, you may pass createMessageBuilder options directly as options. These will be used as arguments to create the MessageBuilder instance internally.
A curried version of fromZodError meant to be used for FP (Functional Programming). Note it first takes the options object if needed and returns a function that converts the zodError to a ValidationError object
toValidationError(options) => (zodError) => ValidationError
import * as Either from 'fp-ts/Either'; import { z as zod } from 'zod'; import { toValidationError, ValidationError } from 'zod-validation-error'; // create zod schema const zodSchema = zod .object({ id: zod.int().positive(), email: zod.email(), }) .brand<'User'>(); export type User = zod.infer<typeof zodSchema>; export function parse( value: zod.input<typeof zodSchema> ): Either.Either<ValidationError, User> { return Either.tryCatch(() => schema.parse(value), toValidationError()); }
While both libraries aim to provide a human-readable string representation of a zod error, they differ in several ways...
Disclaimer: as per this comment, we have no intention to antagonize zod. In fact, we are happy to decommission this module assuming it's in the best interest of the community. As of now, it seems that there's room for both zod-validation-error and prettifyError, also based on Colin McDonnell's response.
No, you can use zod's native error map if you prefer. However, we recommend using zod-validation-error's error map for better user-friendly messages.
You may also use your own custom error map if you have specific requirements, e.g. internationalization.
The easiest way to understand how zod-validation-error's error map works is to look at the tests. They cover various scenarios and demonstrate how the error map formats issues into user-friendly messages.
Use the isValidationErrorLike type guard.
Scenario: Distinguish between ValidationError VS generic Error in order to respond with 400 VS 500 HTTP status code respectively.
import { isValidationErrorLike } from 'zod-validation-error'; try { func(); // throws Error - or - ValidationError } catch (err) { if (isValidationErrorLike(err)) { return 400; // Bad Data (this is a client error) } return 500; // Server Error }
It's possible to implement custom validation logic outside zod and throw a ValidationError.
import { ValidationError } from 'zod-validation-error'; import { Buffer } from 'node:buffer'; function parseBuffer(buf: unknown): Buffer { if (!Buffer.isBuffer(buf)) { throw new ValidationError('Invalid argument; expected buffer'); } return buf; }
import { ValidationError } from 'zod-validation-error'; try { // do something that throws an error } catch (err) { throw new ValidationError('Something went deeply wrong', { cause: err }); }
Zod supports customizing error messages by providing a custom "error map". You may combine this with zod-validation-error to produce user-friendly messages.
If all you need is to produce user-friendly error messages you may use the customError property.
import { z as zod } from 'zod'; import { createErrorMap } from 'zod-validation-error'; zod.config({ customError: createErrorMap({ includePath: true, }), });
zod-validation-error will respect the customError property when it is set, no further configuration is needed.
Yes, zod-validation-error supports CommonJS out-of-the-box. All you need to do is import it using require.
const { ValidationError } = require('zod-validation-error');
Source code contributions are most welcome. Please open a PR, ensure the linter is satisfied and all tests pass.
Causaly is building the world's largest biomedical knowledge platform, using technologies such as TypeScript, React and Node.js. Find out more about our openings at https://jobs.ashbyhq.com/causaly.
MIT