@ambarltd/core 0.1.17

package/dist/json/encoder.d.ts

@@ -0,0 +1,50 @@
+import { Maybe, Nullable } from "../maybe";
+import { Json } from "./types";
+/** Infer the type from an encoder definition. */
+type Infer<A extends Encoder<any>> = A extends Encoder<infer B> ? B : never;
+/**
+ * An Encoder is the opposite of a Decoder.
+ *
+ * It takes a structured value and transforms it into
+ * an object of type Json.
+ */
+declare class Encoder<A> {
+    readonly run: (v: A) => Json;
+    constructor(f: (v: A) => Json);
+    rmap<W>(f: (v: W) => A): Encoder<W>;
+}
+type EncoderDef<A> = {
+    [P in keyof A]: Encoder<A[P]> | EncoderOptional<A[P]>;
+};
+/**
+ * Encode two values into a single one.
+ * Conflicts result in properties being overwritten.
+ */
+declare const both: <T, U>(left: Encoder<T>, right: Encoder<U>) => Encoder<[T, U]>;
+declare const json: Encoder<Json>;
+declare const boolean: Encoder<boolean>;
+declare const number: Encoder<number>;
+declare const string: Encoder<string>;
+declare const array: <A>(encoder: Encoder<A>) => Encoder<Array<A>>;
+declare const object: <A>(encoders: EncoderDef<A>) => Encoder<A>;
+declare const pair: <L, R>(sleft: Encoder<L>, sright: Encoder<R>) => Encoder<[L, R]>;
+declare const triple: <A, B, C>(sA: Encoder<A>, sB: Encoder<B>, sC: Encoder<C>) => Encoder<[A, B, C]>;
+declare const maybe: <V>(encoder: Encoder<V>) => Encoder<Maybe<V>>;
+declare const nullable: <V>(encoder: Encoder<V>) => Encoder<Nullable<V>>;
+/** An encoder for object keys that omits the field if the value is Nothing. */
+declare class EncoderOptional<A> {
+    readonly encoder: Encoder<A>;
+    private constructor();
+    static from<T>(e: Encoder<Maybe<T>>): EncoderOptional<Maybe<T>>;
+    rmap<B>(f: (v: B) => A): EncoderOptional<B>;
+}
+declare const optionalMaybe: <V>(encoder: Encoder<V>) => EncoderOptional<Maybe<V>>;
+declare const optionalNullable: <V>(encoder: Encoder<NonNullable<V>>) => EncoderOptional<Nullable<V>>;
+declare const optional: <V>(encoder: Encoder<V>) => EncoderOptional<V | undefined>;
+declare const oneOf: <V>(f: (v: V) => Encoder<V>) => Encoder<V>;
+declare const stringEnum: <const T extends string[]>(strs: T) => Encoder<T[number]>;
+/** Encode a value into a JSON string by stringifying its JSON representation. */
+declare const stringified: <T>(inner: Encoder<T>) => Encoder<T>;
+/** Define a recursive encoder. */
+declare function recursive<A>(f: (p: Encoder<A>) => Encoder<A>): Encoder<A>;
+export { type Infer, Encoder, type EncoderDef, type EncoderOptional, json, boolean, number, string, array, object, pair, maybe, nullable, triple, optional, oneOf, both, stringEnum, stringified, optionalNullable, optionalMaybe, recursive, };

package/dist/json/encoder.js

