Codec overview

This module is experimental

Experimental features are published in order to get early feedback from the community, see these tracking issues for further discussions and enhancements.

A feature tagged as Experimental is in a high state of flux, you’re at risk of it changing without notice.

Added in v2.2.3

---

Table of contents

• Invariant
  • imap
• combinators
  • array
  • compose
  • fromArray
  • fromPartial
  • fromRecord
  • fromStruct
  • fromSum
  • fromTuple
  • intersect
  • lazy
  • mapLeftWithInput
  • nullable
  • partial
  • readonly
  • record
  • refine
  • struct
  • sum
  • tuple
  • fromType
  • type
• constructors
  • fromDecoder
  • literal
  • make
• instances
  • Invariant
  • URI
  • URI (type alias)
• model
  • Codec (interface)
• primitives
  • UnknownArray
  • UnknownRecord
  • boolean
  • number
  • string
• utils
  • InputOf (type alias)
  • OutputOf (type alias)
  • TypeOf (type alias)

---

Invariant

imap

Signature

export declare const imap: <I, O, A, B>(f: (a: A) => B, g: (b: B) => A) => (fa: Codec<I, O, A>) => Codec<I, O, B>

Added in v2.2.3

combinators

array

Signature

export declare function array<O, A>(item: Codec<unknown, O, A>): Codec<unknown, Array<O>, Array<A>>

Added in v2.2.3

compose

Signature

export declare const compose: <L, A extends L, P extends A, B>(
  to: Codec<L, P, B>
) => <I, O>(from: Codec<I, O, A>) => Codec<I, O, B>

Added in v2.2.8

fromArray

Signature

export declare function fromArray<I, O, A>(item: Codec<I, O, A>): Codec<Array<I>, Array<O>, Array<A>>

Added in v2.2.3

fromPartial

Signature

export declare function fromPartial<P extends Record<string, Codec<any, any, any>>>(
  properties: P
): Codec<
  Partial<{ [K in keyof P]: InputOf<P[K]> }>,
  Partial<{ [K in keyof P]: OutputOf<P[K]> }>,
  Partial<{ [K in keyof P]: TypeOf<P[K]> }>
>

Added in v2.2.8

fromRecord

Signature

export declare function fromRecord<I, O, A>(
  codomain: Codec<I, O, A>
): Codec<Record<string, I>, Record<string, O>, Record<string, A>>

Added in v2.2.3

fromStruct

Signature

export declare function fromStruct<P extends Record<string, Codec<any, any, any>>>(
  properties: P
): Codec<{ [K in keyof P]: InputOf<P[K]> }, { [K in keyof P]: OutputOf<P[K]> }, { [K in keyof P]: TypeOf<P[K]> }>

Added in v2.2.15

fromSum

Signature

export declare const fromSum: <T extends string>(
  tag: T
) => <MS extends Record<string, Codec<any, any, any>>>(
  members: MS
) => Codec<InputOf<'Either', MS[keyof MS]>, E.OutputOf<MS[keyof MS]>, E.TypeOf<MS[keyof MS]>>

Added in v2.2.8

fromTuple

Signature

export declare const fromTuple: <C extends readonly Codec<any, any, any>[]>(
  ...components: C
) => Codec<
  { [K in keyof C]: InputOf<'Either', C[K]> },
  { [K in keyof C]: E.OutputOf<C[K]> },
  { [K in keyof C]: E.TypeOf<C[K]> }
>

Added in v2.2.8

intersect

Signature

export declare const intersect: <IB, OB, B>(
  right: Codec<IB, OB, B>
) => <IA, OA, A>(left: Codec<IA, OA, A>) => Codec<IA & IB, OA & OB, A & B>

Added in v2.2.3

lazy

Signature

export declare function lazy<I, O, A>(id: string, f: () => Codec<I, O, A>): Codec<I, O, A>

Added in v2.2.3

mapLeftWithInput

Signature

export declare const mapLeftWithInput: <I>(
  f: (i: I, e: D.DecodeError) => D.DecodeError
) => <O, A>(codec: Codec<I, O, A>) => Codec<I, O, A>

Added in v2.2.3

nullable

Signature

