arrayfunctionfunction array<T>(element: Decoder<T>): Decoder<readonly T[]>An array whose every element decodes.
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 } }arrayfunctionfunction array<T>(element: Decoder<T>): Decoder<readonly T[]>An array whose every element decodes.
booleanconstconst boolean: Decoder<boolean>A boolean.
describefunctionfunction describe(input: unknown): stringA short description of a value for an error message: its type, and the start of it where it is a string.
formatDecodeErrorfunctionfunction formatDecodeError(e: DecodeError): stringA decode error as one sentence: $.age: expected an integer, found the string "x".
integerconstconst integer: Decoder<number>An integer.
jsonfunctionfunction 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.
literalfunctionfunction literal<const L extends readonly string[]>(...values: L): Decoder<L[number]>One of the given string literals.
mapDecoderfunctionfunction mapDecoder<T, U>(base: Decoder<T>, f: (value: T) => U): Decoder<U>A decoded value transformed, as a decoder of the new type.
nullablefunctionfunction nullable<T>(inner: Decoder<T>): Decoder<T | null>null, or what inner decodes.
numberconstconst number: Decoder<number>A finite number.
objectfunctionfunction 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.
oneOffunctionfunction oneOf<const D extends readonly Decoder<unknown>[]>(...alternatives: D): Decoder<Decoded<D[number]>>The first of several decoders that accepts the input.
recordfunctionfunction record<T>(value: Decoder<T>): Decoder<Readonly<Record<string, T>>>An object used as a map: every own key kept, every value decoded.
refinefunctionfunction 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.
stringconstconst string: Decoder<string>A string.
taggedfunctionfunction 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.
tuplefunctionfunction 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.
unknownValueconstconst unknownValue: Decoder<unknown>Any value at all, kept as unknown: for a field whose contents another decoder reads later.
Decodedtypetype Decoded<D> = D extends Decoder<infer T> ? T : never;The type a decoder gives.
DecodeErrortypeno test imports ittype 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 ittype 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 ittype Fields = Readonly<Record<string, Decoder<unknown>>>;The decoders of an object's fields.
ObjectOftypeno test imports ittype 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.