Xanv — Lightweight Runtime Validation with TypeScript Inference

Xanv is a minimal runtime validation library that pairs elegantly with TypeScript. It provides a fluent API for building runtime-safe schemas that retain full static typing at compile time. With generic class-based validators, you get the best of both worlds — reliable runtime checks and precise type inference.

Table of Contents

• Features
• Installation
• Quick Start
• Type Inference & TypeScript Integration
• API Reference
• Advanced Examples
• Migration Notes
• Development & Testing
• Contributing
• Changelog
• License

Features

• 🚀 Lightweight & dependency-free — zero external dependencies.
• 🔗 Fluent API — chainable constraints and transformations.
• 🧩 Generic XV classes — XVArray<T>, XVObject<S>, XVMap<K, V>, and more, for perfect type inference.
• 🧠 Type inference helper — xv.infer<T> extracts TypeScript types directly from schema definitions.

Installation

npm install xanv
# or
yarn add xanv

Quick Start

Validate and parse data with type safety:

import { xv } from 'xanv';

const schema = xv.object({
  id: xv.string().min(3),
  age: xv.number().min(0),
  tags: xv.array(xv.string()),
});

const parsed = schema.parse({ id: 'abc', age: 30, tags: ['x'] });
console.log(parsed.id);

The parse() method returns a validated value or throws on failure. Control missing or nullable values with .optional(), .nullable(), and .default().

Type Inference & TypeScript Integration

Because each factory returns a generic class instance, Xanv retains full type information across schema definitions.

import { xv } from 'xanv';

const schema = {
  id: xv.string(),
  age: xv.number(),
  tags: xv.array(xv.string()),
} as const;

type SchemaT = xv.infer<typeof schema>;
// { id: string; age: number; tags: string[] }

const obj = xv.object(schema);
type ObjT = xv.infer<typeof schema>; // same as SchemaT

const maybe: ObjT | undefined | null = obj.parse({ id: 'a', age: 1, tags: ['x'] });

How Inference Works

• Each XV class is generic, e.g. XVObject<S>, XVArray<T>, XVRecord<K, V>, XVTuple<Ts>.
• The xv.infer<typeof schema> utility traverses schema literals and extracts TypeScript equivalents.

API Reference

Each top-level factory method on the xv export returns a typed validator class.

| Method | Returns | Description | | ------------------------- | -------------------- | ---------------------------- | | xv.string(length?) | XVString<string> | String validator | | xv.number() | XVNumber<number> | Number validator | | xv.boolean() | XVBoolean<boolean> | Boolean validator | | xv.date() | XVDate<Date> | Date validator | | xv.array(type, length?) | XVArray<T> | Array of a specific type | | xv.tuple(types) | XVTuple<T> | Tuple with precise types | | xv.union(types) | XVUnion<T> | Union of multiple validators | | xv.object(schema?) | XVObject<S> | Object validator | | xv.map(key, value) | XVMap<K, V> | Map validator | | xv.set(type) | XVSet<T> | Set validator | | xv.record(key, value) | XVRecord<K, V> | Record validator | | xv.enum(values) | XVEnum<T> | Enum validator |

Common Instance Methods

• parse(value: any): T | undefined | null
• optional(): this
• nullable(): this
• default(value: T | (() => T)): this
• transform(cb: (value: T) => T): this

Additional constraint methods are available in src/types (e.g., .min, .max, .email, .unique, .float, .integer, etc.).

Advanced Examples

Tuple with Exact Types

const tpl = xv.tuple([xv.string(), xv.number()]);
type Tpl = xv.infer<typeof ({ a: tpl })['a']>;
// [string, number]

Nested Objects and Arrays

const user = xv.object({ name: xv.string(), id: xv.number() });
const schema = xv.object({ users: xv.array(user) });

type SchemaT = xv.infer<typeof schema['arg']>;
// { users: { name: string; id: number }[] }

Validation with Transform and Default

const s = xv.string().transform(v => v.trim()).default('n/a');
const parsed = s.parse(undefined); // "n/a"

Migration Notes

If you’re upgrading from a pre-generic version of Xanv:

• Factories now return generic class types — remove legacy wrappers.
• Use as const on schema literals for optimal xv.infer inference.

Development & Testing

Run TypeScript checks and tests:

npx tsc --noEmit
npm test

Adding New Types

1. Create a new generic class under src/types.
2. Add its factory signature in src/index.ts.
3. Write unit tests and update documentation examples.

Contributing

• Open issues before large changes.
• Keep PRs focused and include relevant tests.
• Update public type definitions and README when altering APIs.

Changelog

Refer to CHANGELOG.md for updates. Include short migration notes for any breaking changes.

License

MIT © 2025