functionalscript 0.43.1 → 0.44.0

package/fjs/types/rtti/parse/module.f.js

@@ -1,114 +0,0 @@
-/**
- * Runtime deserialization of unknown values against RTTI schemas.
- *
- * The main entry point is `parse(rtti)`, which takes a schema `Type` and returns
- * a `Parse<T>` function. When called with an unknown value, it returns a `Result`
- * that is either `['ok', newValue]` or `['error', { path, message }]`.
- *
- * Unlike `validate`, which checks an existing value in-place and returns it
- * unchanged on success, `parse` always returns a freshly constructed value that
- * contains only the fields/elements declared by the schema. This makes both
- * structs and tuples effectively closed at runtime, matching the TypeScript
- * type produced by `Ts<T>`:
- *
- * - Tuples: the result has exactly the schema's length; extra elements are dropped.
- * - Structs: the result contains only the schema's keys; extra properties are dropped.
- * - Arrays/records: every element/value is itself parsed, so a fresh container is
- *   always returned even if the inner type is a primitive.
- *
- * This also provides forward compatibility with extended serialization formats:
- * a schema-based parser keeps working when newer versions of the format add
- * extra fields or tuple elements.
- *
- * The error shape, path bookkeeping, primitive checks, and schema
- * recognition (`visit`) are shared with `validate` through
- * `../common/module.f.ts`; only container construction differs.
- *
- * @module
- */
-import {} from '../module.f.js';
-import { ok } from '../../result/module.f.js';
-import { reverse, toArray } from '../../list/module.f.js';
-import { constPrimitiveValidate, eachEntry, isArray, isObject, orVisit, primitive0Validate, verror, visit, } from '../common/module.f.js';
-export {} from '../common/module.f.js';
-const { entries } = Object;
-const arrayRebuild = entries => entries.map(([, v]) => v);
-const recordRebuild = entries => Object.fromEntries(entries);
-/** `eachEntry`'s accumulator seed: entries are consed on in reverse as they parse. */
-const emptyEntries = null;
-/** `eachEntry`'s accumulate step: an O(1) prepend, unlike rebuilding an array on every entry. */
-const consEntry = (acc, k, v) => ({ first: [k, v], tail: acc });
-/** Restores forward order from `consEntry`'s reverse-order list, in one linear pass. */
-const orderedEntries = (list) => toArray(reverse(list));
-/**
- * Builds a parser for `array` or `record` schemas. Mirrors `validate`'s
- * `containerValidate`, but rebuilds a fresh container from each item's parsed
- * result instead of returning the value unchanged. The inner item parser is
- * instantiated lazily (only when the container is non-empty) so recursive
- * schemas don't recurse forever on empty containers.
- */
-const containerParse = (isContainer, rebuild) => (item) => value => {
-    if (!isContainer(value)) {
-        return verror('unexpected value');
-    }
-    const e = entries(value);
-    if (e.length === 0) {
-        return ok(rebuild([]));
-    }
-    const itemParse = parse(item);
-    const r = eachEntry(e, (_k, v) => itemParse(v), emptyEntries, consEntry);
-    return r[0] === 'error' ? r : ok(rebuild(orderedEntries(r[1])));
-};
-const arrayParse = containerParse(isArray, arrayRebuild);
-const recordParse = containerParse(isObject, recordRebuild);
-/**
- * Builds a parser for `Tuple` or `Struct` const schemas. Mirrors `validate`'s
- * `constContainerValidate`: it iterates the schema's entries (so extra tuple
- * elements and undeclared struct keys are dropped) and rebuilds the result
- * from each parsed item.
- */
-const constContainerParse = (isContainer, getItem, rebuild) => (rtti) => value => {
-    if (!isContainer(value)) {
-        return verror('unexpected value');
-    }
-    const r = eachEntry(entries(rtti), (k, t) => parse(t)(getItem(value, k)), emptyEntries, consEntry);
-    return r[0] === 'error' ? r : ok(rebuild(orderedEntries(r[1])));
-};
-const tupleParse = constContainerParse(isArray, (value, k) => value[Number(k)], arrayRebuild);
-const structParse = constContainerParse(isObject, (value, k) => value[k], recordRebuild);
-const orParse = (rtti) => orVisit(parse)(rtti);
-/**
- * Creates a parser function for the given RTTI schema.
- *
- * The returned function takes an unknown value and returns either
- * `['ok', newValue]` containing a freshly constructed value matching the schema,
- * or `['error', { path, message }]` describing the failure location.
- *
- * @param rtti - A schema `Type`: a `Thunk` for tag-based schemas, or a `Const`
- *   (primitive literal, tuple, or struct) for exact-value schemas.
- * @returns A `Parse<T>` function.
- *
- * @example
- * ```ts
- * const p = parse(array(number))
- * p([1, 2, 3])         // ['ok', [1, 2, 3]]   (a new array)
- * p([1, 'two'])        // ['error', { path: ['1'], message: 'unexpected value' }]
- *
- * // tuples are closed: extra elements are dropped
- * parse([number, number] as const)([1, 2, 3]) // ['ok', [1, 2]]
- *
- * // structs drop undeclared keys
- * parse({ a: number } as const)({ a: 1, b: 2 }) // ['ok', { a: 1 }]
- * ```
- */
-const parseVisitor = {
-    tuple: tupleParse,
-    struct: structParse,
-    array: arrayParse,
-    record: recordParse,
-    or: orParse,
-    constPrimitive: constPrimitiveValidate,
-    primitive0: primitive0Validate,
-    unknown: () => ok,
-};
-export const parse = (rtti) => visit(parseVisitor)(rtti);

