https://github.com/async3619/better-zod-errors
formatted and more descriptive error messages for Zod validation
https://github.com/async3619/better-zod-errors
cli codeframe json yaml zod
Last synced: about 2 months ago
JSON representation
formatted and more descriptive error messages for Zod validation
- Host: GitHub
- URL: https://github.com/async3619/better-zod-errors
- Owner: async3619
- License: mit
- Created: 2025-09-17T11:08:07.000Z (9 months ago)
- Default Branch: dev
- Last Pushed: 2025-09-17T15:52:07.000Z (9 months ago)
- Last Synced: 2025-10-20T07:31:59.020Z (8 months ago)
- Topics: cli, codeframe, json, yaml, zod
- Language: TypeScript
- Homepage:
- Size: 231 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
💎
better-zod-errors
formatted and more descriptive error messages for Zod validation
## Introduction
This library provides set of functions to format and enhance error messages generated by [Zod](https://zod.dev/) with code frames.
| with JSON | with YAML |
|:----------------------------------:|:----------------------------------:|
|  |  |
## Installation
```bash
$ npm install better-zod-errors
# or
$ yarn add better-zod-errors
# or
$ pnpm add better-zod-errors
```
## Usage
This library provides two main functions to format Zod errors with code frames:
### JSON Format
You can format JSON data validation errors using the `formatJsonError` function:
```typescript
import { z } from "zod";
import { formatJsonError } from "better-zod-errors";
const schema = z.object({
name: z.string().min(2, "Name must be at least 2 characters long"),
age: z.number().min(0, "Age must be a positive number"),
});
const payload = {
name: "A",
age: -5,
};
try {
schema.parse(payload);
} catch (e) {
if (e instanceof z.ZodError) {
for (const issue of e.issues) {
const formattedError = formatJsonError(issue, payload);
console.log(formattedError); // formatted error message with code frame
}
} else {
// handle other errors
}
}
```
### YAML Format
You can also format YAML data validation errors using the `formatYamlError` function:
```typescript
import { z } from "zod";
import { formatYamlError } from "better-zod-errors";
const schema = z.object({
name: z.string().min(2, "Name must be at least 2 characters long"),
age: z.number().min(0, "Age must be a positive number"),
address: z.object({
street: z.string(),
city: z.string(),
}),
});
const payload = {
name: "John",
age: -5,
address: {
street: "123 Main St",
city: 456, // Invalid type
},
};
try {
schema.parse(payload);
} catch (e) {
if (e instanceof z.ZodError) {
for (const issue of e.issues) {
const formattedError = formatYamlError(issue, payload);
console.log(formattedError); // formatted YAML error message with code frame
}
} else {
// handle other errors
}
}
```
## API
### `formatJsonError(issue: z.ZodIssue, data: any, [options: FormatJsonErrorOptions]): string`
Formats a single Zod issue into a more readable error message with a code frame.
#### `issue`
Type: `z.ZodIssue`
The Zod issue to format thrown during validation with `ZodError`.
#### `data`
Type: `any`
The original data that was validated. If the data was not matched with the original structure, it may throw an error.
#### `options`
Type: `FormatJsonErrorOptions` (optional)
##### `useColor`
Type: `boolean` (default: `true`)
Whether to use ANSI colors in the output. Set to `false` to disable colors.
##### `syntaxHighlighting`
Type: `boolean` (default: `true`)
Whether to use syntax highlighting in the code frame. Set to `false` to disable syntax highlighting.
### `formatYamlError(issue: z.ZodIssue, payload: any, [options: FormatYamlErrorOptions]): string`
Formats a single Zod issue into a more readable error message with a YAML code frame.
#### `issue`
Type: `z.ZodIssue`
The Zod issue to format thrown during validation with `ZodError`.
#### `payload`
Type: `number | bigint | boolean | string | object`
The original data that was validated in YAML format. The function will serialize this data to YAML and create a source map to locate error positions.
#### `options`
Type: `FormatYamlErrorOptions` (optional)
##### `useColor`
Type: `boolean` (default: `true`)
Whether to use ANSI colors in the output. Set to `false` to disable colors.
##### `syntaxHighlighting`
Type: `boolean` (default: `true`)
Whether to use syntax highlighting in the YAML code frame. Set to `false` to disable syntax highlighting.