@@ -0,0 +1,115 @@
+import { Nothing, Just } from "../maybe";
+/**
+ * An Encoder is the opposite of a Decoder.
+ *
+ * It takes a structured value and transforms it into
+ * an object of type Json.
+ */
+class Encoder {
+    run;
+    constructor(f) {
+        this.run = f;
+    }
+    rmap(f) {
+        return new Encoder(v => this.run(f(v)));
+    }
+}
+const toAny = () => new Encoder(v => v);
+/**
+ * Encode two values into a single one.
+ * Conflicts result in properties being overwritten.
+ */
+const both = (left, right) => new Encoder(([l, r]) => {
+    return Object.assign({}, left.run(l), right.run(r));
+});
+const json = toAny();
+const boolean = toAny();
+const number = new Encoder(input => {
+    if (!Number.isFinite(input)) {
+        throw new Error(`Cannot encode non-finite number: ${String(input)}`);
+    }
+    return input;
+});
+const string = toAny();
+const array = (encoder) => new Encoder((input) => input.map(encoder.run));
+const object = (encoders) => new Encoder(input => {
+    const result = {};
+    for (const field in encoders) {
+        const encoder = encoders[field];
+        switch (true) {
+            case encoder instanceof EncoderOptional: {
+                const encoded = encoder.encoder.run(input[field]);
+                if (typeof encoded != "object" || encoded === null || !("nothing" in encoded || "just" in encoded)) {
+                    throw new Error(`Invalid output of EncoderOptional: ${encoded}`);
+                }
+                if ("just" in encoded) {
+                    result[field] = encoded["just"];
+                }
+                break;
+            }
+            case encoder instanceof Encoder:
+                const encoded = encoder.run(input[field]);
+                result[field] = encoded;
+                break;
+            default:
+                encoder;
+        }
+    }
+    return result;
+});
+const pair = (sleft, sright) => new Encoder(input => {
+    const [left, right] = input;
+    return [sleft.run(left), sright.run(right)];
+});
+const triple = (sA, sB, sC) => new Encoder(input => {
+    const [a, b, c] = input;
+    return [sA.run(a), sB.run(b), sC.run(c)];
+});
+const maybe = (encoder) => new Encoder(input => (input instanceof Nothing ? { nothing: {} } : { just: encoder.run(input.value) }));
+const nullable = (encoder) => new Encoder(input => (input === null ? null : encoder.run(input)));
+/** An encoder for object keys that omits the field if the value is Nothing. */
+class EncoderOptional {
+    encoder;
+    constructor(encoder) {
+        this.encoder = encoder;
+    }
+    static from(e) {
+        return new EncoderOptional(e);
+    }
+    rmap(f) {
+        return new EncoderOptional(this.encoder.rmap(f));
+    }
+}
+const optionalMaybe = (encoder) => EncoderOptional.from(maybe(encoder));
+const optionalNullable = (encoder) => optionalMaybe(encoder).rmap(v => v === null ? Nothing()
+    : v === undefined ? Nothing()
+        : Just(v));
+const optional = (encoder) => optionalMaybe(encoder).rmap((input) => {
+    if (typeof input === "undefined") {
+        return Nothing();
+    }
+    return Just(input);
+});
+const oneOf = (f) => new Encoder(input => {
+    const encoder = f(input);
+    return encoder.run(input);
+});
+const stringEnum = (strs) => string.rmap(input => {
+    if (!strs.includes(input)) {
+        throw new Error(`Cannot encode '${input}'. Expected one of '${strs.join(", ")}'"`);
+    }
+    return input;
+});
+/** Encode a value into a JSON string by stringifying its JSON representation. */
+const stringified = (inner) => string.rmap(v => JSON.stringify(inner.run(v)));
+/** Define a recursive encoder. */
+function recursive(f) {
+    const base = new Encoder(_ => {
+        throw new Error("A recursive encoder cannot immediately call itself.");
+    });
+    const top = f(base);
+    // @ts-expect-error assigning to read-only prop
+    base.run = top.run;
+    return top;
+}
+export { Encoder, json, boolean, number, string, array, object, pair, maybe, nullable, triple, optional, oneOf, both, stringEnum, stringified, optionalNullable, optionalMaybe, recursive, };

package/dist/json/schema.d.ts

