ts-codec

``bash
npm install ts-codec
`

Glossary

- What is ts-codec
- Getting started example
- Codec Library
- Gotchas
- Related Projects

What is ts-codec

This tool was built to solve a specific set of use-cases surrounding validation and Serialization/Deserialization of data in TypeScript applications. This is achieved by providing a suite of tagged Codecs designed to be composed together in order to describe 2-way data schemas and derive static TypeScript types from. These schemas can then be encoded as JSON-Schema to be used for data validation through other excellent JSON-schema validation tools like AJV.

This tool is heavily inspired by other similar tools like Zod and io-ts and can almost be seen as a type of marriage of the two in order to achieve something slightly different. The codec API follows Zod's quite closely (Thanks colinhacks for the hard work :) with the exception that it is altered to support two-way transformations of data.

In summary, the goals of this project are:

- Describe a _single_ schema that can;
- Encode and Decode data (Date <-> string, for example)
- Be used to derive TypeScript types from both the Encoded and Decoded form
- Be used to validate data, both in the Encoded and Decoded form

Quick Example

Just to demonstrate the basics and help get the idea across

`ts
import * as t from 'ts-codec';

const date = t.codec(
'Date',
(date) => date.toISOString(),
(date) => new Date(date)
);

const schema = t.object({
name: t.string,
date: date
});

schema.encode({ name: 'James', date: new Date() }); // { name: 'James', date: '1970-01-01T00:00:00.000Z' }
schema.decode({ name: 'James', date: '1970-01-01T00:00:00.000Z' }); // { name: 'James', date: 1970-01-01T00:00:00.000Z }

type d = t.Decoded; // { name: string; date: Date; }
type d = t.Encoded; // { name: string; date: string; }

// Parser for the custom date codec that isn't part of the standard set provided by ts-codec
const DateParser = {
tag: date._tag,
parse: () => ({ type: 'string' })
};

t.generateJSONSchema(schema, { parsers: [DateParser] });
/*
=> {
type: "object",
properties: {
name: { type: "string" },
date: { type: "string" }
},
additionalProperties: false,
required: ["name", "date"]
}
*/
`

Codec Library

- Primitives
- String
- Number
- Boolean
- Null
- Any
- Literal
- Enum
- Object
- Record
- Array
- Tuple
- Intersection
- Union
- Optional
- Omit
- Partial
- Metadata
- Codec

$3

Basic TS primitive types. These can be though of as identity codecs that accept their value and return their value. No transformations happen during encode/decode

`ts
import * as t from 'ts-codec';

t.string;
t.number;
t.boolean;
t.null;
t.any;

// accepts exactly 'value'
t.literal('value');
`

$3

Accepts native TypeScript enum values as an input

`ts
import * as t from 'ts-codec';

enum Fruits {
Apple = 'apple',
Banana = 'banana',
Cantaloupe = 'Cantaloupe'
}

const FruitEnum = t.Enum(Fruits);
type d = t.Encoded; // Fruits

FruitEnum.encode(Fruits.Apple); // 'apple'
FruitEnum.encode('apple'); // type error
`

$3

Accepts an arbitrarily nested map of key => codec

`ts
import * as t from 'ts-codec';

const schema = t.object({
name: t.string
});
type d = t.Encoded; // {name: string}

schema.encode({ name: 'James' }); // { name: "James" }
`

$3

A ts-codec equivalent of TypeScript's Record type. Accepts a Codec to be used as the record value

`ts
import * as t from 'ts-codec';

const schema = t.record(t.string);
type d = t.Encoded; // Record

schema.encode({ a: 'b', c: 'd' }); // { a: 'b', c: 'd' }
`

$3

A ts-codec equivalent of TypeScript's Array type. Accepts a Codec to be used as the array elements

`ts
import * as t from 'ts-codec';

const array = t.array(t.string);
type d = t.Encoded; // Array

array.encode(['1', '2']); // ['1', '2']
`

$3

Equivalent to TypeScript's [T1, T2, ...T3[]] type semantics. Accepts an array of Codec's to be used positionally against array elements

`ts
import * as t from 'ts-codec';

const tuple = t.tuple([t.string, t.number, t.boolean]);
type d = t.Encoded; // [string, number, boolean]

array.encode(['1', 2, true]); // ['1', 2, true]
array.encode(['1', '2', 3]); // type error
`

Intersections and Unions

$3

Intersections and unions can be created by calling .and(codec) and .or(codec) on any codec.

Calling .and and .or on a codec produces a new codec. It does _not_ modify the original

`ts
import * as t from 'ts-codec';

const A = t.object({
a: t.string.or(t.number)
});

const B = t.object({
b: t.boolean.or(t.null)
});

const schema = A.and(B);
type d = t.Encoded; // { a: string | number, b: boolean | null }

