https://github.com/nvie/decoders

Elegant validation library for type-safe input data (for TypeScript and Flow)
https://github.com/nvie/decoders

checking composition decoders elm flow input javascript type typescript validation

Last synced: about 2 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/nvie/decoders
• Owner: nvie
• License: mit
• Created: 2017-10-04T19:40:11.000Z (over 6 years ago)
• Default Branch: main
• Last Pushed: 2024-04-30T04:47:12.000Z (2 months ago)
• Last Synced: 2024-05-02T01:08:34.811Z (about 2 months ago)
• Topics: checking, composition, decoders, elm, flow, input, javascript, type, typescript, validation
• Language: TypeScript
• Homepage: https://decoders.cc
• Size: 46.4 MB
• Stars: 355
• Watchers: 5
• Forks: 28
• Open Issues: 14
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Lists

• awesome-list - decoders - safe input data (for TypeScript and Flow) | nvie | 262 | (JavaScript)
• awesome-flow - decoders - Type-safe data validation for Flow. (Packages / Helpers)
• awesome-stars - decoders - safe input data (for TypeScript and Flow) | nvie | 354 | (TypeScript)

README

        



[![npm](https://img.shields.io/npm/v/decoders.svg)](https://www.npmjs.com/package/decoders)

[![Build Status](https://github.com/nvie/decoders/workflows/test/badge.svg)](https://github.com/nvie/decoders/actions)

[![Bundle size for decoders](https://pkg-size.dev/badge/bundle/4200)](https://pkg-size.dev/decoders)

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

[TypeScript](https://www.typescriptlang.org/).

## Introduction

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

```typescript

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[];

//    }

```

## Installation

```bash

npm install decoders

```

## Requirements

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

correctly!

```js

// tsconfig.json

{

  "compilerOptions": {

    "strict": true

  }

}

```

## Documentation

















































































































































Documentation can be found on [https://decoders.cc](https://decoders.cc).

## Building your own decoders

There is a dedicated page in the docs that explains how to

[build your own decoders](https://decoders.cc/building-your-own.html) — it’s fun!