package/fjs/types/rtti/parse/proof.f.d.ts

@@ -1,115 +0,0 @@
-export declare const proof: {
-    boolean: {
-        ok: () => void;
-        error: () => void;
-    };
-    number: {
-        ok: () => void;
-        error: () => void;
-    };
-    string: {
-        ok: () => void;
-        error: () => void;
-    };
-    bigint: {
-        ok: () => void;
-        error: () => void;
-    };
-    unknown: {
-        ok: () => void;
-    };
-    const: {
-        null: {
-            ok: () => void;
-            error: () => void;
-        };
-        undefined: {
-            ok: () => void;
-            error: () => void;
-        };
-        number: {
-            ok: () => void;
-            error: () => void;
-        };
-        nan: {
-            ok: () => void;
-            error: () => void;
-        };
-        infinity: {
-            ok: () => void;
-            error: () => void;
-        };
-        signedZero: {
-            distinct: () => void;
-            self: () => void;
-        };
-        string: {
-            ok: () => void;
-            error: () => void;
-        };
-        bigint: {
-            ok: () => void;
-            error: () => void;
-        };
-        boolean: {
-            ok: () => void;
-            error: () => void;
-        };
-        tuple: {
-            ok: () => void;
-            extraItemsDropped: () => void;
-            error: () => void;
-        };
-        struct: {
-            ok: () => void;
-            extraKeysDropped: () => void;
-            error: () => void;
-        };
-    };
-    array: {
-        empty: () => void;
-        ok: () => void;
-        freshArray: () => void;
-        error: () => void;
-        nested: () => void;
-    };
-    record: {
-        empty: () => void;
-        ok: () => void;
-        freshRecord: () => void;
-        error: () => void;
-    };
-    constThunk: {
-        primitive: () => void;
-    };
-    or: {
-        consts: {
-            ok: () => void;
-            error: () => void;
-        };
-        thunks: {
-            ok: () => void;
-            error: () => void;
-        };
-        firstMatchWins: () => void;
-    };
-    option: {
-        ok: () => void;
-        error: () => void;
-    };
-    path: {
-        rootMismatch: () => void;
-        arrayIndex: () => void;
-        recordKey: () => void;
-        nestedArray: () => void;
-        tupleIndex: () => void;
-        structKey: () => void;
-        deepStruct: () => void;
-        recursiveSchema: () => void;
-        orRoot: () => void;
-    };
-    recursive: {
-        arrayOfArrays: () => void;
-        recordOfRecords: () => void;
-    };
-};

package/fjs/types/rtti/parse/proof.f.js