@@ -0,0 +1,78 @@
+import * as decoder from "./decoder";
+import * as encoder from "./encoder";
+import { Result } from "../result";
+import { Decoder, type DecoderOptional } from "./decoder";
+import { Encoder, type EncoderOptional } from "./encoder";
+import { Json } from "./types";
+import { Maybe, Nullable } from "../maybe";
+/** Infer the type from a schema definition. */
+type Infer<A extends Schema<any>> = A extends Schema<infer B> ? B : never;
+/**
+ * A `Schema<A>` contains information to encode and decode a value.
+ *
+ * This allows us to have safe conversion to and from JSON.
+ */
+declare class Schema<A> {
+    decoder: Decoder<A>;
+    encoder: Encoder<A>;
+    constructor(decoder: Decoder<A>, encoder: Encoder<A>);
+    dimap<W>(p: (v: A) => W, s: (v: W) => A): Schema<W>;
+    chain<W>(p: (v: A) => Decoder<W>, s: (v: W) => A): Schema<W>;
+}
+declare function decode<A>(schema: Schema<A>, input: unknown): Result<string, A>;
+declare function encode<A>(schema: Schema<A>, input: A): Json;
+/** Create a Schema. */
+declare function from<A>(decoder: Decoder<A>, encoder: Encoder<A>): Schema<A>;
+type SchemaDef<A> = {
+    [D in keyof A]: Schema<A[D]> | SchemaOptional<A[D]>;
+};
+declare const json: Schema<Json>;
+declare const boolean: Schema<boolean>;
+declare const number: Schema<number>;
+declare const string: Schema<string>;
+declare const array: <A>(schema: Schema<A>) => Schema<Array<A>>;
+declare const both: <T, U>(left: Schema<T>, right: Schema<U>) => Schema<[T, U]>;
+/** Schema for an object field that may not be present. */
+declare class SchemaOptional<A> {
+    readonly decoder: DecoderOptional<A>;
+    readonly encoder: EncoderOptional<A>;
+    constructor(decoder: DecoderOptional<A>, encoder: EncoderOptional<A>);
+    dimap<W>(p: (v: A) => W, s: (v: W) => A): SchemaOptional<W>;
+}
+/** An object field that may be absent. */
+declare const optional: <A>(s: Schema<A>) => SchemaOptional<A | undefined>;
+declare const optionalNullable: <A>(schema: Schema<NonNullable<A>>) => SchemaOptional<Nullable<A>>;
+declare const optionalMaybe: <A>(schema: Schema<A>) => SchemaOptional<Maybe<A>>;
+/**
+ * When decoding, if the field is absent, then the default will be used.
+ * When encoding, the field is required.
+ */
+declare const optionalDefault: <A>(def: A, schema: Schema<A>) => SchemaOptional<A>;
+declare function object<A>(def: SchemaDef<A>): Schema<A>;
+declare const pair: <L, R>(l: Schema<L>, r: Schema<R>) => Schema<[L, R]>;
+declare const triple: <A, B, C>(a: Schema<A>, b: Schema<B>, c: Schema<C>) => Schema<[A, B, C]>;
+declare const map: <A>(s: Schema<A>) => Schema<Map<string, A>>;
+declare const maybe: <A>(s: Schema<A>) => Schema<Maybe<A>>;
+declare const result: <E, T>(error: Schema<E>, success: Schema<T>) => Schema<Result<E, T>>;
+declare const nullable: <A>(s: Schema<A>) => Schema<Nullable<A>>;
+declare const stringLiteral: <T extends string>(str: T) => Schema<T>;
+declare const stringEnum: <const T extends string[]>(strs: T) => Schema<T[number]>;
+declare const oneOf: <V>(f: (v: V) => Schema<V>, ss: Array<Schema<V>>) => Schema<V>;
+declare const discriminatedUnion: <const Variants extends readonly Variant<any>[]>(vars: Variants) => Schema<Infer<Variants[number]["schema"]>>;
+/**
+ * One option in a sum type.
+ * Includes the pattern that differentiates it from the other options in the type.
+ */
+declare class Variant<T> {
+    readonly pattern: Record<string, string>;
+    readonly schema: Schema<T>;
+    constructor(pattern: Record<string, string>, schema: Schema<T>);
+}
+type VariantDef<T extends string, A> = {
+    [D in keyof A]: Schema<A[D]> | SchemaOptional<A[D]> | (A[D] & T);
+};
+declare const variant: <const T extends string, const A>(def: VariantDef<T, A>) => Variant<A>;
+/** Schema for a stringified JSON representation. */
+declare const stringified: <T>(inner: Schema<T>) => Schema<T>;
+declare const recursive: <T>(f: (s: Schema<T>) => Schema<T>) => Schema<T>;
+export { Schema, type Infer, type SchemaDef, type SchemaOptional, type Variant, object, pair, triple, map, boolean, number, string, array, json, both, maybe, result, nullable, optional, optionalNullable, optionalMaybe, optionalDefault, stringLiteral, stringEnum, stringified, oneOf, discriminatedUnion, variant, from, decode, encode, decoder, encoder, recursive, };

