johnpyp / valita

A typesafe validation & parsing library for TypeScript

@badrap/valita

A TypeScript library for validating & parsing structured objects. The API is heavily influenced by Zod's excellent API, while the implementation side aims for the impressive performance of simple-runtypes.

We also pay special attention for providing descriptive validation error messages:

const vehicle = v.union(
  v.object({ type: v.literal("plane"), airline: v.string() }),
  v.object({ type: v.literal("train") }),
  v.object({ type: v.literal("automobile"), make: v.string() })
);
vehicle.parse({ type: "bike" });
// ValitaError: invalid_literal at .type (expected "plane", "train" or "automobile")

Installation

npm i @badrap/valita

Docs aren't my forté

A motivating example in lack of any better documentation:

import * as v from "@badrap/valita";

const Pet = v.object({
  type: v.union(v.literal("dog"), v.literal("cat")),
  name: v.string(),
});

const Person = v.object({
  name: v.string(),
  age: v.number(),
  pets: v.array(Pet).optional(),
});

Now Person.parse(value) returns value if it matches the Person schema - or throws an error otherwise.

const grizzlor = Person.parse({
  name: "Grizzlor",
  age: 101,
  pets: [
    { type: "cat", name: "Mittens" },
    { type: "cat", name: "Parsley" },
    { type: "cat", name: "Lulu" },
    { type: "cat", name: "Thomas Percival Meowther III" },
  ],
});

The real magic here comes from TypeScript's type inference. The inferred type for grizzlor is:

const grizzlor: {
  name: string;
  age: number;
  pets?: { type: "dog" | "cat"; name: string }[] | undefined;
};

You can use Infer<T> to get your mitts on the inferred type in your code:

type PersonType = v.Infer<typeof Person>;

License

This library is licensed under the MIT license. See LICENSE.