TS VChecker

Minimal validation library with TypeScript type inference

npm install ts-vchecker

Features

This library lets you build a standard type guard declaratively.

The resulting type is inferred by TypeScript automatically, and you can give it a name if you want to reuse it in your code.

The following declarations are available (see documentation below):

Type	Declaration	Notes
Values:
boolean	vBoolean()
number	vNumber()
string	vString()
null	vNull()
undefined	vUndefined()
Literal ("foo" as const)	vLiteral(...)	Treats all NaN values as equal, unlike JavaScript.
any	vAny()	Always matches.
never	vNever()	Never matches.
Structures:
object	vObject(...)	A schema must be provided. Extra properties are ignored.
array	vArray(...)	A child type can be provided.
Combinations:
Union (A | B | ...)	vUnion(...)	A value must match one of the schemas.
Intersection (A & B & ...)	vIntersection(...)	A value must match all of the schemas.
Runtime logic:
if with type guard	vRefine(...)	Takes a user-defined type guard to narrow down the type.
if without type guard	vValidate(...)	Takes a user-defined validation function returning a boolean.

Example

Declare both your type and the validation function at once:

export type MovedEvent = VCheckerType<typeof isMovedEvent>;
export const isMovedEvent = vObject({
  type: vLiteral("moved"),
  data: vUnion(
    vObject({
      parentId: vValidate(vString(), isUUID),
      index: vNumber(),
    }),
    vObject({
      parentId: vNull(),
    })
  ),
});

Use the validation function in your code like a standard type guard:

const event = req.body;

if (!isMovedEvent(event)) {
  return res.status(400).end();
}

res.status(200).send("Moving node to " + event.data.parentId);

The following types are inferred automatically by TypeScript.

// type MovedEvent = {
//   type: "moved";
//   data:
//     | {
//         parentId: string;
//         index: number;
//       }
//     | {
//         parentId: null;
//       };
// };
// const isMovedEvent: (x: unknown) => x is MovedEvent;

Documentation

Any

function vAny(): VChecker<any>

• This checker returns true for any value

Array

function vArray(checker: VChecker<T> = vAny()): VChecker<T[]>

• This checker returns true for empty arrays
• This checker returns true for arrays of correctly typed values
• This checker returns false for non-arrays
• This checker returns false for arrays of incorrectly typed values

Boolean

function vBoolean(): VChecker<boolean>

• This checker returns true for booleans
• This checker returns false for non-booleans

Intersection

function vIntersection(
  schema1: VChecker<T1>,
  schema2: VChecker<T2>,
  schema3: VChecker<T3> = vAny(),
  schema4: VChecker<T4> = vAny(),
  schema5: VChecker<T5> = vAny(),
  schema6: VChecker<T6> = vAny(),
  schema7: VChecker<T7> = vAny(),
  schema8: VChecker<T8> = vAny(),
  schema9: VChecker<T9> = vAny(),
  schema10: VChecker<T10> = vAny()
): VChecker<T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 & T9 & T10>

• This checker returns true if and only if all checks return true

Literal

function vLiteral(literal: T): VChecker<T>

• This checker returns true for the given value
• This checker returns true for NaN values (unlike === in JavaScript)
• This checker returns false for not the given value

Never

function vNever(): VChecker<never>

• This checker always returns false

Null

function vNull(): VChecker<null>

• This checker returns true for null
• This checker returns false for non-null values

Number

function vNumber(): VChecker<number>

• This checker returns true for numbers
• This checker returns false for non-numbers

Object

function vObject(
  schema: T
): VChecker<
  {
    [K in keyof T]: VCheckerType<T[K]>;
  }
>

• This checker returns true if and only if all values in schema match
• This checker returns true for an array if the array matches the schema (weird JavaScript quirk)
• This checker returns true for objects with extra properties
• This checker returns false for non-objects

Refine

function vRefine(
  checker: VChecker<T>,
  refinement: (x: T) => x is U
): VChecker<U>

• This checker returns true if and only if both checks return true

String

function vString(): VChecker<string>

• This checker returns true for strings
• This checker returns false for non-strings

Undefined

function vUndefined(): VChecker<undefined>

• This checker returns true for undefined
• This checker returns false for non-undefined values

Union

function vUnion(
  schema1: VChecker<T1>,
  schema2: VChecker<T2>,
  schema3: VChecker<T3> = vNever(),
  schema4: VChecker<T4> = vNever(),
  schema5: VChecker<T5> = vNever(),
  schema6: VChecker<T6> = vNever(),
  schema7: VChecker<T7> = vNever(),
  schema8: VChecker<T8> = vNever(),
  schema9: VChecker<T9> = vNever(),
  schema10: VChecker<T10> = vNever()
): VChecker<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8 | T9 | T10>

• This checker returns true for values of one of the given types
• This checker returns false for values not of one of the given types

Validate

function vValidate(
  checker: VChecker<T>,
  validator: (x: T) => boolean
): VChecker<T>

• This checker returns true if and only if both checks return true