package/dist/json/schema.js

@@ -0,0 +1,168 @@
+import * as decoder from "./decoder";
+import * as encoder from "./encoder";
+import { Success, Failure } from "../result";
+import { Encoder } from "./encoder";
+import { filterMap, mapValues } from "../helpers/object";
+/**
+ * A `Schema<A>` contains information to encode and decode a value.
+ *
+ * This allows us to have safe conversion to and from JSON.
+ */
+class Schema {
+    decoder;
+    encoder;
+    constructor(decoder, encoder) {
+        this.decoder = decoder;
+        this.encoder = encoder;
+    }
+    dimap(p, s) {
+        return new Schema(this.decoder.map(p), this.encoder.rmap(s));
+    }
+    chain(p, s) {
+        return new Schema(this.decoder.chain(p), this.encoder.rmap(s));
+    }
+}
+function decode(schema, input) {
+    return decoder.decode(input, schema.decoder);
+}
+function encode(schema, input) {
+    return schema.encoder.run(input);
+}
+/** Create a Schema. */
+function from(decoder, encoder) {
+    return new Schema(decoder, encoder);
+}
+const json = new Schema(decoder.json, encoder.json);
+const boolean = new Schema(decoder.boolean, encoder.boolean);
+const number = new Schema(decoder.number, encoder.number);
+const string = new Schema(decoder.string, encoder.string);
+const array = (schema) => new Schema(decoder.array(schema.decoder), encoder.array(schema.encoder));
+const both = (left, right) => new Schema(decoder.both(left.decoder, right.decoder), encoder.both(left.encoder, right.encoder));
+/** Schema for an object field that may not be present. */
+class SchemaOptional {
+    decoder;
+    encoder;
+    constructor(decoder, encoder) {
+        this.decoder = decoder;
+        this.encoder = encoder;
+    }
+    dimap(p, s) {
+        return new SchemaOptional(this.decoder.map(p), this.encoder.rmap(s));
+    }
+}
+/** An object field that may be absent. */
+const optional = (s) => new SchemaOptional(decoder.optional(s.decoder), encoder.optional(s.encoder));
+const optionalNullable = (schema) => new SchemaOptional(decoder.optionalNullable(schema.decoder), encoder.optionalNullable(schema.encoder));
+const optionalMaybe = (schema) => new SchemaOptional(decoder.optionalMaybe(schema.decoder), encoder.optionalMaybe(schema.encoder));
+/**
+ * When decoding, if the field is absent, then the default will be used.
+ * When encoding, the field is required.
+ */
+const optionalDefault = (def, schema) => new SchemaOptional(decoder.optionalDefault(def, schema.decoder), encoder.optional(schema.encoder));
+function object(def) {
+    const pdef = {};
+    const sdef = {};
+    for (const key in def) {
+        const schema = def[key];
+        pdef[key] = schema.decoder;
+        sdef[key] = schema.encoder;
+    }
+    return new Schema(decoder.object(pdef), encoder.object(sdef));
+}
+const pair = (l, r) => new Schema(decoder.pair(l.decoder, r.decoder), encoder.pair(l.encoder, r.encoder));
+const triple = (a, b, c) => new Schema(decoder.triple(a.decoder, b.decoder, c.decoder), encoder.triple(a.encoder, b.encoder, c.encoder));
+const map = (s) => array(pair(string, s)).dimap(xs => xs.reduce((acc, [k, v]) => acc.set(k, v), new Map()), m => Array.from(m.entries()));
+const maybe = (s) => new Schema(decoder.maybe(s.decoder), encoder.maybe(s.encoder));
+const result = (error, success) => discriminatedUnion([
+    variant({
+        type: "Success",
+        value: success,
+    }),
+    variant({
+        type: "Failure",
+        error,
+    }),
+]).dimap(v => {
+    switch (v.type) {
+        case "Success":
+            return Success(v.value);
+        case "Failure":
+            return Failure(v.error);
+        default:
+            return v;
+    }
+}, r => r.either(error => ({ type: "Failure", error }), value => ({ type: "Success", value })));
+const nullable = (s) => new Schema(decoder.nullable(s.decoder), encoder.nullable(s.encoder));
+const stringLiteral = (str) => new Schema(decoder.stringLiteral(str), encoder.string.rmap(input => {
+    if (input != str) {
+        throw new Error(`Cannot encode '${input}'. Expected literal '${str}'"`);
+    }
+    return input;
+}));
+const stringEnum = (strs) => new Schema(decoder.stringEnum(strs), encoder.stringEnum(strs));
+const oneOf = (f, ss) => new Schema(decoder.oneOf(ss.map(s => s.decoder)), encoder.oneOf(v => f(v).encoder));
+const discriminatedUnion = (vars) => {
+    const d = decoder.oneOf(vars.map(v => v.schema.decoder));
+    const e = encoder.oneOf(v => {
+        const found = vars.find(variant => matches(variant.pattern, v));
+        if (found == undefined) {
+            throw new Error(`Invalid discriminant in union type: '${v}'`);
+        }
+        return found.schema.encoder;
+    });
+    return new Schema(d, e);
+};
+/** Check whether a value matches a pattern. */
+const matches = (pattern, val) => {
+    if (typeof val !== "object" || val === null) {
+        return false;
+    }
+    for (const key in pattern) {
+        if (!(key in val)) {
+            return false;
+        }
+        if (pattern[key] != undefined && pattern[key] !== val[key]) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * One option in a sum type.
+ * Includes the pattern that differentiates it from the other options in the type.
+ */
+class Variant {
+    pattern;
+    schema;
+    constructor(pattern, schema) {
+        this.pattern = pattern;
+        this.schema = schema;
+    }
+}
+const variant = (def) => {
+    const pattern = filterMap(def, (_, v) => (typeof v == "string" ? v : undefined));
+    if (Object.keys(pattern).length == 0) {
+        throw new Error("Invalid variant definition. No discriminant identified. Discriminant must be provided as a string");
+    }
+    const schemaDef = mapValues(def, (_, value) => 
+    // @ts-expect-error hard to prove the types, but this is correct.
+    typeof value == "string" ? stringLiteral(value) : value);
+    const schema = object(schemaDef);
+    return new Variant(pattern, schema);
+};
+/** Schema for a stringified JSON representation. */
+const stringified = (inner) => new Schema(decoder.stringified(inner.decoder), encoder.stringified(inner.encoder));
+const recursive = (f) => {
+    const baseEncoder = new Encoder(_ => {
+        throw new Error("A recursive encoder cannot immediately call itself.");
+    });
+    const baseDecoder = decoder.fail("A recursive decoder cannot immediately call itself.");
+    const base = new Schema(baseDecoder, baseEncoder);
+    const top = f(base);
+    // @ts-expect-error assigning to read-only prop
+    base.encoder.run = top.encoder.run;
+    // @ts-expect-error assigning to read-only prop
+    base.decoder.run = top.decoder.run;
+    return top;
+};
+export { Schema, object, pair, triple, map, boolean, number, string, array, json, both, maybe, result, nullable, optional, optionalNullable, optionalMaybe, optionalDefault, stringLiteral, stringEnum, stringified, oneOf, discriminatedUnion, variant, from, decode, encode, decoder, encoder, recursive, };

package/dist/json/types.d.ts

@@ -0,0 +1,6 @@
+export { type Json, type JsonObject, type JsonArray };
+type Json = null | string | number | boolean | JsonArray | JsonObject;
+type JsonObject = {
+    [x: string]: Json;
+};
+type JsonArray = Array<Json>;

package/dist/json/types.js

@@ -0,0 +1 @@
+export {};

package/dist/list.d.ts

@@ -0,0 +1,35 @@
+import { Maybe } from "./maybe";
+type Content<T> = {
+    head: T;
+    tail: List<T>;
+} | {
+    empty: null;
+};
+/**
+ * An immutable singly-linked list with cheap prepending (`cons`) and
+ * iteration. Empty lists share a common representation; otherwise, each
+ * node holds a `head` and a reference to the next list.
+ */
+declare class List<T> {
+    readonly value: Content<T>;
+    static empty<T>(): List<T>;
+    static cons<T>(head: T, tail: List<T>): List<T>;
+    static singleton<T>(v: T): List<T>;
+    static concat<T>(x: List<T>, y: List<T>): List<T>;
+    static from<T>(array: Array<T>): List<T>;
+    private constructor();
+    isEmpty(): boolean;
+    head(): Maybe<T>;
+    tail(): List<T>;
+    length(): number;
+    map<W>(f: (v: T) => W): List<W>;
+    reduce<U>(init: U, f: (acc: U, elem: T) => U): U;
+    find(predicate: (elem: T) => boolean): Maybe<T>;
+    contains(elem: T): boolean;
+    filter(predicate: (v: T) => boolean): List<T>;
+    reverse(): List<T>;
+    append(item: T): List<T>;
+    toArray(): Array<T>;
+    [Symbol.iterator](): IterableIterator<T>;
+}
+export { List };

package/dist/list.js

@@ -0,0 +1,130 @@
+import { Just, Nothing } from "./maybe";
+/**
+ * An immutable singly-linked list with cheap prepending (`cons`) and
+ * iteration. Empty lists share a common representation; otherwise, each
+ * node holds a `head` and a reference to the next list.
+ */
+class List {
+    value;
+    static empty() {
+        return new List({ empty: null });
+    }
+    static cons(head, tail) {
+        return new List({ head, tail });
+    }
+    static singleton(v) {
+        return List.cons(v, List.empty());
+    }
+    static concat(x, y) {
+        let r = y;
+        for (const el of x.reverse()) {
+            r = List.cons(el, r);
+        }
+        return r;
+    }
+    static from(array) {
+        let result = List.empty();
+        for (let i = array.length - 1; i >= 0; i--) {
+            result = List.cons(array[i], result);
+        }
+        return result;
+    }
+    constructor(v) {
+        this.value = v;
+    }
+    isEmpty() {
+        switch (true) {
+            case "empty" in this.value:
+                return true;
+            case "head" in this.value:
+                return false;
+            default:
+                return this.value;
+        }
+    }
+    head() {
+        switch (true) {
+            case "empty" in this.value:
+                return Nothing();
+            case "head" in this.value:
+                return Just(this.value.head);
+            default:
+                return this.value;
+        }
+    }
+    tail() {
+        switch (true) {
+            case "empty" in this.value:
+                return List.empty();
+            case "head" in this.value:
+                return this.value.tail;
+            default:
+                return this.value;
+        }
+    }
+    length() {
+        let len = 0;
+        for (const _ of this) {
+            len++;
+        }
+        return len;
+    }
+    map(f) {
+        let r = List.empty();
+        for (const item of this.reverse()) {
+            r = List.cons(f(item), r);
+        }
+        return r;
+    }
+    reduce(init, f) {
+        let acc = init;
+        for (const item of this) {
+            acc = f(acc, item);
+        }
+        return acc;
+    }
+    find(predicate) {
+        for (const item of this) {
+            if (predicate(item))
+                return Just(item);
+        }
+        return Nothing();
+    }
+    contains(elem) {
+        return this.find(x => x === elem).isJust();
+    }
+    filter(predicate) {
+        let result = List.empty();
+        for (const item of this.reverse()) {
+            if (predicate(item)) {
+                result = List.cons(item, result);
+            }
+        }
+        return result;
+    }
+    reverse() {
+        let r = List.empty();
+        for (const item of this) {
+            r = List.cons(item, r);
+        }
+        return r;
+    }
+    append(item) {
+        return List.concat(this, List.singleton(item));
+    }
+    toArray() {
+        const result = [];
+        for (const item of this) {
+            result.push(item);
+        }
+        return result;
+    }
+    *[Symbol.iterator]() {
+        let list = this;
+        while ("head" in list.value) {
+            yield list.value.head;
+            list = list.value.tail;
+        }
+    }
+}
+export { List };