DEV Community

Naxrul Ahmed
Naxrul Ahmed

Posted on

Xanv

Documentation

Xanv is a small TypeScript-first runtime validation library. Schemas validate
values at runtime while exposing their inferred TypeScript types.

Features

  • Runtime validation for primitive, collection, object, function, promise, file, and React function-component values
  • Composable optional, nullable, default, and transform behavior
  • Type inference with Infer and InferValue
  • No runtime dependencies
  • Named validator classes are exported for extension and direct use

Installation

npm install xanv
Enter fullscreen mode Exit fullscreen mode

Quick start

import { InferValue, xv } from "xanv";

const userSchema = xv.object({
  id: xv.string().min(1),
  email: xv.string().email(),
  age: xv.number().integer().min(0),
  roles: xv.array(xv.enum(["admin", "member"])),
  nickname: xv.string().optional(),
});

type User = InferValue<typeof userSchema>;

const user = userSchema.parse({
  id: "usr_123",
  email: "hello@example.com",
  age: 28,
  roles: ["member"],
});
Enter fullscreen mode Exit fullscreen mode

parse returns the parsed value. It throws an Error when validation fails.
Nested objects, arrays, tuples, records, maps, sets, and unions validate their
contents recursively.

Inference

Xanv exports two inference utilities:

import { Infer, InferValue, xv } from "xanv";

const shape = {
  name: xv.string(),
  enabled: xv.boolean().default(true),
  note: xv.string().nullable(),
};

type Input = Infer<typeof shape>;
// { name: string; note: string | null; enabled?: boolean }

type Output = InferValue<typeof shape>;
// { name: string; note: string | null; enabled: boolean }
Enter fullscreen mode Exit fullscreen mode
  • Infer treats fields with .optional() or .default() as optional. Use it for values that may be supplied to a schema.
  • InferValue only treats .optional() fields as optional. Use it for values after parsing, including fields populated by defaults.
  • .nullable() adds null to a schema's inferred value type.

Infer and InferValue accept either a schema object or an XVType validator.

Common methods

Every validator extends XVType<T> and provides:

schema.parse(value);
schema.optional();
schema.nullable();
schema.default(fallback);
schema.transform(value => newValue);
schema.clone();
schema.getDefault();
Enter fullscreen mode Exit fullscreen mode

Defaults may be a value or a zero-argument function:

const createdAt = xv.date().default(() => new Date());
const normalized = xv.string()
  .min(1)
  .transform(value => value.trim());
Enter fullscreen mode Exit fullscreen mode

Validation checks run before transforms. A transform receives and returns the
validator's parsed value type.

Validators

Factory Validates Constraint methods
xv.any<T>() Any value (default type: any) Common methods
xv.string(length?) String length, min, max, email, uppercase, lowercase, number, date, base64
xv.number(length?) Number length, min, max, positive, negative, integer, float
xv.boolean() Boolean Common methods
xv.date() Valid Date instance Common methods
xv.enum(values) A value from an array or object Common methods
xv.file() Browser File or file-like object size, minsize, maxsize, type, extension
xv.array(item) Array whose items match item min, max, unique
xv.object(shape) Object matching a validator shape Common methods
xv.record(key, value) Object with validated keys and values Common methods
xv.map(key, value) Map with validated entries Common methods
xv.set(item) Set with validated items min, max
xv.tuple(items) Fixed-length tuple Common methods
xv.union(items) Value accepted by at least one item schema Common methods
xv.function(options) Function wrapper with validated arguments and return value Common methods
xv.promise(item) Promise whose resolved value matches item Common methods
xv.functionComponent(props, async?) Function-component wrapper with validated props Common methods

Objects

const person = xv.object({
  name: xv.string().min(1),
  age: xv.number().integer().min(0),
});

const parsed = person.parse({ name: "Ada", age: 36 });
Enter fullscreen mode Exit fullscreen mode

Object parsing returns the fields declared by the schema. Every shape field is
parsed independently, so its default, nullable, optional, and nested validators
are applied.

Collections

const tags = xv.array(xv.string()).min(1).max(5).unique();
const pair = xv.tuple([xv.string(), xv.number()]);
const scores = xv.record(xv.enum(["math", "science"]), xv.number().min(0));
const lookup = xv.map(xv.string(), xv.number());
const selection = xv.set(xv.number()).min(1);
Enter fullscreen mode Exit fullscreen mode

Unions and enums

const identifier = xv.union([xv.string().min(1), xv.number().integer()]);
const role = xv.enum(["admin", "member"] as const);

enum Status {
  Active = "active",
  Disabled = "disabled",
}

const status = xv.enum(Status);
Enter fullscreen mode Exit fullscreen mode

Functions

xv.function wraps a function and validates its arguments and return value each
time the wrapper is called.

const calculate = xv.function({
  args: [xv.number(), xv.number()],
  returns: xv.number(),
});

const add = calculate.parse((left, right) => left + right)!;
add(2, 3); // 5
Enter fullscreen mode Exit fullscreen mode

For a function that returns a promise, pass async: true:

const fetchName = xv.function({
  args: [xv.number().integer()],
  returns: xv.string(),
  async: true,
});

const loadName = fetchName.parse(async id => `user-${id}`);
Enter fullscreen mode Exit fullscreen mode

If a function is marked async, Xanv checks that the original function returned a
promise and validates the resolved return value.

React function components

The second argument marks a function component as async:

import { xv } from "xanv";

const buttonSchema = xv.functionComponent({
  label: xv.string().min(1),
  count: xv.number().integer(),
});

const Button = buttonSchema.parse(props => (
  <button>
    {props.label}: {props.count}
  </button>
))!;
Enter fullscreen mode Exit fullscreen mode
const asyncButtonSchema = xv.functionComponent(
  { label: xv.string() },
  true,
);

const AsyncButton = asyncButtonSchema.parse(async props => (
  <div>{props.label}</div>
))!;
Enter fullscreen mode Exit fullscreen mode

Promises and files

const responseSchema = xv.promise(
  xv.object({
    ok: xv.boolean(),
  }),
);

const response = await responseSchema.parse(Promise.resolve({ ok: true }));

const image = xv.file()
  .maxsize(5 * 1024 * 1024)
  .type(["image/png", "image/jpeg"])
  .extension(["png", "jpg", "jpeg"]);
Enter fullscreen mode Exit fullscreen mode

xv.file() accepts File instances in browser environments and file-like
objects containing name, size, and type.

Extending Xanv

Subclass XVType<T> and implement check to create a custom validator:

import { XVType } from "xanv";

class EvenNumber extends XVType<number> {
  protected check(value: unknown): number {
    if (typeof value !== "number" || !Number.isInteger(value) || value % 2 !== 0) {
      throw new Error("Value must be an even integer");
    }
    return value;
  }
}

const even = new EvenNumber();
even.parse(4);
Enter fullscreen mode Exit fullscreen mode

Register additional constraints with the protected set helper from a subclass.
Validator classes exported by Xanv can also be instantiated directly.

Development

npm install
npx tsc --noEmit
npm run build
Enter fullscreen mode Exit fullscreen mode

The project uses makepack for build and release tasks. The package currently
does not define an automated test script.

Repository

Documentation: xanv.devnax.com

Source and issue tracking: github.com/devnax/xanv

Top comments (0)