runtypes

class Runtype

class Runtype<T = any, X = T> implements Conformance<T, X> {}

• A runtype determines at runtime whether a value conforms to a type specification.

class ValidationError

class ValidationError extends Error {}

interface Array

interface Array<R extends Runtype.Core = Runtype.Core>
    extends Runtype<Static<R>[], Parsed<R>[]>,
        Iterable<Spread<Array<R>>> {}

• Validates a value is an array of the given element type.

  Possible failures:

  - TYPE_INCORRECT for non-arrays - CONTENT_INCORRECT with details reporting the failed elements

interface BigInt

interface BigInt extends Runtype<bigint> {}

• Validates that a value is a bigint.

  Possible failures:

  - TYPE_INCORRECT for non-bigints

interface Boolean

interface Boolean extends Runtype<boolean> {}

• Validates that a value is a boolean.

  Possible failures:

  - TYPE_INCORRECT for non-booleans

interface Brand

interface Brand<B extends string = string, R extends Runtype.Core = Runtype.Core>
    extends Runtype<Static<R> & RuntypeBrand<B>, Parsed<R> & RuntypeBrand<B>> {}

• Adds a brand to the inferred static type.

  Possible failures:

  - TYPE_INCORRECT with detail reporting the inner failure

interface Constraint

interface Constraint<
    R extends Runtype.Core = Runtype.Core,
    T extends Parsed<R> = Parsed<R>
> extends Runtype<
        [Static<R>, Parsed<R>] extends [Parsed<R>, Static<R>] ? T : Static<R>,
        T
    > {}

• Adds a constraint to a runtype, narrowing its inferred static type.

  Possible failures:

  - Failures of the inner runtype - CONSTRAINT_FAILED with thrown reporting the thrown value from the constraint function

interface Function

interface Function extends Runtype<(...args: never[]) => unknown> {}

• Validates that a value is a function.

  Possible failures:

  - TYPE_INCORRECT for non-functions

interface InstanceOf

interface InstanceOf<V = unknown> extends Runtype<V> {}

• Validates that a value is an instance of the given class.

  Possible failures:

  - TYPE_INCORRECT if instanceof was false - INSTANCEOF_FAILED if instanceof threw (per Symbol.hasInstance)

interface Intersect

interface Intersect<R extends readonly Runtype.Core[] = readonly Runtype.Core[]>
    extends Runtype<
        {
            [K in keyof R]: (_: Static<R[K]>) => unknown;
        }[number] extends (_: infer I) => unknown
            ? I
            : unknown,
        R extends [...(readonly unknown[]), infer R]
            ? R extends Runtype.Core
                ? Parsed<R>
                : never
            : unknown
    > {}

• Validates that a value fulfills all of the given runtypes.

  Possible failures:

  - TYPE_INCORRECT with details reporting failures for each runtype

interface Literal

interface Literal<T extends LiteralStatic = LiteralStatic> extends Runtype<T> {}

