README

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

Usage no npm install needed!