valtio-zod !GitHub Actions Workflow Status !NPM Version !NPM License

Validate your valtio store values with Zod

What is this

valtio is
a proxy state library for ReactJS and VanillaJS.

Zod is a TypeScript-first
schema validation library with static type inference.

valtio-zod is an attempt to make validating your store values
with zod as easy as possible.

Installation

Zod and valtio are peer dependencies.

``bash
npm install zod valtio valtio-zod
`

Project Status

This project is in early development. We are still trying to iron out details on how best to implement this. All ideas and feedback
are welcome and strongly encouraged.

How to use it

`js
import { schema } from 'valtio-zod';

const userSchema = z.object({
name: z.string(),
age: z.number(),
});

const userState = schema(userSchema).proxy({
name: 'John Doe',
age: 30,
});

state.name = 'Jane Doe';
// state.name = 'Jane Doe'

state.name = 55; // Error
// state.name = 'Jane Doe'
`

API

$3

#### schema(zodSchema)

This function takes a ZodSchema and returns a on object that has a proxy
function that returns a tuple of 2 values.

1. The proxy that can be used to trap the values being set on the valtio store and validate them against the ZodSchema before passing them along.
2. The underlying valtio store. This object is what must be used when using useSnapshot() to access the values in the store.

`js
import { schema } from 'valtio-zod';

const userSchema = z.object({
name: z.string(),
age: z.number(),
});

const userState = schema(userSchema).proxy({
name: 'John Doe',
age: 30,
});

// state is the proxy, snap is the underlying valtio store. You must use the snap object
// when you use useSnapshot()
`

#### useSnapshot(state)

This function takes a store object created by schema.proxy() and returns the useSnapshot function from valtio attached to the underlying valtio store.

`js
import { schema, useSnapshot } from 'valtio-zod';

const userSchema = z.object({
name: z.string(),
age: z.number(),
});

const userState = schema(userSchema).proxy({
name: 'John Doe',
age: 30,
});

//... inside a react component
const snap = useSnapshot(userState);
//...
`

$3

These properties can be passed to the proxy function to configure how each schema is handled.
parseSafe and errorHandler are also available as properties on the vzGlobalConfig object
to configure the default behavior of all schemas that don't provide their own configuration.

> | property | type | description |
> | -------------- | ---------------------- | ------------------------------------------------------------------ |
> | parseSafe | boolean | Tells zod whether or not to throw an error when a value is invalid |
> | errorHandler | (error: any) => void | A function that is called when a value is invalid |

#### parseSafe example

`js
import { schema } from 'valtio-zod';

const userSchema = z.object({
name: z.string(),
});

const userState = schema(userSchema).proxy(
{
name: 'John Doe',
age: 30,
},
{
parseSafe: true,
},
);

userState.name = 'Jane Doe';
// userState.name = 'Jane Doe'

userState.name = 55; // Error
// this will call the errorHandler function without throwing an error
// userState.name = 'Jane Doe'
`

parseSafe is also available as a property on the vzGlobalConfig object

`js
import { vzGlobalConfig } from 'valtio-zod';

vzGlobalConfig.parseSafe = true;
`

#### errorHandler example

This will allow you to use your own error handling logic (or use Zod.Error)

`js
import { schema, errorHandler } from 'valtio-zod';

const userSchema = z.object({
name: z.string(),
age: z.number(),
});

const userState = schema(userSchema).proxy(
{
name: 'John Doe',
age: 30,
},
{
errorHandler: (error) => {
console.error(error);
},
},
);
``