gem-hunter

Table of contents

Purpose

Contribute

Yet another library

Installation

From npm (Node/Bun)

npm install zod_utilz
yarn add zod_utilz
pnpm add zod_utilz
bun add zod_utilz

Getting Started

import

Node/Bun

import { zu } from 'zod_utilz'

Deno

import { zu } from 'npm:zod_utilz'

Utilz

SPR

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?._errors

makeErrorMap

import { zu } from 'zod_utilz'

const errorMap = zu.makeErrorMap( {
    required: 'Custom required message',
    invalid_type: ( { data } ) => `${ data } is an invalid type`,
    too_big: ( { maximum } ) => `Maximum length is ${ maximum }`,
    invalid_enum_value: ( { data, options } ) =>
        `${ data } is not a valid enum value. Valid options: ${ options?.join( ' | ' ) } `,
} )

const stringSchema = z.string( { errorMap } ).max( 32 )

zu.SPR( stringSchema.safeParse( undefined ) ).error?.issues[ 0 ].message
// Custom required message

zu.SPR( stringSchema.safeParse( 42 ) ).error?.issues[ 0 ].message
// 42 is an invalid type

zu.SPR( stringSchema.safeParse( 'this string is over the maximum length' ) ).error?.issues[ 0 ].message
// Maximum length is 32

const enumSchema = z.enum( [ 'foo', 'bar' ], { errorMap } )

zu.SPR( enumSchema.safeParse( 'baz' ) ).error?.issues[ 0 ].message
// baz is not a valid enum value. Valid options: foo | bar

useTypedParsers

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"'

coerce

z.bigint()

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'

z.boolean()

import { zu } from 'zod_utilz'
const booleanSchema = zu.coerce( z.boolean() )

// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean
// only exception to normal boolean coercion rules
booleanSchema.parse( 'false' ) // false

// https://developer.mozilla.org/en-US/docs/Glossary/Falsy
// falsy => false
booleanSchema.parse( false ) // false
booleanSchema.parse( 0 ) // false
booleanSchema.parse( -0 ) // false
booleanSchema.parse( 0n ) // false
booleanSchema.parse( '' ) // false
booleanSchema.parse( null ) // false
booleanSchema.parse( undefined ) // false
booleanSchema.parse( NaN ) // false

// truthy => true
booleanSchema.parse( 'foo' ) // true
booleanSchema.parse( 42 ) // true
booleanSchema.parse( [] ) // true
booleanSchema.parse( {} ) // true

z.number().array()

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'

useURLSearchParams

import { zu } from 'zod_utilz'
const schema = zu.useURLSearchParams(
    z.object( {
        string: z.string(),
        number: z.number(),
        boolean: z.boolean(),
    } )
)

zu.SPR( schema.safeParse(
    new URLSearchParams( {
        string: 'foo',
        number: '42',
        boolean: 'false',
    } )
) ).data
// { string: 'foo', number: 42, boolean: false }

zu.SPR( schema.safeParse(
    new URLSearchParams( {
        string: '42',
        number: 'false',
        boolean: 'foo',
    } )
) ).error?.flatten().fieldErrors
// {
//     string: [ 'Expected string, received number' ],
//     number: [ 'Expected number, received boolean' ],
//     boolean: [ 'Expected boolean, received string' ],
// }

useFormData

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

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' ] }

json

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' ] }

stringToJSON

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( '<html>not a JSON string</html>' ) // throws

TODO