Wondering what’s next for npm?Check out our public roadmap! »

    TypeScript icon, indicating that this package has built-in type declarations

    0.0.2 • Public • Published

    build status dependency status npm downloads Minified Size

    The idea

    Blog post: "Typescript and validations at runtime boundaries" by @lorefnon

    A value of type Type<A, O, I> (called "codec") is the runtime representation of the static type A.

    Also a codec can

    • decode inputs of type I (through decode)
    • encode outputs of type O (through encode)
    • be used as a custom type guard (through is)
    class Type<A, O, I> {
      readonly _A: A
      readonly _O: O
      readonly _I: I
        /** a unique name for this codec */
        readonly name: string,
        /** a custom type guard */
        readonly is: (u: unknown) => u is A,
        /** succeeds if a value of type I can be decoded to a value of type A */
        readonly validate: (input: I, context: Context) => Either<Errors, A>,
        /** converts a value of type A to a value of type O */
        readonly encode: (a: A) => O
      ) {}
      /** a version of `validate` with a default context */
      decode(i: I): Either<Errors, A>

    Note. The Either type is defined in fp-ts, a library containing implementations of common algebraic types in TypeScript.


    A codec representing string can be defined as

    import * as t from 'io-ts'
    const isString = (u: unknown): u is string => typeof u === 'string'
    const string = new t.Type<string, string, unknown>(
      (u, c) => (isString(u) ? t.success(u) : t.failure(u, c)),

    A codec can be used to validate an object in memory (for example an API payload)

    const Person = t.type({
      name: t.string,
      age: t.number
    // validation succeeded
    Person.decode(JSON.parse('{"name":"Giulio","age":43}')) // => Right({name: "Giulio", age: 43})
    // validation failed
    Person.decode(JSON.parse('{"name":"Giulio"}')) // => Left([...])

    TypeScript compatibility

    The stable version is tested against TypeScript 3.2.4.

    io-ts version required TypeScript version
    1.6.x 3.2.2+
    1.5.3 3.0.1+
    1.5.2- 2.7.2+

    Note. If you are running < typescript@3.0.1 you have to polyfill unknown.

    You can use unknown-ts as a polyfill.

    Error reporters

    A reporter implements the following interface

    interface Reporter<A> {
      report: (validation: Validation<any>) => A

    This package exports a default PathReporter reporter


    import { PathReporter } from 'io-ts/lib/PathReporter'
    const result = Person.decode({ name: 'Giulio' })
    // => ['Invalid value undefined supplied to : { name: string, age: number }/age: number']

    You can define your own reporter. Errors has the following type

    interface ContextEntry {
      readonly key: string
      readonly type: Decoder<any, any>
    interface Context extends ReadonlyArray<ContextEntry> {}
    interface ValidationError {
      readonly value: unknown
      readonly context: Context
    interface Errors extends Array<ValidationError> {}


    import * as t from 'io-ts'
    const getPaths = <A>(v: t.Validation<A>): Array<string> => {
      return v.fold(errors => errors.map(error => error.context.map(({ key }) => key).join('.')), () => ['no errors'])
    const Person = t.type({
      name: t.string,
      age: t.number
    console.log(getPaths(Person.decode({}))) // => [ '.name', '.age' ]

    Custom error messages

    You can set your own error message by providing a message argument to failure


    const NumberFromString = new t.Type<number, string, unknown>(
      (u, c) =>
        t.string.validate(u, c).chain(s => {
          const n = +s
          return isNaN(n) ? t.failure(u, c, 'cannot parse to a number') : t.success(n)
    // => ['cannot parse to a number']


    • io-ts-types - A collection of codecs and combinators for use with io-ts
    • io-ts-reporters - Error reporters for io-ts
    • geojson-iots - codecs for GeoJSON as defined in rfc7946 made with io-ts
    • graphql-to-io-ts - Generate typescript and cooresponding io-ts types from a graphql schema

    TypeScript integration

    codecs can be inspected


    This library uses TypeScript extensively. Its API is defined in a way which automatically infers types for produced values


    Note that the type annotation isn't needed, TypeScript infers the type automatically based on a schema.

    Static types can be extracted from codecs using the TypeOf operator

    type Person = t.TypeOf<typeof Person>
    // same as
    type Person = {
      name: string
      age: number

    Implemented types / combinators

    import * as t from 'io-ts'
    Type TypeScript codec / combinator
    null null t.null or t.nullType
    undefined undefined t.undefined
    void void t.void or t.voidType
    string string t.string
    number number t.number
    boolean boolean t.boolean
    unknown unknown t.unknown
    never never t.never
    object object t.object
    array of unknown Array<unknown> t.UnknownArray
    array of type Array<A> t.array(A)
    record of unknown Record<string, unknown> t.UnknownRecord
    record of type Record<K, A> t.record(K, A)
    function Function t.Function
    literal 's' t.literal('s')
    partial Partial<{ name: string }> t.partial({ name: t.string })
    readonly Readonly<A> t.readonly(A)
    readonly array ReadonlyArray<A> t.readonlyArray(A)
    type alias type T = { name: A } t.type({ name: A })
    tuple [ A, B ] t.tuple([ A, B ])
    union A \| B t.union([ A, B ]) or t.taggedUnion(tag, [ A, B ])
    intersection A & B t.intersection([ A, B ])
    keyof keyof M t.keyof(M)
    integer t.Integer
    recursive types t.recursion(name, definition)
    refinement t.refinement(A, predicate)
    exact types t.exact(type)

    Recursive types

    Recursive types can't be inferred by TypeScript so you must provide the static type as a hint

    interface Category {
      name: string
      categories: Array<Category>
    const Category: t.RecursiveType<t.Type<Category>> = t.recursion('Category', () =>
        name: t.string,
        categories: t.array(Category)

    Mutually recursive types

    interface Foo {
      type: 'Foo'
      b: Bar | undefined
    interface Bar {
      type: 'Bar'
      a: Foo | undefined
    const Foo: t.RecursiveType<t.Type<Foo>> = t.recursion('Foo', () =>
        type: t.literal('Foo'),
        b: t.union([Bar, t.undefined])
    const Bar: t.RecursiveType<t.Type<Bar>> = t.recursion('Bar', () =>
        type: t.literal('Bar'),
        a: t.union([Foo, t.undefined])
    const FooBar = t.taggedUnion('type', [Foo, Bar])

    Tagged unions

    If you are encoding tagged unions, instead of the general purpose union combinator, you may want to use the taggedUnion combinator in order to get better performances

    const A = t.type({
      tag: t.literal('A'),
      foo: t.string
    const B = t.type({
      tag: t.literal('B'),
      bar: t.number
    // the actual presence of the tag is statically checked
    const U = t.taggedUnion('tag', [A, B])


    You can refine a type (any type) using the refinement combinator

    const Positive = t.refinement(t.number, n => n >= 0, 'Positive')
    const Adult = t.refinement(Person, person => person.age >= 18, 'Adult')

    Exact types

    You can make a codec alias exact (which means that only the given properties are allowed) using the exact combinator

    const Person = t.type({
      name: t.string,
      age: t.number
    const ExactPerson = t.exact(Person)
    Person.decode({ name: 'Giulio', age: 43, surname: 'Canti' }) // ok
    ExactPerson.decode({ name: 'Giulio', age: 43, surname: 'Canti' }) // fails

    Mixing required and optional props

    You can mix required and optional props using an intersection

    const A = t.type({
      foo: t.string
    const B = t.partial({
      bar: t.number
    const C = t.intersection([A, B])
    type C = t.TypeOf<typeof C>
    // same as
    type C = {
      foo: string
    } & {
      bar?: number | undefined

    You can apply partial to an already defined codec via its props field

    const Person = t.type({
      name: t.string,
      age: t.number
    const PartialPerson = t.partial(Person.props)
    type PartialPerson = t.TypeOf<typeof PartialPerson>
    // same as
    type PartialPerson = {
      name?: string
      age?: number

    Custom types

    You can define your own types. Let's see an example

    import * as t from 'io-ts'
    // represents a Date from an ISO string
    const DateFromString = new t.Type<Date, string, unknown>(
      (u): u is Date => u instanceof Date,
      (u, c) =>
        t.string.validate(u, c).chain(s => {
          const d = new Date(s)
          return isNaN(d.getTime()) ? t.failure(u, c) : t.success(d)
      a => a.toISOString()
    const s = new Date(1973, 10, 30).toISOString()
    // right(new Date('1973-11-29T23:00:00.000Z'))
    // left(errors...)

    Note that you can deserialize while validating.

    Generic Types

    Polymorphic codecs are represented using functions. For example, the following typescript:

    interface ResponseBody<T> {
      result: T
      _links: Links
    interface Links {
      previous: string
      next: string

    Would be:

    import * as t from 'io-ts'
    // t.Mixed = t.Type<any, any, unknown>
    const ResponseBody = <RT extends t.Mixed>(type: RT) =>
        result: type,
        _links: Links
    const Links = t.interface({
      previous: t.string,
      next: t.string

    And used like:

    const UserModel = t.type({
      name: t.string
    functionThatRequiresRuntimeType(ResponseBody(t.array(UserModel)), ...params)


    You can pipe two codecs if their type parameters do align

    const NumberDecoder = new t.Type<number, string, string>(
      (s, c) => {
        const n = parseFloat(s)
        return isNaN(n) ? t.failure(s, c) : t.success(n)
    const NumberFromString = t.string.pipe(

    Tips and Tricks

    Is there a way to turn the checks off in production code?

    No, however you can define your own logic for that (if you really trust the input)

    import * as t from 'io-ts'
    import { Either, right } from 'fp-ts/lib/Either'
    const { NODE_ENV } = process.env
    export function unsafeDecode<A, O, I>(value: I, type: t.Type<A, O, I>): Either<t.Errors, A> {
      if (NODE_ENV !== 'production' || type.encode !== t.identity) {
        return type.decode(value)
      } else {
        // unsafe cast
        return right(value as any)
    // or...
    import { failure } from 'io-ts/lib/PathReporter'
    export function unsafeGet<A, O, I>(value: I, type: t.Type<A, O, I>): A {
      if (NODE_ENV !== 'production' || type.encode !== t.identity) {
        return type.decode(value).getOrElseL(errors => {
          throw new Error(failure(errors).join('\n'))
      } else {
        // unsafe cast
        return value as any

    Union of string literals

    Use keyof instead of union when defining a union of string literals

    const Bad = t.union([
      // etc...
    const Good = t.keyof({
      foo: null,
      bar: null,
      baz: null
      // etc...


    • unique check for free
    • better performance, O(log(n)) vs O(n)


    npm i @rjhilgefort/io-ts

    DownloadsWeekly Downloads






    Unpacked Size

    103 kB

    Total Files


    Last publish


    • avatar