export declare function nullable<I, O, A>(or: Codec<I, O, A>): Codec<null | I, null | O, null | A>

Added in v2.2.3

partial

Signature

export declare function partial<P extends Record<string, Codec<unknown, any, any>>>(
  properties: P
): Codec<unknown, Partial<{ [K in keyof P]: OutputOf<P[K]> }>, Partial<{ [K in keyof P]: TypeOf<P[K]> }>>

Added in v2.2.3

readonly

Signature

export declare const readonly: <I, O, A>(codec: Codec<I, O, A>) => Codec<I, O, Readonly<A>>

Added in v2.2.16

record

Signature

export declare function record<O, A>(
  codomain: Codec<unknown, O, A>
): Codec<unknown, Record<string, O>, Record<string, A>>

Added in v2.2.3

refine

Signature

export declare const refine: <A, B extends A>(
  refinement: Refinement<A, B>,
  id: string
) => <I, O>(from: Codec<I, O, A>) => Codec<I, O, B>

Added in v2.2.3

struct

Signature

export declare function struct<P extends Record<string, Codec<unknown, any, any>>>(
  properties: P
): Codec<unknown, { [K in keyof P]: OutputOf<P[K]> }, { [K in keyof P]: TypeOf<P[K]> }>

Added in v2.2.15

sum

Signature

export declare function sum<T extends string>(
  tag: T
): <M extends Record<string, Codec<unknown, any, any>>>(
  members: M
) => Codec<unknown, OutputOf<M[keyof M]>, TypeOf<M[keyof M]>>

Added in v2.2.3

tuple

Signature

export declare function tuple<C extends ReadonlyArray<Codec<unknown, any, any>>>(
  ...components: C
): Codec<unknown, { [K in keyof C]: OutputOf<C[K]> }, { [K in keyof C]: TypeOf<C[K]> }>

Added in v2.2.3

fromType

Use fromStruct instead.

Signature

export declare const fromType: typeof fromStruct

Added in v2.2.8

type

Use struct instead.

Signature

export declare const type: typeof struct

Added in v2.2.3

constructors

fromDecoder

Signature

export declare function fromDecoder<I, A>(decoder: D.Decoder<I, A>): Codec<I, A, A>

Added in v2.2.3

literal

Signature

export declare function literal<A extends readonly [L, ...ReadonlyArray<L>], L extends S.Literal = S.Literal>(
  ...values: A
): Codec<unknown, A[number], A[number]>

Added in v2.2.3

make

Signature

export declare function make<I, O, A>(decoder: D.Decoder<I, A>, encoder: E.Encoder<O, A>): Codec<I, O, A>

Added in v2.2.3

instances

Invariant

Signature

export declare const Invariant: Invariant3<'io-ts/Codec'>

Added in v2.2.8

URI

Signature

export declare const URI: 'io-ts/Codec'

Added in v2.2.3

URI (type alias)

Signature

export type URI = typeof URI

Added in v2.2.3

model

Codec (interface)

Laws:

1. pipe(codec.decode(u), E.fold(() => u, codec.encode)) = u for all u in unknown
2. codec.decode(codec.encode(a)) = E.right(a) for all a in A

Signature

export interface Codec<I, O, A> extends D.Decoder<I, A>, E.Encoder<O, A> {}

Added in v2.2.3

primitives

UnknownArray

Signature

export declare const UnknownArray: Codec<unknown, unknown[], unknown[]>

Added in v2.2.3

UnknownRecord

Signature

export declare const UnknownRecord: Codec<unknown, Record<string, unknown>, Record<string, unknown>>

Added in v2.2.3

boolean

Signature

export declare const boolean: Codec<unknown, boolean, boolean>

Added in v2.2.3

number

Signature

export declare const number: Codec<unknown, number, number>

Added in v2.2.3

string

Signature

export declare const string: Codec<unknown, string, string>

Added in v2.2.3

utils

InputOf (type alias)

Signature

export type InputOf<C> = D.InputOf<C>

Added in v2.2.8

OutputOf (type alias)

Signature

export type OutputOf<C> = E.OutputOf<C>

Added in v2.2.3

TypeOf (type alias)

Signature

export type TypeOf<C> = E.TypeOf<C>

Added in v2.2.3