README.md

zod-invertible

declare zod schemas that can be inverted to format from output to input

Limitations and notes

zod-invertible doesn't support the following schemas, and invert will throw an error if it encounters them:

• z.preprocess(...)
• ZodType.transform(...) (outside of the transform created by invertible)

However, you may work around this by marking the schema with ignoreEffect:

import { schema, ignoreEffect } from 'zod-intervible'

const innerSchema = ...
const schema = ignoreEffect(z.preprocess((value) => ..., innerSchema))
const inverse = invert(schema) // equivalent to invert(innerSchema)

The inverse of ZodType.default(...) will not have a default, which should be okay, since the input to the inverse should always be defined.

The inverse of ZodType.catch(...) will not catch. If you want to use a fallback value if errors are thrown during parsing or formatting, add your own logic in the parse and format functions you pass to invertible.

If the output types of z.union([...]) options overlap, then invert(z.union([...])).parse(output) may format with a different union option than the one that parsed the input.

If you have recursive schemas (using z.lazy()), the inverse z.lazy() schemas will re-invert the resolved schema each time they are used. I may fix this in the future with a WeakMap inverse cache.

Example

npm i zod-invertible
# OR
pnpm i zod-invertible

import z from 'zod'
import { invertible, invert, ZodInvertible } from 'zod-intertible'

const StringToNumber = invertible(
  z.string(),
  (s, ctx) => {
    const result = parseFloat(s)
    if (isNaN(result)) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: 'invalid float',
      })
    }
    return result
  },
  z.number(),
  (n) => String(n)
)

StringToNumber instanceof ZodInvertible // true

StringToNumber.parse('3.5') // 3.5

const NumberToString = invert(StringToNumber)

NumberToString.parse(3.5) // '3.5'

const obj = z.object({ foo: StringToNumber })
obj.parse({ foo: '3.5' }) // { foo: 3.5 }
// invert works deeply:
invert(obj).parse({ foo: 3.5 }) // { foo: '3.5' }

invertible(inputSchema, parse, outputSchema, format)

Creates an invertible schema that transforms from an input type to a different output type. Returns a ZodInvertible, which is a subclass of ZodPipeline.

inputSchema

The ZodType for validating the input value

parse

The function for transforming the input value into the output value. It is called with two arguments:

• value: the output of inputSchema
• ctx: the zod RefinementCtx

parse may be async.

outputSchema

The ZodType for validating the output

format

The function for converting from the output value back into the input value. It is called with two arguments:

• value: the input of outputSchema
• ctx: the zod RefinementCtx

format may be async.

invert(schema)

Deeply inverts a zod schema, inverting any ZodInvertible schemas inside it, and otherwise preserving the structure of objects, arrays, etc.

If the zod schema parses input type I into output type O, the inverted schema will parse input type O into output type I.