• Validates that a value is equal to the given value with the [SameValueZero](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#same-value-zero_equality) equality.

  Possible failures:

  - TYPE_INCORRECT if they have different typeofs - VALUE_INCORRECT if they were different as per SameValueZero

interface Never

interface Never extends Runtype<never> {}

• Validates nothing.

  Possible failures:

  - NOTHING_EXPECTED for any value

interface Number

interface Number extends Runtype<number> {}

• Validates that a value is a number.

  Possible failures:

  - TYPE_INCORRECT for non-numbers

interface Object

interface Object<O extends Object.Fields = Object.Fields>
    extends Runtype<ObjectStatic<O>, ObjectParsed<O>>,
        Utilities<O> {}

• Validates that a value is an object and each property fulfills the given property runtype.

  Possible failures:

  - TYPE_INCORRECT for null, undefined, and non-objects if fields were non-empty - CONTENT_INCORRECT with details reporting the failed properties

  For each property, contextual failures can be seen in addition to failures of the property runtype:

  - PROPERTY_MISSING for missing required properties - PROPERTY_PRESENT for extraneous properties where .exact() flag is enabled

interface Optional

interface Optional<R extends Runtype.Core = Runtype.Core, D = any> {}

• A pseudo-runtype that is only usable in the context of Object properties. This works as the runtime counterpart of optional properties.

  const O = Object({ x: Number.optional() })
  const O = Static<typeof O> // { x?: number }

interface Parser

interface Parser<R extends Runtype.Core = Runtype.Core, X = Parsed<R>>
    extends Runtype<Static<R>, X> {}

• Adds a parser to the given runtype.

  Possible failures when check-ing:

  - Failures of the inner runtype

  Possible failures when parse-ing:

  - Failures of the inner runtype - PARSING_FAILED with thrown reporting the thrown value from the parser function

interface Record

interface Record<
    K extends Runtype.Core<PropertyKey> = Runtype.Core<PropertyKey>,
    V extends Runtype.Core = Runtype.Core
> extends Runtype<RecordStatic<K, V>, RecordParsed<K, V>> {}

• Validates that a value is an object, and properties fulfill the given key and value runtypes.

  Possible failures:

  - TYPE_INCORRECT for null, undefined, non-objects, non-plain-object non-arrays, and non-plain-object arrays if the key runtype was String - CONTENT_INCORRECT with details reporting the failed properties

  For each property, contextual failures can be seen in addition to failures of the property runtype:

  - PROPERTY_MISSING for missing required properties - KEY_INCORRECT with detail reporting the failure of the key runtype

interface Spread

interface Spread<R extends Runtype.Spreadable = Runtype.Spreadable> {}

• A pseudo-runtype that is only usable in the context of Tuple arguments. This works as the runtime counterpart of variadic tuple types.

  const T = Tuple(Literal(0), Spread(Tuple(Literal(1), Literal(2))), Literal(3))
  type T = Static<typeof T> // [0, 1, 2, 3]
  
  const U = Tuple(Literal(0), Spread(Array(Literal(1))), Literal(2))
  type U = Static<typeof U> // [0, ...1[], 2]

  Spread only accepts a Tuple, an Array, and trivial runtypes around them e.g. Tuple(...).withBrand(...) and Union(Array(...)). Using the spread operator ... against those runtypes yields a Spread just once, so you can write ...Tuple(...) instead of Spread(Tuple(...)).

  const T = Tuple(Literal(0), ...Tuple(Literal(1), Literal(2)), Literal(3))
  type T = Static<typeof T> // [0, 1, 2, 3]
  
  const U = Tuple(Literal(0), ...Array(Literal(1)), Literal(2))
  type U = Static<typeof U> // [0, ...1[], 2]

interface String

interface String extends Runtype<string> {}

• Validates that a value is a string.

  Possible failures:

  - TYPE_INCORRECT for non-strings

interface Symbol

interface Symbol<K extends string | undefined = never> extends Runtype<symbol> {}

• Validates that a value is a symbol, and optionally the key is equal to the given one. If you want to ensure a symbol is *not* keyed, pass undefined.

  Possible failures:

  - TYPE_INCORRECT for non-symbols - VALUE_INCORRECT if the key is not equal to the given one

interface Template

interface Template<
    A extends readonly [string, ...string[]] = readonly [string, ...string[]],
    B extends readonly Runtype.Core<LiteralStatic>[] = readonly Runtype.Core<LiteralStatic>[]
> extends Runtype<
        A extends TemplateStringsArray ? string : TemplateStatic<A, B>,
        A extends TemplateStringsArray ? string : TemplateParsed<A, B>
    > {}

• Validates that a value is a string that conforms to the template.

  Possible failures:

  - TYPE_INCORRECT for non-strings - VALUE_INCORRECT if the string didn't match the template

  You can use the familiar syntax to create a Template runtype:

  const T = Template`foo${Literal('bar')}baz`;

  But then the type inference won't work:

  type T = Static<typeof T>; // inferred as string

  Because TS doesn't provide the exact string literal type information (["foo", "baz"] in this case) to the underlying function. See the issue [microsoft/TypeScript#33304](https://github.com/microsoft/TypeScript/issues/33304), especially this comment [microsoft/TypeScript#33304 (comment)](https://github.com/microsoft/TypeScript/issues/33304#issuecomment-697977783) we hope to be implemented.

  If you want the type inference rather than the tagged syntax, you have to manually write a function call:

  const T = Template(['foo', 'baz'] as const, Literal('bar'));
  type T = Static<typeof T>; // inferred as "foobarbaz"

  As a convenient solution for this, it also supports another style of passing arguments:

  const T = Template('foo', Literal('bar'), 'baz');
  type T = Static<typeof T>; // inferred as "foobarbaz"

  You can pass various things to the Template constructor, as long as they are assignable to string | number | bigint | boolean | null | undefined and the corresponding Runtypes:

  // Equivalent runtypes
  Template(Literal('42'));
  Template(42);
  Template(Template('42'));
  Template(4, '2');
  Template(Literal(4), '2');
  Template(String.withConstraint(s => s === '42'));
  Template(
    Intersect(
      Number.withConstraint(n => n === 42),
      String.withConstraint(s => s.length === 2),
      // `Number`s in `Template` accept alternative representations like `"0x2A"`,
      // thus we have to constraint the length of string, to accept only `"42"`
    ),
  );

  Trivial items such as bare literals, Literals, and single-element Unions and Intersects are all coerced into strings at the creation time of the runtype. Additionally, Unions of such runtypes are converted into RegExp patterns like (?:foo|bar|...), so we can assume Union of Literals is a fully supported runtype in Template.

  ### Caveats

  A Template internally constructs a RegExp to parse strings. This can lead to a problem if it contains multiple non-literal runtypes:

  const UpperCaseString = Constraint(String, s => s === s.toUpperCase(), {
    name: 'UpperCaseString',
  });
  const LowerCaseString = Constraint(String, s => s === s.toLowerCase(), {
    name: 'LowerCaseString',
  });
  Template(UpperCaseString, LowerCaseString);

  The only thing we can do for parsing such strings correctly is brute-forcing every single possible combination until it fulfills all the constraints, which must be hardly done. Actually Template treats String runtypes as the simplest RegExp pattern .* and the “greedy” strategy is always used, that is, the above runtype won't work expectedly because the entire pattern is just ^(.*)(.*)$ and the first .* always wins. You have to avoid using Constraint this way, and instead manually parse it using a single Constraint which covers the entire string.

interface Tuple

interface Tuple<
    R extends readonly (Runtype.Core | Spread)[] = readonly (Runtype.Core | Spread)[]
> extends Runtype<TupleStatic<R>, TupleParsed<R>>,
        Iterable<Spread<Tuple<R>>> {}

• Validates that a value is an array of the given element types.

  Possible failures:

  - TYPE_INCORRECT for non-arrays - CONSTRAINT_FAILED with thrown being a string reporting that the length constraint was not fulfilled - CONTENT_INCORRECT with details reporting the failed elements

interface Union

interface Union<R extends readonly Runtype.Core[] = readonly Runtype.Core[]>
    extends Runtype<
        {
            [K in keyof R]: R[K] extends Runtype.Core ? Static<R[K]> : unknown;
        }[number],
        {
            [K in keyof R]: R[K] extends Runtype.Core ? Parsed<R[K]> : unknown;
        }[number]
    > {}

• Validates that a value fulfills one of the given runtypes.

  Possible failures:

  - TYPE_INCORRECT with details reporting failures for each runtype

interface Unknown

interface Unknown extends Runtype<unknown> {}

• Validates anything.