Framework agnostic utilities for Zod
Always open to ideas. Positive or negative, all are welcome. Feel free to contribute an issue or PR.
You might not want to install yet another library only to get access to that one Util you need. No worries. Feel free to copy and paste the code you need into your project. It won't get updated when this library gets updated, but it will reduce your bundle size. :D
Perhaps in the future there will be a way to install only the Utilz you need. If you know how to do this, please let me know.
npm install zod_utilz
yarn add zod_utilz
pnpm add zod_utilz
bun add zod_utilzimport { zu } from 'zod_utilz'import { zu } from 'npm:zod_utilz'SPR stands for SafeParseResult
This enables optional chaining or nullish coalescing for z.SafeParseReturnType.
import { zu } from 'zod_utilz'
const schema = z.object( { foo: z.string() } )
const result = zu.SPR( schema.safeParse( { foo: 42 } ) )
const fooDataOrErrors = result.data?.foo ?? result.error?.format().foo?._errorsSimplifies the process of making a ZodErrorMap
…Enables compile time type checking for zod parsers.
import { zu } from 'zod_utilz'
const schemaWithTypedParsers = zu.useTypedParsers( z.literal( 'foo' ) )
schemaWithTypedParsers.parse( 'foo' )
// no ts errors
schemaWithTypedParsers.parse( 'bar' )
// ^^^^^
// Argument of type '"bar"' is not assignable to parameter of type '"foo"'Coercion that treats errors like normal zod errors. Prevents throwing errors when using safeParse.
import { zu } from 'zod_utilz'
const bigintSchema = zu.coerce( z.bigint() )
bigintSchema.parse( '42' ) // 42n
bigintSchema.parse( '42n' ) // 42n
zu.SPR( bigintSchema.safeParse( 'foo' ) ).error?.issues[ 0 ].message
// 'Expected bigint, received string'…import { zu } from 'zod_utilz'
const numberArraySchema = zu.coerce( z.number().array() )
// if the value is not an array, it is coerced to an array with one coerced item
numberArraySchema.parse( 42 ) // [ 42 ]
numberArraySchema.parse( '42' ) // [ 42 ]
// if the value is an array, it coerces each item in the array
numberArraySchema.parse( [] ) // []
numberArraySchema.parse( [ '42', 42 ] ) // [ 42, 42 ]
zu.SPR( numberArraySchema.safeParse( 'foo' ) ).error?.issues[ 0 ].message
// 'Expected number, received nan'A way to parse URLSearchParams
…A way to parse FormData
import { zu } from 'zod_utilz'
const schema = zu.useFormData(
z.object( {
string: z.string(),
number: z.number(),
boolean: z.boolean(),
file: z.instanceof( File ),
} )
)const formData = new FormData()
formData.append( 'string', 'foo' )
formData.append( 'number', '42' )
formData.append( 'boolean', 'false' )
formData.append( 'file', new File( [], 'filename.ext' ) )
zu.SPR( schema.safeParse( formData ) ).data,
// { string: 'foo', number: 42, boolean: false, file: File }const formData = new FormData()
formData.append( 'string', '42' )
formData.append( 'number', 'false' )
formData.append( 'boolean', 'foo' )
formData.append( 'file', 'filename.ext' )
zu.SPR( schema.safeParse( formData ) ).error?.flatten().fieldErrors,
// {
// string: [ 'Expected string, received number' ],
// number: [ 'Expected number, received boolean' ],
// boolean: [ 'Expected boolean, received string' ],
// file: [ 'Input not instance of File' ],
// }partialSafeParse allows you to get the valid fields even if there was an error in another field
import { zu } from 'zod_utilz'
const userSchema = z.object( { name: z.string(), age: z.number() } )
const result = zu.partialSafeParse( userSchema, { name: null, age: 42 } )
// {
// successType: 'partial',
// validData: { age: 42 },
// invalidData: { name: null },
// }
result.error?.flatten().fieldErrors
// { name: [ 'Expected string, received null' ] }zu.json() is a schema that validates that a JavaScript object is JSON-compatible. This includes string, number, boolean, and null, plus Arrays and Objects containing JSON-compatible types as values
import { zu } from 'zod_utilz'
const schema = zu.json()
schema.parse( false ) // false
schema.parse( 8675309 ) // 8675309
schema.parse( { a: 'deeply', nested: [ 'JSON', 'object' ] } )
// { a: 'deeply', nested: [ 'JSON', 'object' ] }zu.stringToJSON() is a schema that validates JSON encoded as a string, then returns the parsed value
import { zu } from 'zod_utilz'
const schema = zu.stringToJSON()
schema.parse( 'true' ) // true
schema.parse( 'null' ) // null
schema.parse( '["one", "two", "three"]' ) // ['one', 'two', 'three']
schema.parse( 'not a JSON string' ) // throwsAlways open to ideas. Positive or negative, all are welcome. Feel free to contribute an issue or PR.
lib/mapValuesNo open issues yet, or sync has not completed.