https://github.com/nvie/decoders
Elegant validation library for type-safe input data for TypeScript
https://github.com/nvie/decoders
checking composition decoders elm flow input javascript type typescript validation
Last synced: 7 months ago
JSON representation
Elegant validation library for type-safe input data for TypeScript
- Host: GitHub
- URL: https://github.com/nvie/decoders
- Owner: nvie
- License: mit
- Created: 2017-10-04T19:40:11.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2025-04-11T15:12:37.000Z (8 months ago)
- Last Synced: 2025-04-13T10:58:07.024Z (8 months ago)
- Topics: checking, composition, decoders, elm, flow, input, javascript, type, typescript, validation
- Language: TypeScript
- Homepage: https://decoders.cc
- Size: 46.3 MB
- Stars: 375
- Watchers: 4
- Forks: 27
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-flow - decoders - Type-safe data validation for Flow. (Packages / Helpers)
- awesome-list - decoders - safe input data (for TypeScript and Flow) | nvie | 262 | (JavaScript)
README
[](https://www.npmjs.com/package/decoders)
[](https://github.com/nvie/decoders/actions)
[](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!