Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
zod-validation-error
Advanced tools
Wrap zod validation errors in user-friendly readable messages.
error.details
;npm install zod-validation-error
import { z as zod } from 'zod';
import { fromZodError } from 'zod-validation-error';
// create zod schema
const zodSchema = zod.object({
id: zod.number().int().positive(),
email: zod.string().email(),
});
// parse some invalid value
try {
zodSchema.parse({
id: 1,
email: 'foobar', // note: invalid email
});
} catch (err) {
const validationError = fromZodError(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.
[
{
"code": "too_small",
"inclusive": false,
"message": "Number must be greater than 0",
"minimum": 0,
"path": ["id"],
"type": "number"
},
{
"code": "invalid_string",
"message": "Invalid email",
"path": ["email"],
"validation": "email"
}
]
Validation error: Number must be greater than 0 at "id"; Invalid email at "email"
Main ValidationError
class, extending native JavaScript 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)message
const { ValidationError } = require('zod-validation-error');
const error = new ValidationError('foobar');
console.log(error instanceof Error); // prints true
message
and options.cause
import { z as zod } from 'zod';
const { ValidationError } = require('zod-validation-error');
const error = new ValidationError('foobar', {
cause: new zod.ZodError([
{
code: 'invalid_string',
message: 'Invalid email',
path: ['email'],
validation: 'email',
},
]),
});
console.log(error.details); // prints issues from zod error
A custom error map to use with zod's setErrorMap
method and get user-friendly messages automatically.
import { z as zod } from 'zod';
import { errorMap } from 'zod-validation-error';
zod.setErrorMap(errorMap);
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 if we have 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.
In most cases, it is safer to use isValidationErrorLike
than 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
Converts a single zod issue to ValidationError
.
zodIssue
- zod.ZodIssue; a ZodIssue instance (required)options
- Object; formatting options (optional)
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 or null; prefix to use in user-friendly message (optional, defaults to "Validation error"). Pass null
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 null
.includePath
- boolean; used to provide control on whether to include the erroneous property name suffix or not (optional, defaults to true
).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)
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 or null; prefix to use in user-friendly message (optional, defaults to "Validation error"). Pass null
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 null
.includePath
- boolean; used to provide control on whether to include the erroneous property name suffix or not (optional, defaults to true
).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.number().int().positive(),
email: zod.string().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());
}
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 * as Either from 'fp-ts/Either';
import { z as zod } from 'zod';
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
}
ValidationError
outside zod
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 });
}
ValidationError
with custom "error map"Zod supports customizing error messages by providing a custom "error map". You may combine this with zod-validation-error
to produce user-friendly messages.
errorMap
propertyIf all you need is to produce user-friendly error messages you may use the errorMap
property.
import { z as zod } from 'zod';
import { errorMap } from 'zod-validation-error';
zod.setErrorMap(errorMap);
fromZodIssue
If you need to customize some error code, you may use the fromZodIssue
function.
import { z as zod } from 'zod';
import { fromZodIssue } from 'zod-validation-error';
const customErrorMap: zod.ZodErrorMap = (issue, ctx) => {
switch (issue.code) {
case ZodIssueCode.invalid_type: {
return {
message:
'Custom error message of your preference for invalid_type errors',
};
}
default: {
const validationError = fromZodIssue({
...issue,
// fallback to the default error message
// when issue does not have a message
message: issue.message ?? ctx.defaultError,
});
return {
message: validationError.message,
};
}
}
};
zod.setErrorMap(customErrorMap);
zod-validation-error
with react-hook-form
?import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { errorMap } from 'zod-validation-error';
useForm({
resolver: zodResolver(schema, { errorMap }),
});
zod-validation-error
support CommonJSYes, 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://apply.workable.com/causaly/.
MIT
FAQs
Wrap zod validation errors in user-friendly readable messages
The npm package zod-validation-error receives a total of 1,388,137 weekly downloads. As such, zod-validation-error popularity was classified as popular.
We found that zod-validation-error demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.