Skip to content

Minimalistic yet feature-rich IO decoding and encoding

Notifications You must be signed in to change notification settings

ceramicnetwork/codeco

Repository files navigation

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.

About

Minimalistic yet feature-rich IO decoding and encoding

Resources

Stars

Watchers

Forks

Packages

No packages published