valtiojs/valtio-zod

README

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.

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

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