@@ -1,334 +0,0 @@
-import { parse } from './module.f.js';
-import { boolean, number, string, bigint, unknown, array, record, or, option } from '../module.f.js';
-import { assert, assertEq } from '../../../asserts/module.f.js';
-const assertOk = ([k]) => { assertEq(k, 'ok', 'expected ok'); };
-const assertError = ([k]) => { assertEq(k, 'error', 'expected error'); };
-const unwrap = (r) => {
-    assert(r[0] === 'ok', 'expected ok');
-    return r[1];
-};
-const assertErrorPath = (expected) => (r) => {
-    assert(r[0] === 'error', 'expected error');
-    const e = r[1];
-    if (e.path.length !== expected.length) {
-        throw `path length ${e.path.length} != ${expected.length}`;
-    }
-    for (let i = 0; i < expected.length; i++) {
-        if (e.path[i] !== expected[i]) {
-            throw `path[${i}] ${e.path[i]} != ${expected[i]}`;
-        }
-    }
-};
-const assertDeepEqual = (a, b) => {
-    if (a === b) {
-        return;
-    }
-    if (a instanceof Array && b instanceof Array) {
-        if (a.length !== b.length) {
-            throw `array length ${a.length} != ${b.length}`;
-        }
-        for (let i = 0; i < a.length; i++) {
-            assertDeepEqual(a[i], b[i]);
-        }
-        return;
-    }
-    if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
-        const ka = Object.keys(a).sort();
-        const kb = Object.keys(b).sort();
-        if (ka.length !== kb.length) {
-            throw `key count ${ka.length} != ${kb.length}`;
-        }
-        for (let i = 0; i < ka.length; i++) {
-            if (ka[i] !== kb[i]) {
-                throw `key ${ka[i]} != ${kb[i]}`;
-            }
-            assertDeepEqual(a[ka[i]], b[kb[i]]);
-        }
-        return;
-    }
-    throw `not deep-equal: ${String(a)} vs ${String(b)}`;
-};
-export const proof = {
-    boolean: {
-        ok: () => {
-            assertOk(parse(boolean)(true));
-            assertOk(parse(boolean)(false));
-        },
-        error: () => {
-            assertError(parse(boolean)(0));
-            assertError(parse(boolean)('true'));
-            assertError(parse(boolean)(null));
-        },
-    },
-    number: {
-        ok: () => {
-            assertOk(parse(number)(42));
-        },
-        error: () => {
-            assertError(parse(number)('42'));
-            assertError(parse(number)(42n));
-        },
-    },
-    string: {
-        ok: () => {
-            assertOk(parse(string)('hello'));
-        },
-        error: () => {
-            assertError(parse(string)(42));
-            assertError(parse(string)(null));
-        },
-    },
-    bigint: {
-        ok: () => {
-            assertOk(parse(bigint)(4n));
-        },
-        error: () => {
-            assertError(parse(bigint)(4));
-            assertError(parse(bigint)('4'));
-        },
-    },
-    unknown: {
-        ok: () => {
-            assertOk(parse(unknown)(null));
-            assertOk(parse(unknown)(42));
-            assertOk(parse(unknown)('hello'));
-            assertOk(parse(unknown)(true));
-            assertOk(parse(unknown)({}));
-            assertOk(parse(unknown)([]));
-        },
-    },
-    const: {
-        null: {
-            ok: () => assertOk(parse(null)(null)),
-            error: () => {
-                assertError(parse(null)(undefined));
-                assertError(parse(null)(0));
-            },
-        },
-        undefined: {
-            ok: () => assertOk(parse(undefined)(undefined)),
-            error: () => assertError(parse(undefined)(null)),
-        },
-        number: {
-            ok: () => assertOk(parse(42)(42)),
-            error: () => assertError(parse(42)(43)),
-        },
-        nan: {
-            ok: () => assertOk(parse(NaN)(NaN)),
-            error: () => {
-                assertError(parse(NaN)(0));
-                assertError(parse(0)(NaN));
-                assertError(parse(42)(NaN));
-            },
-        },
-        infinity: {
-            ok: () => {
-                assertOk(parse(Infinity)(Infinity));
-                assertOk(parse(-Infinity)(-Infinity));
-            },
-            error: () => {
-                assertError(parse(Infinity)(-Infinity));
-                assertError(parse(Infinity)(0));
-            },
-        },
-        signedZero: {
-            // `Object.is` distinguishes +0 and -0; `===` treats them equal.
-            distinct: () => {
-                assertError(parse(0)(-0));
-                assertError(parse(-0)(0));
-            },
-            self: () => {
-                assertOk(parse(0)(0));
-                assertOk(parse(-0)(-0));
-            },
-        },
-        string: {
-            ok: () => assertOk(parse('hello')('hello')),
-            error: () => assertError(parse('hello')('world')),
-        },
-        bigint: {
-            ok: () => assertOk(parse(7n)(7n)),
-            error: () => assertError(parse(7n)(8n)),
-        },
-        boolean: {
-            ok: () => assertOk(parse(true)(true)),
-            error: () => assertError(parse(true)(false)),
-        },
-        tuple: {
-            ok: () => {
-                const t = [42, 'hello'];
-                const r = parse(t)([42, 'hello']);
-                assertDeepEqual(unwrap(r), [42, 'hello']);
-            },
-            // The key behavior change vs `validate`: extra tuple elements are dropped.
-            extraItemsDropped: () => {
-                const r = parse([42])([42, 'extra']);
-                assertDeepEqual(unwrap(r), [42]);
-            },
-            error: () => {
-                assertError(parse([42])([99]));
-                assertError(parse([42])({}));
-            },
-        },
-        struct: {
-            ok: () => {
-                const t = { a: 42, b: 'hello' };
-                const r = parse(t)({ a: 42, b: 'hello' });
-                assertDeepEqual(unwrap(r), { a: 42, b: 'hello' });
-            },
-            // Undeclared properties are dropped from the constructed value.
-            extraKeysDropped: () => {
-                const r = parse({ a: 42 })({ a: 42, b: 'extra' });
-                assertDeepEqual(unwrap(r), { a: 42 });
-            },
-            error: () => {
-                assertError(parse({ a: 42 })({ a: 99 }));
-                assertError(parse({ a: 42 })([]));
-            },
-        },
-    },
-    array: {
-        empty: () => {
-            const r = parse(array(number))([]);
-            assertDeepEqual(unwrap(r), []);
-        },
-        ok: () => {
-            const r = parse(array(number))([1, 2, 3]);
-            assertDeepEqual(unwrap(r), [1, 2, 3]);
-        },
-        // `parse` always constructs a new array, even when the inner type is a primitive.
-        freshArray: () => {
-            const input = [1, 2, 3];
-            const out = unwrap(parse(array(number))(input));
-            assert(out !== input, 'expected a fresh array');
-            assertDeepEqual(out, [1, 2, 3]);
-        },
-        error: () => {
-            assertError(parse(array(number))([1, 'two', 3]));
-            assertError(parse(array(number))({}));
-            assertError(parse(array(number))(null));
-        },
-        nested: () => {
-            const r = parse(array(array(boolean)))([[true, false], [false]]);
-            assertDeepEqual(unwrap(r), [[true, false], [false]]);
-            assertError(parse(array(array(boolean)))([[true, 42]]));
-        },
-    },
-    record: {
-        empty: () => {
-            const r = parse(record(number))({});
-            assertDeepEqual(unwrap(r), {});
-        },
-        ok: () => {
-            const r = parse(record(string))({ a: 'hello', b: 'world' });
-            assertDeepEqual(unwrap(r), { a: 'hello', b: 'world' });
-        },
-        // `parse` always constructs a new record.
-        freshRecord: () => {
-            const input = { a: 1, b: 2 };
-            const out = unwrap(parse(record(number))(input));
-            assert(out !== input, 'expected a fresh record');
-            assertDeepEqual(out, { a: 1, b: 2 });
-        },
-        error: () => {
-            assertError(parse(record(number))({ a: 1, b: 'two' }));
-            assertError(parse(record(number))(null));
-            assertError(parse(record(number))([]));
-        },
-    },
-    constThunk: {
-        primitive: () => {
-            const t = () => ['const', 7n];
-            assertOk(parse(t)(7n));
-            assertError(parse(t)(8n));
-        },
-    },
-    or: {
-        consts: {
-            ok: () => {
-                const t = or(...[false, 42, 'hello']);
-                assertOk(parse(t)(false));
-                assertOk(parse(t)(42));
-                assertOk(parse(t)('hello'));
-            },
-            error: () => {
-                const t = or(...[false, 42, 'hello']);
-                assertError(parse(t)(true));
-                assertError(parse(t)(43));
-                assertError(parse(t)('world'));
-                assertError(parse(t)(null));
-            },
-        },
-        thunks: {
-            ok: () => {
-                const t = or(number, string);
-                assertOk(parse(t)(42));
-                assertOk(parse(t)('hello'));
-            },
-            error: () => {
-                const t = or(number, string);
-                assertError(parse(t)(true));
-                assertError(parse(t)(null));
-            },
-        },
-        // First matching variant wins; the freshly-constructed value comes from that variant.
-        firstMatchWins: () => {
-            const t = or([number], array(number));
-            const out = unwrap(parse(t)([1, 2, 3]));
-            // The const tuple `[number]` matches first and returns a length-1 result.
-            assertDeepEqual(out, [1]);
-        },
-    },
-    option: {
-        ok: () => {
-            const t = option(number);
-            assertOk(parse(t)(42));
-            assertOk(parse(t)(undefined));
-        },
-        error: () => {
-            const t = option(number);
-            assertError(parse(t)(null));
-            assertError(parse(t)('42'));
-        },
-    },
-    path: {
-        rootMismatch: () => assertErrorPath([])(parse(number)('not a number')),
-        arrayIndex: () => assertErrorPath(['1'])(parse(array(number))([1, 'two', 3])),
-        recordKey: () => {
-            const r = parse(record(number))({ a: 1, b: 'two', c: 3 });
-            assertErrorPath(['b'])(r);
-        },
-        nestedArray: () => assertErrorPath(['0', '1'])(parse(array(array(number)))([[1, 'x'], [2, 3]])),
-        tupleIndex: () => assertErrorPath(['1'])(parse([number, number])([1, 'two'])),
-        structKey: () => assertErrorPath(['b'])(parse({ a: number, b: number })({ a: 1, b: 'two' })),
-        deepStruct: () => {
-            const schema = { user: { name: string, age: number } };
-            const r = parse(schema)({ user: { name: 'A', age: 'old' } });
-            assertErrorPath(['user', 'age'])(r);
-        },
-        recursiveSchema: () => {
-            const list = () => ['array', list];
-            const r = parse(list)([[[42]]]);
-            assertErrorPath(['0', '0', '0'])(r);
-        },
-        orRoot: () => assertErrorPath([])(parse(or(number, string))(true)),
-    },
-    recursive: {
-        arrayOfArrays: () => {
-            const list = () => ['array', list];
-            const v = parse(list);
-            assertOk(v([]));
-            assertOk(v([[], []]));
-            assertOk(v([[[], []], []]));
-            assertError(v([42]));
-            assertError(v(null));
-        },
-        recordOfRecords: () => {
-            const tree = () => ['record', tree];
-            const v = parse(tree);
-            assertOk(v({}));
-            assertOk(v({ a: {}, b: { c: {} } }));
-            assertError(v({ a: 42 }));
-        },
-    },
-};

package/fjs/types/rtti/proof.f.d.ts

@@ -1,5 +0,0 @@
-export declare const proof: {
-    typeof: {
-        [k: string]: (() => void)[];
-    };
-};

package/fjs/types/rtti/proof.f.js

@@ -1,16 +0,0 @@
-const tests = {
-    undefined: [undefined],
-    boolean: [true, false],
-    string: ['hello'],
-    number: [3],
-    bigint: [4n],
-    object: [null, {}, []],
-    function: [() => undefined]
-};
-export const proof = {
-    typeof: Object.fromEntries(Object.entries(tests).map(([k, a]) => [k, a.map(v => () => {
-            if (typeof v !== k) {
-                throw `typeof ${v} !== ${k}`;
-            }
-        })])),
-};