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
InferandInferValue - No runtime dependencies
- Named validator classes are exported for extension and direct use
Installation
npm install xanv
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"],
});
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 }
-
Infertreats fields with.optional()or.default()as optional. Use it for values that may be supplied to a schema. -
InferValueonly treats.optional()fields as optional. Use it for values after parsing, including fields populated by defaults. -
.nullable()addsnullto 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();
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());
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 });
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);
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);
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
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}`);
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>
))!;
const asyncButtonSchema = xv.functionComponent(
{ label: xv.string() },
true,
);
const AsyncButton = asyncButtonSchema.parse(async props => (
<div>{props.label}</div>
))!;
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"]);
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);
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
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)