@pcvl/schema / pvl

Variable: pvl

const pvl: object;

Defined in: pvl.ts:58

The single entry point of @pcvl/schema. Every schema factory hangs off this object; from a schema, the modifiers and checks are chained methods.

Type Declaration

array

array: <Item>(item) => ArrayInterpretedSchema<Item>;

A schema validating every element against one shared item schema, with optional .min(), .max() and .length() constraints on the array itself. Every element is checked, each failure pathed with its index.

Type Parameters

Item

Item extends Schema<unknown, unknown>

Parameters

item

Item

Returns

ArrayInterpretedSchema<Item>

Example

import { pvl } from '@pcvl/schema';

const tags = pvl.array(pvl.string()).min(1);

tags.validate(['a', 2]); // { issues: [{ path: [1], code: 'INVALID_TYPE', ... }] }

bigint

bigint: () => BigintInterpretedSchema;

A schema accepting a real JavaScript bigint, with optional .min() and .max() bounds — themselves bigints. A number is never silently accepted.

Returns

BigintInterpretedSchema

Example

import { pvl } from '@pcvl/schema';

pvl.bigint().validate(9007199254740993n); // { value: 9007199254740993n }
pvl.bigint().coerce().validate('42'); // { value: 42n }

boolean

boolean: () => BooleanInterpretedSchema;

A schema accepting a JavaScript boolean. Use pvl.literal(true) when only one of the two values will do.

Returns

BooleanInterpretedSchema

Example

import { pvl } from '@pcvl/schema';

pvl.boolean().validate(false); // { value: false }
pvl.boolean().validate('false'); // { issues: [{ code: 'INVALID_TYPE', ... }] }

compile

compile: <TSchema>(schema) => CompiledSchemaOf<TSchema>;

Marks a schema — any schema, primitive or composite, transformed or not — for ahead-of-time compilation by @pcvl/compiler. At runtime it is the identity function, so a schema that uses it still validates normally before the compiler has seen the call site.

It hands back a plain Schema: no modifier can be chained onto it, so chain every modifier before compiling — pvl.compile(x.optional()), not pvl.compile(x).optional(). It keeps an untransformed object's shape, an untransformed array's element and the .standalone() marker, and .standalone() can still be called on it, so pvl.compile(x.standalone()) and pvl.compile(x).standalone() are the same. Each Standalone Key in its shape is a plain Schema too, as its compiled validator is. It can still be a field or element of another schema.

Type Parameters

TSchema

TSchema extends Schema<unknown, unknown>

Parameters

schema

TSchema

Returns

CompiledSchemaOf<TSchema>

Example

import { pvl } from '@pcvl/schema';

const payload = pvl.compile(
  pvl.object({ id: pvl.string().standalone(), tags: pvl.array(pvl.string()) }),
);

payload.validate({ id: 'a1', tags: [] }); // works today, compiled later
payload.shape.id.validate('a1'); // a compiled validator of `id` alone, once compiled

enum

enum: <Source>(source) => EnumInterpretedSchema<Source>;

A schema accepting one of a fixed set of values, from either an as const enum object or an array of string literals.

Type Parameters

Source

Source extends EnumSource

Parameters

source

Source

Returns

EnumInterpretedSchema<Source>

Example

import { pvl } from '@pcvl/schema';

const SYSTEM_ROLE = { OWNER: 'OWNER', MEMBER: 'MEMBER' } as const;

pvl.enum(SYSTEM_ROLE).validate('OWNER'); // { value: 'OWNER' }
pvl.enum(['small', 'large']).validate('medium'); // { issues: [...] }

literal

literal: <Value>(value) => LiteralInterpretedSchema<Value>;

A schema matching exactly one constant value, compared with Object.is. Combine literals inside a union to model a tagged variant.

Type Parameters

Value

Value extends PossibleLiteralValue

Parameters

value

Value

Returns

LiteralInterpretedSchema<Value>

Example

import { pvl } from '@pcvl/schema';

pvl.literal('OWNER').validate('OWNER'); // { value: 'OWNER' }
pvl.literal(42).validate('42'); // { issues: [{ code: 'INVALID_VALUE', ... }] }

number

number: () => NumberInterpretedSchema;

A schema accepting a JavaScript number — floats and integers alike, with optional .min(), .max() and .int() constraints. NaN is rejected; Infinity is not.

Returns

NumberInterpretedSchema

Example

import { pvl } from '@pcvl/schema';

pvl.number().validate(36); // { value: 36 }
pvl.number().int().min(0).validate(-1); // { issues: [{ code: 'TOO_SMALL', ... }] }

object

object: <Shape>(shape) => ObjectInterpretedSchema<Shape>;

A schema validating each declared key against its own field schema. Unknown keys are stripped by default — chain .strict() to reject them or .passthrough() to keep them. Every field is checked, so one Result reports every failing field at once.

Type Parameters

Shape

Shape extends Readonly<Record<string, Schema<unknown, unknown>>>

Parameters

shape

Shape

Returns

ObjectInterpretedSchema<Shape>

Example

import { pvl } from '@pcvl/schema';

const user = pvl.object({ name: pvl.string(), age: pvl.number().int() });

user.validate({ name: 'Ada', age: 36, extra: true });
// { value: { name: 'Ada', age: 36 } }

string

string: () => StringInterpretedSchema;

A schema accepting a JavaScript string, with optional .min(), .max() and .length() constraints.

Returns

StringInterpretedSchema

Example

import { pvl } from '@pcvl/schema';

pvl.string().validate('hello'); // { value: 'hello' }
pvl.string().min(3).validate('hi'); // { issues: [{ code: 'TOO_SMALL', ... }] }
pvl.string().min(3, { message: 'too short' }).validate('hi'); // message: 'too short'

union

union: <Members>(members) => UnionInterpretedSchema<Members>;

A schema trying each member in the order given and succeeding on the first that accepts the value. A total failure reports one INVALID_UNION issue followed by every member's own rejection.

Type Parameters

Members

Members extends UnionMembers

Parameters

members

Members

Returns

UnionInterpretedSchema<Members>

Example

import { pvl } from '@pcvl/schema';

const id = pvl.union([pvl.string(), pvl.number().int()]);

id.validate(7); // { value: 7 }
id.validate(true); // { issues: [...] } — INVALID_UNION, then each member's rejection

Example

import { pvl } from '@pcvl/schema';

const user = pvl.object({
  name: pvl.string().min(1),
  role: pvl.enum(['OWNER', 'MEMBER']),
  nickname: pvl.string().optional(),
});

const result = user.validate({ name: 'Ada', role: 'OWNER' });