Reviewed

Ergonomic, extensible and lightweight validators.

Motivation

I want to validate unknowns and for the compiler to know the parsed type:

import { isNumber } from "reviewed";

const parse = (input: unknown) => {
  const { valid, parsed } = isNumber(input);

  if (valid) {
    // Parsed type: number
    console.log(parsed);
  }
};
Copy

I want to validate an object and get failure messages for each field:

import { errors, isNaturalNumberString } from "reviewed";

const paginate = (url: URL): void => {
  const isPagination = validateWith({
    page: isNaturalNumberString,
    size: isNaturalNumberString,
  });

  const { valid, parsed, error } = isPagination({
    page: url.searchParams.get("page"),
    size: url.searchParams.get("size"),
  });

  if (valid) {
    console.log(parsed);
  } else {
    console.error(error);
  }
};
Copy

paginate(new URL("https://example.com?page=1&size=10")) >>
  {
    page: 1,
    size: 10,
  };
Copy

paginate(new URL("https://example.com?page=-1")) >>
  {
    page: 'Not a natural number string: "-1"',
    size: "Not a string: null",
  };
Copy

I want a record with the input and failure messages, not some ridiculous opaque object with error methods!

isRecordOf({ a: isNumber, b: isString })({ a: 1, b: 2 }) >>
  {
    valid: false,
    input: { a: 1, b: 2 },
    parsed: null,
    error: { b: "Not a string: 2" },
  };
Copy

Installing

npm install reviewed
Copy

Documentation

Documentation and more detailed examples are hosted on Github Pages.

Design

A validation library for TypeScript needs to be:

• Ergonomic
  • Validated types can be inferred by the compiler
  • Validators can parse the inputs
  • Errors are easy to collect
• Extensible
  • It is quick to write validators
  • It is simple to test validators
  • Common validators are available
• Lightweight
  • Dependency free
  • Tiny bundle size (~ 10Kb)
  • Fully tree shakeable

reviewed exposes a flexible interface that achieves these goals.

isIntegerString("1") >>
  {
    valid: true,
    input: "1",
    parsed: 1,
    error: null,
  };
Copy

isIntegerString("0.5") >>
  {
    valid: false,
    input: "0.5",
    parsed: null,
    error: "Not an integer 0.5",
  };
Copy

Alternatives

Webpack warns when a bundle exceeds 250kb, validation is not an optional feature of an application. If the minified size of a package compromises this budget it simply won't be used.

Package	Version	Minified (kB)
joi	17.12.0	145.5
ajv	8.12.0	119.6
validator	13.11.0	114.2
zod	3.22.4	57.0
yup	1.3.3	40.8
superstruct	1.0.3	11.5

Superstruct has good TypeScript support and serves as an inspiration for this package. However, the validation style for this package is designed to be much simpler and more flexible than superstruct with less need for factory functions and simpler failure message customisation.

Usage

Writing validators

numbers.ts

import { Validator, isInteger, validateIf } from "reviewed";

export const isNaturalNumber: Validator<number> = (input: unknown) => {
  const integer = isInteger(input);

  if (!integer.valid) {
    return integer;
  }

  return validateIf(integer.parsed > 0, input, input, "Not a natural number");
};
Copy

Testing validators

numbers.spec.ts

import { isNaturalNumber } from "./numbers";
import { suite } from "reviewed";

suite(isNaturalNumber, [{ input: 1, parsed: 1 }], {
  "Not a number": [undefined, null, true, "", "a", [], {}, NaN, Infinity],
  "Not an integer": [0.5],
  "Not a natural number": [-1, 0],
});
Copy

Combining validators

Validators can be chained to validate a payload:

[{ "name": "a" }, { "name": "b" }]
Copy

export const isArrayOfNames = isArrayOf(isRecordOf({ name: isString }));
Copy

Guards

Guards can inform the compiler that the input satisfies a type predicate. This is thanks to TypeScript's is operator:

(input: unknown): input is string => {};
Copy

Validators make assertions about the parsed type:

import { isNumber } from "reviewed";

const { valid, parsed } = isNumber(x);

if (valid) {
  // Parsed type: number
  console.log(parsed + 1);
}
Copy

We can convert this to a guard and apply the assertion to the input instead:

import { guard, isNumber } from "reviewed";

if (guard(isNumber)(input)) {
  // Parsed type: number
  console.log(input + 1);
}
Copy

Using literals

Array literals can be converted directly to validators:

const builds = ["dev", "prod"] as const;
const isBuild = isOneOf(builds);

isBuild("dev") >>
  {
    valid: true,
    parsed: [3, 1],
  };

isBuild("local") >>
  {
    valid: false,
    error: 'Not one of ["dev", "prod"]: "local"',
  };
Copy

Overview

Validators take an unknown input and return a record that implements the Valid or Invalid interfaces:

interface Valid<T> {
  valid: true;
  input: unknown;
  parsed: T;
  error: null;
}

interface Invalid<T> {
  valid: false;
  input: unknown;
  parsed: null;
  error: ValidationErrors<T>;
}

type Validated<T> = Valid<T> | Invalid<T>;

type Validator<T> = (input: unknown) => Validated<T>;
Copy

Inputs can be validated directly:

const validate: <T>(input: unknown, parsed: unknown = input) => Validated<T>;
const invalidate: <T>(input: unknown, error: ValidationErrors<T>) => Validated<T>;

const validateWith: <T>(validators: ValidatorFields<T>) => Validator<T>;
const invalidateWith: <T>(reason: string) => Validator<T>;
Copy

Helper factories are provided:

const validateIf: <T>(condition: boolean, input: unknown, parsed: unknown, reason: string) => Validated<T[]>;
const validateRegex: <T extends string>(regex: RegExp, reason: string) => RegexValidator<T>;

const validateAll: <T>(validator: Validator<T>) => Validator<T[]>;
const validateEach: <T>(validator: Validator<T>) => Validator<T>[];

const validateOr: <T>(validator: Validator<T>, fallback: T) => (input: unknown) => T;
const validateEachOr: <T>(validator: Validator<T>, fallback: T) => (input: unknown) => T[];
Copy

Validators can be used to filter inputs:

const filterValid: <T>(validator: Validator<T>) => (input: unknown) => T[];
Copy

Validators can be inverted or joined:

const not: <T>(validator: Validator<T>, reason?: string) => Validator<T>;

const both: <T, U>(first: Validator<T>, second: Validator<U>) => Validator<T & U>;
const either: <T, U>(first: Validator<T>, second: Validator<U>) => Validator<T | U>;

const isArrayOf: <T>(validator: Validator<T>) => Validator<T[]>;
const isRecordOf: <T>(validators: ValidatorFields<T>) => Validator<T>;
Copy

Results can be merged:

const all: <T>(results: Validated<T>[]) => Validated<T[]>;
const any: <T>(results: Validated<T>[]) => Validated<T[]>;

const merge: <T>(results: ValidatedFields<T>) => Validated<T>;
const sieve: <T>(results: ValidatedFields<T>) => Partial<T>;
Copy

Validation errors can be converted to native errors:

const fail: <T>(errors: ValidationErrors<T>) => Error;
Copy

Common validators are provided out of the box:

const isUndefined: Validator<undefined>;
const isNull: Validator<null>;
const isBoolean: Validator<boolean>;
const isNumber: Validator<number>;
const isString: Validator<string>;
const isObject: Validator<object>;

const isInteger: Validator<number>;
const isNaturalNumber: Validator<number>;

const isBooleanString: Validator<boolean>;
const isNumberString: Validator<number>;
const isIntegerString: Validator<number>;
const isNaturalNumberString: Validator<number>;

const isArray: Validator<unknown[]>;
const isNonEmptyArray: Validator<unknown[]>;
const isNumberArray: Validator<number[]>;
const isStringArray: Validator<string[]>;

const isRecord: Validator<Record<string, unknown>>;
const isNonEmptyRecord: Validator<Record<string, unknown>>;

const isEmail: RegexValidator<"user" | "domain">;

const isOneOf: <T>(options: T[]) => Validator<T>;
const isManyOf: <T>(options: T[]) => Validator<T[]>;
Copy

Reasonable types

JavaScript has some famously confusing types:

typeof NaN >> "number";
Copy

Care is taken to make primitive types easier to work with.

Numbers

const isNumber: Validator<number> = (input: unknown) =>
  validateIf(typeof input === "number" && isFinite(input), input, input, "Not a number");
Copy

Input	Parsed	Error
1	1	null
NaN	null	Not an number
Infinity	null	Not an number
""	null	Not an number

Objects

const isObject: Validator<object> = (input: unknown) =>
  validateIf(typeof input === "object" && input !== null, input, input, "Not an object");
Copy

Input	Parsed	Error
[]	[]	null
{}	{}	null
""	null	Not an object

Records

const isRecord: Validator<Record<string, unknown>> = (input: unknown) =>
  validateIf(isObject(input).valid && !isArray(input).valid, input, input, "Not a record");
Copy

Input	Parsed	Error
[]	null	Not a record
{}	{}	null
""	null	Not an object

Secret magic

Hey let's write an isArrayOf and isRecordOf function:

const isArrayOf: <T>(validator: Validator<T>) => Validator<T[]>;
const isRecordOf: <T>(validators: ValidatorFields<T>) => Validator<T>;
Copy

But wait we already have:

const validateAll: <T>(validator: Validator<T>) => Validator<T[]>;
const validateWith: <T>(validators: ValidatorFields<T>) => Validator<T>;
Copy

That's because they're the same thing woah...

So we can just alias them:

export const isArrayOf = validateAll;
export const isRecordOf = validateWith;
Copy

Tooling

Dependencies

To install dependencies:

yarn install
Copy

Tests

To run tests:

npm run test
Copy

Documentation

To generate the documentation locally:

npm run docs
Copy

Linters

To run linters:

npm run lint
Copy

Formatters

To run formatters:

npm run format
Copy

Contributing

Please read this repository's Code of Conduct which outlines our collaboration standards and the Changelog for details on breaking changes that have been made.

This repository adheres to semantic versioning standards. For more information on semantic versioning visit SemVer.

Bump2version is used to version and tag changes. For example:

bump2version patch
Copy

Contributors

• Joel Lefkowitz - Initial work

Remarks

Lots of love to the open source community!