Skip to content
/ decoders Public

Elegant validation library for type-safe input data (for TypeScript and Flow)


Notifications You must be signed in to change notification settings


Repository files navigation

Decoders logo

npm Build Status Bundle size for decoders

Elegant and battle-tested validation library for type-safe input data for TypeScript.


Data entering your application from the outside world should not be trusted without validation and often is of the any type, effectively disabling your type checker around input values. It's an industry good practice to validate your expectations right at your program's boundaries. This has two benefits: (1) your inputs are getting validated, and (2) you can now statically know for sure the shape of the incoming data. Decoders help solve both of these problems at once.

Basic example

import { array, iso8601, number, object, optional, string } from 'decoders';

// Incoming data at runtime
const externalData = {
  id: 123,
  name: 'Alison Roberts',
  createdAt: '1994-01-11T12:26:37.024Z',
  tags: ['foo', 'bar'],

// Write the decoder (= what you expect the data to look like)
const userDecoder = object({
  id: number,
  name: string,
  createdAt: optional(iso8601),
  tags: array(string),

// Call .verify() on the incoming data
const user = userDecoder.verify(externalData);
//    ^^^^
//    TypeScript automatically infers this type as:
//    {
//      id: number;
//      name: string;
//      createdAt?: Date;
//      tags: string[];
//    }


npm install decoders


You must set strict: true in your tsconfig.json in order for type inference to work correctly!

// tsconfig.json
  "compilerOptions": {
    "strict": true


Documentation can be found on

Building your own decoders

There is a dedicated page in the docs that explains how to build your own decoders — it’s fun!