npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

zodex

v0.18.2

Published

Type-safe (de)serialization for Zod

Downloads

5,361

Readme

Zodex

Type-safe (de)serialization library for zod. It both serializes and simplifies types into a JSON format, in the following ways:

  • optional, nullable and default types are inlined into any given types itself
{ "type": "string", "defaultValue": "hi" }
  • number checks are also inlined into the type itself
{ "type": "number", "min": 23, "max": 42 }

Installation

pnpm add zodex
# or
yarn add zodex
# or
npm install zodex

Usage

import { z } from "zod";
import { zerialize } from "zodex";

const someZodType = z.discriminatedUnion("id", [
  z.object({ id: z.literal("a"), count: z.number().optional() }),
  z.object({ id: z.literal("b") }),
]);
const shape = zerialize(someZodType);

Now typeof shape will be

type Shape = {
  type: "discriminatedUnion";
  discriminator: "id";
  options: [
    {
      type: "object";
      properties: {
        id: { type: "literal"; value: "a" };
        count: { type: "number"; isOptional: true };
      };
    },
    { type: "object"; properties: { id: { type: "literal"; value: "b" } } }
  ];
};

which is exactly equal to its runtime value (shown in YAML for brevity, you probably shouldn't use YAML):

type: "discriminatedUnion"
discriminator: "id"
options:
  - type: "object"
    properties:
      id:
        type: "literal"
        value: "a"
      count:
        type: "number"
        isOptional: true
  - type: "object"
    properties:
      id:
        type: "literal"
        value: "b"

Options

Both zerialize and dezerialize accept an options object with the same properties.

Since Zod does not allow the specification of the names of effects (refinements, transforms, and preprocesses), we allow you to supply as options maps of names to effects so that these can be part of serialization and deserialization. If none of these options are supplied, the effects will be omitted.

Properties:

  • superRefinements - Map of name to .superRefine() functions
  • transforms - Map of name to .transform() functions
  • preprocesses - Map of name to z.preprocess() functions

Use of JSON References

JSON references are used to represent local references. If you wish to use JSON references for remote (non-cyclic) references, you may do so, but you will need to use a library like json-refs (with resolveRefs) to first resolve such references and then supply the object to dezerialize.

Zodex will serialize local references, including handling recursive ones. As with JSON Schema, the $defs property may be a reasonable top-level property to use as storage for local references, but it receives no special treatment by this library (any property could be targeted by one's references).

Note that if you wish to use additional properties with an item containing a reference, e.g., isOptional, you will first need to wrap the JSON reference within a single-item union such as in the following:

{
  "type": "union",
  "options": [
    {
      "$ref": "#/properties/id"
    }
  ]
}

Note that due to technical limitations with Zod, we are unable to allow a JSON reference in place of an object properties object. You can either resolve this first with another library (if it is a non-cyclic reference), or target the whole object or individual properties.

Roadmap

  • custom error messages are not included

Caveats

  • brand is not supportable and omitted
  • lazy and pipeline types are unwrapped
  • catch with a function can have its then-value serialized but it cannot then be deserialized back into using the original function
  • Due to technical limitations, we cannot support the regular refine(), custom() and instanceof methods (and they will be ignored), but these are really just implementations of superRefine() which is supported