IF Commons GitHub

decode

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-core FR-002

Decoders: everything that enters a program is decoded from unknown into a typed value once, where it enters, and past a decoder no code holds unknown (0001-core FR-002). The type assertions a decoder needs are confined to this file. Taken from erga's kernel (decode.decode.ts), with nullable, record, tuple and json added.

import { integer, object, string } from "./decode.ts";
const person = object({ name: string, age: integer });
person({ name: "Ada", age: 36 }); // { kind: "ok", value: { name: "Ada", age: 36 } }

Source: commons/core/src/decode.ts

19 of 23 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

arrayfunction
function array<T>(element: Decoder<T>): Decoder<readonly T[]>

An array whose every element decodes.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

booleanconst
const boolean: Decoder<boolean>

A boolean.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

describefunction
function describe(input: unknown): string

A short description of a value for an error message: its type, and the start of it where it is a string.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

formatDecodeErrorfunction
function formatDecodeError(e: DecodeError): string

A decode error as one sentence: $.age: expected an integer, found the string "x".

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

integerconst
const integer: Decoder<number>

An integer.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

jsonfunction
function json<T>(text: string, decoder: Decoder<T>): Result<T, DecodeError>

Text parsed as JSON and decoded; text that is not JSON is an error at $ that says so.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

literalfunction
function literal<const L extends readonly string[]>(...values: L): Decoder<L[number]>

One of the given string literals.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

mapDecoderfunction
function mapDecoder<T, U>(base: Decoder<T>, f: (value: T) => U): Decoder<U>

A decoded value transformed, as a decoder of the new type.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

nullablefunction
function nullable<T>(inner: Decoder<T>): Decoder<T | null>

null, or what inner decodes.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

numberconst
const number: Decoder<number>

A finite number.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

objectfunction
function object<R extends Fields, O extends Fields = Record<never, never>>(required: R, optional?: O | undefined): Decoder<ObjectOf<R, O>>

An object whose every required field decodes; optional fields may be absent (or undefined), and are then absent from the value. Other fields are dropped.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

oneOffunction
function oneOf<const D extends readonly Decoder<unknown>[]>(...alternatives: D): Decoder<Decoded<D[number]>>

The first of several decoders that accepts the input.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

recordfunction
function record<T>(value: Decoder<T>): Decoder<Readonly<Record<string, T>>>

An object used as a map: every own key kept, every value decoded.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

refinefunction
function refine<T, B extends string>(base: Decoder<T>, name: B, valid: (value: T) => boolean): Decoder<Brand<T, B>>

A value of T validated as a B: the one way a branded type is made.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

stringconst
const string: Decoder<string>

A string.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

taggedfunction
function tagged<const D extends Readonly<Record<string, Decoder<{ readonly kind: string; }>>>>(alternatives: D): Decoder<Decoded<D[keyof D]>>

A union of object types told apart by their kind: the decoder of the alternative the input's kind names.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

tuplefunction
function tuple<const D extends readonly Decoder<unknown>[]>(...elements: D): Decoder<{ readonly [K in keyof D]: Decoded<D[K]>; }>

An array of exactly as many elements as decoders, each decoded by its own.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

unknownValueconst
const unknownValue: Decoder<unknown>

Any value at all, kept as unknown: for a field whose contents another decoder reads later.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Decodedtype
type Decoded<D> = D extends Decoder<infer T> ? T : never;

The type a decoder gives.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

DecodeErrortypeno test imports it
type DecodeError = { readonly kind: "decode"; readonly path: string; readonly expected: string; readonly found: string };

Why a value did not decode: the path of the first field that failed, what was expected there and what was found.

Decodertypeno test imports it
type Decoder<T> = (input: unknown, path?: string) => Result<T, DecodeError>;

A function from anything to a typed value, or the reason it is not one; path names where the value sits, $ by default.

Fieldstypeno test imports it
type Fields = Readonly<Record<string, Decoder<unknown>>>;

The decoders of an object's fields.

ObjectOftypeno test imports it
type ObjectOf<R extends Fields, O extends Fields> = { readonly [K in keyof R]: Decoded<R[K]> } & {
  readonly [K in keyof O]?: Decoded<O[K]>;
};

The value an object decoder gives: the required fields, and the optional ones that may be absent.

Titles, headings, exports, tables, columns and requirements. Esc closes.