Runtypes

Runtime validation for static types

ValidationTypes
runtypes/runtypesruntypes

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


  1. ```
  2. npm install --save runtypes
  3. ```

Example


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

  1. ```ts
  2. type Vector = [number, number, number]

  4. type Asteroid = {
  5. type: "asteroid"
  6. location: Vector
  7. mass: number
  8. }

  10. type Planet = {
  11. type: "planet"
  12. location: Vector
  13. mass: number
  14. population: number
  15. habitable: boolean
  16. }

  18. type Rank = "captain" | "first mate" | "officer" | "ensign"

  20. type CrewMember = {
  21. name: string
  22. age: number
  23. rank: Rank
  24. home: Planet
  25. }

  27. type Ship = {
  28. type: "ship"
  29. location: Vector
  30. mass: number
  31. name: string
  32. crew: CrewMember[]
  33. }

  35. type SpaceObject = Asteroid | Planet | Ship
  36. ```

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:

  1. ```ts
  2. import { Boolean, Number, String, Literal, Array, Tuple, Record, Union } from "runtypes"

  4. const Vector = Tuple(Number, Number, Number)

  6. const Asteroid = Record({
  7. type: Literal("asteroid"),
  8. location: Vector,
  9. mass: Number,
  10. })

  12. const Planet = Record({
  13. type: Literal("planet"),
  14. location: Vector,
  15. mass: Number,
  16. population: Number,
  17. habitable: Boolean,
  18. })

  20. const Rank = Union(Literal("captain"), Literal("first mate"), Literal("officer"), Literal("ensign"))

  22. const CrewMember = Record({
  23. name: String,
  24. age: Number,
  25. rank: Rank,
  26. home: Planet,
  27. })

  29. const Ship = Record({
  30. type: Literal("ship"),
  31. location: Vector,
  32. mass: Number,
  33. name: String,
  34. crew: Array(CrewMember),
  35. })

  37. const SpaceObject = Union(Asteroid, Planet, Ship)
  38. ```

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

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

  1. ```ts
  2. // spaceObject: SpaceObject
  3. const spaceObject = SpaceObject.check(obj)
  4. ```

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

Error information


When it fails to validate, your runtype emits a ValidationError object that contains detailed information that describes what's the problem. Following properties are available in the object:

- name: Always "ValidationError"
- message: A string that summarizes the problem overall
- code: A [Failcode](https://github.com/pelotom/runtypes/blob/dcd4fe0d0bd0fc9c3ec445bda30586f3e6acc71c/src/result.ts#L12-L33) that categorizes the problem
- details: An object that describes which property was invalid precisely; only for complex runtypes (e.g. Record, Array, and the like)

If you want to inform your users about the validation error, it's strongly discouraged to rely on the format of message property in your code, as it may change across minor versions for readability thoughts. Instead of parsing message, you should use code and/or details property to programmatically inspect the validation error, and handle other stuff such as i18n.