zod-structured-error

Kneel before Zod!

A small library that converts Zod errors into structured objects. Zero dependencies, zero fuss.

Installation

npm install zod-structured-error

Zod is a peer dependency. Be sure it's already installed.

npm install zod

Usage

toStructuredError

declare function toStructuredError(
  error: ZodError<any>, 
  options?: ZodStructuredErrorOptions
): ZodStructuredError

• error - A Zod error object
• options - An optional options object

| Option | Type | Default | Description | | --- | --- | --- | --- | | grouping | union ErrorGrouping | join | How to handle multiple errors for the same path | | joinDelimiter | string | '; ' | The delimiter to use when joining multiple errors. Ignored when grouping is not join | | pathDelimiter | string | '.' | The delimiter to use when joining error path segments |

ErrorGrouping

The grouping option determines how multiple errors for the same path are handled. The following values are available:

| Grouping | Description | | --- | --- | | join | Join multiple errors with a delimiter (default) | | array | Represent errors as arrays | | array-if-multiple | Represent errors as arrays, but only if there are multiple errors for the same path |

ZodStructuredError

The ZodStructuredError return type is an alias for Record<string, string | string[]>

Example

import { z } from 'zod'
import { toStructuredError } from 'zod-structured-error'

const schema = z.object({
  label: z.string(),
  tags: z.array(z.string().nonempty()),
  nested: z.object({
    id: z.number().positive().multipleOf(10),
    value: z.string(),
  }),
  attributes: z.array(z.object({
    name: z.string(),
    value: z.string(),
  })),
})

const result = schema.safeParse({
  label: null,
  tags: ['foo', '', 'baz'],
  nested: {
    id: -22,
    value: 'Hello, world!',
  },
  attributes: [
    { name: 'foo', value: 'bar' },
    { name: 'baz', value: 'qux' },
  ],
})

if (!result.success) {
  const structured = toStructuredError(result.error)
  console.log(result.error)
  console.log(structured)
}

The Zod error for this example looks like this:

[
    {
      code: 'invalid_type',
      expected: 'string',
      received: 'null',
      path: [ 'label' ],
      message: 'Expected string, received null'
    },
    {
      code: 'too_small',
      minimum: 1,
      type: 'string',
      inclusive: true,
      exact: false,
      message: 'String must contain at least 1 character(s)',
      path: [ 'tags', 1 ]
    },
    {
      code: 'too_small',
      minimum: 0,
      type: 'number',
      inclusive: false,
      exact: false,
      message: 'Number must be greater than 0',
      path: [ 'nested', 'id' ]
    },
    {
      code: 'not_multiple_of',
      multipleOf: 10,
      message: 'Number must be a multiple of 10',
      path: [ 'nested', 'id' ]
    }
  ],

But the structured error looks simplifies the error and groups errors by path:

{
  'label': 'Expected string, received null',
  'tags.1': 'String must contain at least 1 character(s)',
  'nested.id': 'Number must be greater than 0; Number must be a multiple of 10'
}

Customization

By default, multiple errors for the same path are joined with a semicolon. You can change the delimiter:

const structured = toStructuredError(result.error, {
  joinDelimiter: ' | ',
})

// Outputs
{
  'label': 'Expected string, received null',
  'tags.1': 'String must contain at least 1 character(s)',
  'nested.id': 'Number must be greater than 0 | Number must be a multiple of 10'
}

Errors can be represented arrays instead of strings:

const structured = toStructuredError(result.error, {
  grouping: 'array',
})

// Outputs
{
  'label': [ 'Expected string, received null' ],
  'tags.1': [ 'String must contain at least 1 character(s)' ],
  'nested.id': [
    'Number must be greater than 0',
    'Number must be a multiple of 10'
  ]
}

Errors can be represented arrays, but only if there are multiple errors for the same path:

const structured = toStructuredError(result.error, {
  grouping: 'array-if-multiple',
})

// Outputs
{
  'label': 'Expected string, received null',
  'tags.1': 'String must contain at least 1 character(s)',
  'nested.id': [
    'Number must be greater than 0',
    'Number must be a multiple of 10'
  ]
}

Path segments are joined with a period by default. You can change the this:

const structured = toStructuredError(result.error, {
  pathDelimiter: '/',
})

// Outputs
{
  'label': 'Expected string, received null',
  'tags/1': 'String must contain at least 1 character(s)',
  'nested/id': 'Number must be greater than 0; Number must be a multiple of 10'
}

Changelog

You can find the changelog at CHANGELOG.md.