zod-refine

zod-refine is an adapter library that lets you use Zod schemas for validating atom values in Recoil Sync effects.

Recoil Sync is an add-on library for Recoil, Meta's fairly new-ish state management library for React.

Why?

Recoil Sync provides its own type-refinement/validator library, called Refine, however Zod provides better TypeScript integration and more features, so there's that.

Installation

npm i zod-refine
yarn add zod-refine

Usage

zod-refine's sole export is a function named getRefineCheckerForZodSchema(). It takes a single Zod.Schema (a.k.a. ZodType) and returns the associated Refine Checker.

The following is an introductory example on checking a Recoil atom's value in a Recoil Sync syncEffect.

Using Refine:

import { atom } from 'recoil';
import { syncEffect, refine } from 'recoil-sync';

const testAtom = atom<number>({
  key: 'test',
  default: 0,
  key: 'test',
  effects: [
    syncEffect({
      refine: refine.number(),
    }),
  ],
});

Using zod-refine:

import { atom } from 'recoil';
import { syncEffect } from 'recoil-sync';

import { z } from 'zod';
import { getRefineCheckerForZodSchema } from 'zod-refine';

const testAtom = atom<number>({
  key: 'test',
  default: 0,
  effects: [
    syncEffect({
      refine: getRefineCheckerForZodSchema(z.number()),
    }),
  ],
});

Advanced Usage

Upgrading an atom's type

One can upgrade an atom's type using Refine's match() and asType() checkers:

const myAtom = atom<number>({
  key: 'MyAtom',
  default: 0,
  effects: [
    syncEffect({
      refine: match(
        number(),
        asType(string(), x => parseInt(x)),
        asType(object({ value: number() }), x => x.value)
      ),
    }),
  ],
});

This idiom can be adapted to Zod using z.union() / transform():

const myAtom = atom<number>({
  key: 'MyAtom',
  default: 0,
  effects: [
    syncEffect({
      refine: getRefineCheckerForZodSchema(
        z.union([
          z.number(),
          z.string().transform(x => parseInt(x)),
          z.object({ value: z.number() }).transform(x => x.value),
        ])
      ),
    }),
  ],
});

API Reference

getRefineCheckerForZodSchema()

export function getRefineCheckerForZodSchema<S extends Schema>(
  schema: S
): Checker<z.infer<S>>;

Known problems

Error handling

Refine can only handle a single error when reporting validation problems. When Zod reports multiple issues, zod-refine only passes the first one to Refine.

License

MIT