Codeco

Lightweight TypeScript-first encoding and decoding of complex objects.

Idea

A value of type Codec<A, O, I> (called "codec") is the runtime representation of the static type A.

A codec can:

• decode inputs of type I,
• encode values to type O,
• be used as a type predicate.

export abstract class Codec<A, O = A, I = unknown> {
  protected constructor(readonly name: string) {}

  abstract is(input: unknown): input is A;
  abstract encode(value: A): O;
  abstract decode(input: I): Either<Error, A>;
}

As an example, here is a codec for integer encoded as a string:

// Represents integer `number`, the first type parameter.
// If we encode a known number, it will turn into `string` (the second type parameter).
// If we want to receive a number, the codec can accept `string` as input to parse (the third type parameter).
// To decode `unknown` input do something like `string.pipe(numberAsString)`.
class IntAsStringCodec extends Codec<number, string, string> {
  constructor() {
    super(`IntAsString`);
  }

  // Similar to `instanceof`.
  is(input: unknown): input is number {
    return typeof input === "number";
  }

  decode(input: string, context: Context): Validation<number> {
    const supposedlyInt = parseInt(input, 10);
    // If an integer
    if (supposedlyInt.toString() === input) {
      // Return value
      // Beware: do not return plain value, wrap it in `context.success`
      return context.success(supposedlyInt);
    } else {
      // If anything is wrong, signal failure by returning `context.failure`.
      // Whatever happens, **do not throw an error**.
      return context.failure(`Not an integer`);
    }
  }

  // Encode known value to string output.
  encode(value: number): string {
    return value.toString();
  }
}

const intAsString = new IntAsStringCodec();

In most cases though, creating codecs this way is an overkill. Codec combinators provided by the library are enough for 90% of use cases.

The Either type represents a value of one of two possible types (a disjoint union):

• Left meaning success,
• Right meaning failure.

type Either<TError, TValue> =
  | {
      readonly _tag: "Left";
      readonly left: TError;
    }
  | {
      readonly _tag: "Right";
      readonly right: TValue;
    };

You could check a result of validation using isValid or isError helpers:

import { string, refinement, validate, isError } from "codeco";

const longString = refinement(string, (s) => s.length >= 100);
const validation = validate(longString, "short input");
if (isError(validation)) {
  console.log("Validation errorr", validation.left);
}
const valid = validation.right; // Here goes proper long string

Implemented types

Description	TypeScript	codec
null	null	cs.null or cs.nullCodec
undefined	undefined	cs.undefined
void	void	cs.void
string	string	cs.string
number	number	cs.number
boolean	boolean	cs.boolean
BigInt	bigint	cs.bigint
unknown	unknown	cs.unknown
literal	's'	cs.literal('s')
array of unknown	Array<unknown>	cs.unknownArray
dictionary of unknown	Record<string, unknown>	cs.unknownDictionary
array of type	Array<A>	cs.array(A)
any	any	cs.any
never	never	cs.never
dictionary	Record<string, A>	cs.dictionary(A)
record of type	Record<K, A>	cs.record(K, A)
partial	Partial<{ name: string }>	cs.partial({ name: cs.string })
readonly	Readonly<A>	cs.readonly(A)
type alias	type T = { name: A }	cs.type({ name: A })
tuple	[A, B]	cs.tuple([ A, B ])
union	A | B	cs.union([ A, B ])
intersection	A & B	cs.intersection([ A, B ])
keyof	keyof M	cs.keyof(M) (only supports string keys)
recursive types		cs.recursive(name, definition)
exact types	✘	cs.exact(type) (no unknown extra properties)
strict	✘	cs.strict({ name: A }) (an alias of cs.exact(cs.type({ name: A })))
sparse	✘	cs.sparse({ name: A }) similar to cs.intersect(cs.type(), cs.partial()
replacement	✘	cs.replacement(A, altInput)
optional	A | undefined	cs.optional(A)

Linear parsing

In addition to structural encoding/decoding, we provide linear parsing functions in form of Parser Combinators available from 'codeco/linear':

import * as P from "codeco/linear";
import { getOrThrow } from "codeco";

const line = P.seq(P.literal("My name is "), P.match(/\w+/));
const name = P.map(line, (parsed) => parsed[1]); // `map` combinator
const input = new P.StringTape("My name is Marvin"); // Prepare input for consumption
const decodedName = getOrThrow(P.parseAll(input)); // Would throw if input does not conform to expected format

Provided combinators:

• literal("string-value") - literal value
• map(combinator, mapFn) - map return value of combinator to something else,
• mapFold(combinator, mapFn) - map return value of combinator to something else as Either, so optionally indicating failure,
• match(regexp) - like literal, but matches a RegExp,
• seq(combinatorA, combinatorB, ...) - match combinators and return array of their results,
• join(combinators) - match combinators and their results as a single string,
• joinSeq(combinators) - shortcut for join(seq(combinatros)),
• option(combinator, value) - try matching combinator, return value if the combinator does not match,
• choice(combinatorA, combinatorB, ...) - match any of the passed combinators,
• sepBy(combinator, separator, min = 1, max = Infinity) - match sequence of 1 or more combinators separated by separator, like A, A + A, A + A + A, etc.
• many(combinator, min = 1, max = Infinity) - array of combinators of length [min, max),
• parseAll(combinator) - make sure all the input is consumed.