schema.encode({ a: '', b: null }); // {a: '', b: null}
`

$3

Any codec can be made optional by calling .optional() on the codec.

Calling .optional on a codec produces a new codec. It does _not_ modify the original

`ts
import * as t from 'ts-codec';

const schema = t.object({
a: t.string.optional(),
b: t.number
});

type d = t.Encoded; // {a?: string | undefined, b: number}

schema.encode({ b: 1 }); // {b: 1}
`

$3

Calling .omit(codec, mask) will produce a new codec with object properties omitted according to the given mask. Acts similar to TS Omit.

Calling .omit on a codec produces a new codec. It does _not_ modify the original

`ts
import * as t from 'ts-codec';

const Schema = t.object({
a: t.string,
b: t.number
});
const WithOmit = t.omit(Schema, ['b']);

type d = t.Encoded; // {a: string}

schema.encode({ a: '1' }); // {a: '1'}
`

$3

Calling .partial(codec) will produce a new codec with all top-level object properties made optional. Acts similar to TS Partial.

Calling .partial on a codec produces a new codec. It does _not_ modify the original

`ts
import * as t from 'ts-codec';

const Schema = t.object({
a: t.string,
b: t.number
});
const WithPartial = t.partial(Schema);

type d = t.Encoded; // {a?: string, b?: number}

schema.encode({ b: 1 }); // {b: 1}
`

$3

Codecs can have arbitrary metadata associated with them. This information is mostly intended to be consumed by codec parsers to assist in generation of data. An example usage of this would be adding description fields to JSON-schema or specifying special validation properties like min: 1 or pattern: /abc/.

Calling .meta on a codec produces a new codec. It does _not_ modify the original

`ts
import * as t from 'ts-codec';

const schema = t.object({
name: t.string.meta({
description: 'The name of the schema'
}),
things: t.number.meta({
description: 'The number of things this schema can have',
min: 5
})
});
`

$3

The .codec function can be used to construct custom codecs. Any codec can be constructed with this util - in fact all codecs exposed were internally crafted by this.

The tag is a unique identifier for the codec _type_ and should not collide with any of the other codecs. This value can be used by parsers in order to generate data from a codec tree. For example, the JSON-Schema generator included uses these to determine what type of JSON-schema to produce as it encounters codecs.

When building custom codecs it is important to ensure that they check the data they are transforming. If incoming data is unexpected then they _must_ explicitly throw. This behavior is relied upon to support unions which will sequentially encode/decode data using codecs until one succeeds.

`ts
import * as t from 'ts-codec';

const date = t.codec(
'Date',
(date) => date.toISOString(),
(date) => new Date(date)
);

type d = t.Encoded; // string
type d = t.Decoded; // Date

schema.encode(new Date()); // '1970-01-01T00:00:00.000Z'
schema.decode(new Date()); // Date 1970-01-01T00:00:00.000Z
`

Gotchas

The order of codecs in a union matter

It is important to ensure that the more specific codecs appear first in a union chain in order to ensure they are used to parse matching data.

For example

`ts
date.or(t.string).decode('1970-01-01T00:00:00.000Z'); // => Date 1970-01-01T00:00:00.000Z // good!
t.string.or(date).decode('1970-01-01T00:00:00.000Z'); // => '1970-01-01T00:00:00.000Z' // bad!

// or more extreme

t.string.or(t.Any); // good
t.Any.or(t.string); // bad
`

Intersections of .object() and .record()

In the current implementation, intersections between .object() and .record() won't work as expected if the record and object define different codec values.

I haven't given enough thought to what the expected behaviour should be in this scenario.

`ts
const schema = t.object({ a: t.string }).and(t.record(t.string)); // This is fine, can be used to define known keys
type Schema = t.Encoded; // {a: string} & Record

schema.encode({ a: '', b: '' }); // works

// ==

const schema = t.object({ a: t.string }).and(t.record(t.boolean)); // This won't work. The type will be correct but it won't be able to transform data

schema.encode({ a: '', b: true }); // The record encoder will throw
`

One way of solving this might be to pass only the subset of data that was not evaluated against the object codec to the record codec.

Related Projects

$3

https://github.com/gcanti/io-ts

The concept of Codecs was inspired by this project, but there are a few differences:

+ The very functional API is can be quite verbose, both for defining custom Codecs and for building schemas. The Zod API however is debatably much more pragmatic.
+ There is limited or no support for converting io-ts schemas into JSON-Schema. This is a problem for two reasons:
+ There is no nice way to have cross-language compatibility
+ There is no nice way to generate API documentation

Ts-codec on the other hand was built with a focus on being parsable - allowing it to be easily transformed to JSON-Schema or other data formats

$3

https://github.com/colinhacks/zod

The API for ts-codec was primarily based on Zod's, but also with a few differences:

+ Zod can only describe transformation of data in one direction.
+ Zod can only validate data on the input side of it's data transformation
+ While possible to generate JSON-Schema for Zod schemas, they can only be generated for the input` side of it's transformation