valtio-zod

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.

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

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

Basic

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.

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.

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);
//...

Configuration

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

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

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)

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);
    },
  },
);