runtypes

What is runtypes?

Runtypes is a TypeScript library that provides runtime validation and type checking for JavaScript objects. It allows developers to define types and validate data against those types at runtime, ensuring that the data conforms to the expected structure and types.

What are runtypes's main functionalities?

Basic Type Validation

Runtypes allows you to define basic types like String and Number and validate data against these types. If the data does not match the expected type, an error is thrown.

const { String, Number } = require('runtypes');

const Name = String;
const Age = Number;

Name.check('John Doe'); // Passes
Age.check(30); // Passes

// Name.check(123); // Throws an error
// Age.check('30'); // Throws an error

Object Validation

Runtypes allows you to define complex types like objects and validate data against these types. You can specify the structure of the object and the types of its properties.

const { Record, String, Number } = require('runtypes');

const Person = Record({
  name: String,
  age: Number
});

Person.check({ name: 'John Doe', age: 30 }); // Passes

// Person.check({ name: 'John Doe', age: '30' }); // Throws an error

Union Types

Runtypes supports union types, allowing you to define a type that can be one of several types. This is useful for validating data that can have multiple valid types.

const { Union, String, Number } = require('runtypes');

const StringOrNumber = Union(String, Number);

StringOrNumber.check('Hello'); // Passes
StringOrNumber.check(123); // Passes

// StringOrNumber.check(true); // Throws an error

Array Validation

Runtypes allows you to define array types and validate data against these types. You can specify the type of the elements in the array.

const { Array, String } = require('runtypes');

const StringArray = Array(String);

StringArray.check(['Hello', 'World']); // Passes

// StringArray.check(['Hello', 123]); // Throws an error

Optional Properties

Runtypes allows you to define optional properties in objects. This is useful for validating data where some properties may or may not be present.

const { Record, String, Number, Optional } = require('runtypes');

const Person = Record({
  name: String,
  age: Optional(Number)
});

Person.check({ name: 'John Doe' }); // Passes
Person.check({ name: 'John Doe', age: 30 }); // Passes

// Person.check({ name: 'John Doe', age: '30' }); // Throws an error

Other packages similar to runtypes

io-ts

io-ts is a runtime type system for IO decoding/encoding in TypeScript. It provides similar functionality to runtypes, allowing you to define types and validate data at runtime. However, io-ts has a more functional programming approach and integrates well with fp-ts.

zod

Zod is a TypeScript-first schema declaration and validation library. It provides a similar feature set to runtypes, allowing you to define schemas and validate data at runtime. Zod is known for its simplicity and ease of use.

yup

Yup is a JavaScript schema builder for value parsing and validation. It is similar to runtypes in that it allows you to define schemas and validate data. Yup is widely used in the React ecosystem, especially with form libraries like Formik.

README

Runtypes

Safely bring untyped data into the fold

Runtypes allow you to take values about which you have no assurances and check that they conform to some type A. This is done by means of composable type validators of primitives, literals, arrays, tuples, records, unions, intersections and more.

Installation

npm install --save runtypes

Example

Suppose you have objects which represent asteroids, planets, ships and crew members. In TypeScript, you might write their types like so:

type Vector = [number, number, number];

type Asteroid = {
  type: 'asteroid';
  location: Vector;
  mass: number;
};

type Planet = {
  type: 'planet';
  location: Vector;
  mass: number;
  population: number;
  habitable: boolean;
};

type Rank = 'captain' | 'first mate' | 'officer' | 'ensign';

type CrewMember = {
  name: string;
  age: number;
  rank: Rank;
  home: Planet;
};

type Ship = {
  type: 'ship';
  location: Vector;
  mass: number;
  name: string;
  crew: CrewMember[];
};

type SpaceObject = Asteroid | Planet | Ship;

If the objects which are supposed to have these shapes are loaded from some external source, perhaps a JSON file, we need to validate that the objects conform to their specifications. We do so by building corresponding Runtypes in a very straightforward manner:

import { Boolean, Number, String, Literal, Array, Tuple, Record, Union } from 'runtypes';

const Vector = Tuple(Number, Number, Number);

const Asteroid = Record({
  type: Literal('asteroid'),
  location: Vector,
  mass: Number,
});

const Planet = Record({
  type: Literal('planet'),
  location: Vector,
  mass: Number,
  population: Number,
  habitable: Boolean,
});

const Rank = Union(
  Literal('captain'),
  Literal('first mate'),
  Literal('officer'),
  Literal('ensign'),
);

const CrewMember = Record({
  name: String,
  age: Number,
  rank: Rank,
  home: Planet,
});

const Ship = Record({
  type: Literal('ship'),
  location: Vector,
  mass: Number,
  name: String,
  crew: Array(CrewMember),
});

const SpaceObject = Union(Asteroid, Planet, Ship);

(See the examples directory for an expanded version of this.)

Now if we are given a putative SpaceObject we can validate it like so:

// spaceObject: SpaceObject
const spaceObject = SpaceObject.check(obj);

If the object doesn't conform to the type specification, check will throw an exception.

Static type inference

In TypeScript, the inferred type of Asteroid in the above example is

Runtype<{
  type: 'asteroid'
  coordinates: [number, number, number]
  mass: number
}>

That is, it's a Runtype<Asteroid>, and you could annotate it as such. But we don't really have to define the Asteroid type in TypeScript at all now, because the inferred type is correct. Defining each of your types twice, once at the type level and then again at the value level, is a pain and not very DRY. Fortunately you can define a static Asteroid type which is an alias to the Runtype-derived type like so:

import { Static } from 'runtypes';

type Asteroid = Static<typeof Asteroid>;

which achieves the same result as

type Asteroid = {
  type: 'asteroid';
  coordinates: [number, number, number];
  mass: number;
};

Type guards

In addition to providing a check method, runtypes can be used as type guards:

function disembark(obj: {}) {
  if (SpaceObject.guard(obj)) {
    // obj: SpaceObject
    if (obj.type === 'ship') {
      // obj: Ship
      obj.crew = [];
    }
  }
}

Pattern matching

The Union runtype offers the ability to do type-safe, exhaustive case analysis across its variants using the match method:

const isHabitable = SpaceObject.match(
  asteroid => false,
  planet => planet.habitable,
  ship => true,
);

if (isHabitable(spaceObject)) {
  // ...
}

There's also a top-level match function which allows testing an ad-hoc sequence of runtypes:

const makeANumber = match(
  [Number, n => n * 3],
  [Boolean, b => b ? 1 : 0],
  [String, s => s.length],
);

makeANumber(9); // = 27

To allow the function to be applied to anything and then handle match failures, simply use an Always case at the end:

const makeANumber = match(
  [Number, n => n * 3],
  [Boolean, b => b ? 1 : 0],
  [String, s => s.length],
  [Always, () => 42]
);

Constraint checking

Beyond mere type checking, we can add arbitrary runtime constraints to a Runtype:

const Positive = Number.withConstraint(n => n > 0);

Positive.check(-3); // Throws error: Failed constraint check

You can provide more descriptive error messages for failed constraints by returning a string instead of false:

const Positive = Number.withConstraint(n => n > 0 || `${n} is not positive`);

Positive.check(-3); // Throws error: -3 is not positive

Function contracts

Runtypes along with constraint checking are a natural fit for enforcing function contracts. You can construct a contract from Runtypes for the parameters and return type of the function:

const divide = Contract(
  // Parameters:
  Number,
  Number.withConstraint(n => n !== 0 || 'division by zero'),
  // Return type:
  Number,
).enforce((n, m) => n / m);

divide(10, 2); // 5

divide(10, 0); // Throws error: division by zero

Related libraries

• runtypes-generate Generates random data by Runtype for property-based testing