functionalscript 0.13.1 → 0.14.1

package/fs/types/rtti/parse/test.f.js

@@ -0,0 +1,345 @@
+import { parse } from "./module.f.js";
+import { boolean, number, string, bigint, unknown, array, record, or, option } from "../module.f.js";
+const assertOk = ([k]) => { if (k !== 'ok') {
+    throw 'expected ok';
+} };
+const assertError = ([k]) => { if (k !== 'error') {
+    throw 'expected error';
+} };
+const unwrap = (r) => {
+    if (r[0] !== 'ok') {
+        throw 'expected ok';
+    }
+    return r[1];
+};
+const assertErrorPath = (expected) => (r) => {
+    if (r[0] !== 'error') {
+        throw '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 default {
+    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));
+            if (out === input) {
+                throw '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));
+            if (out === input) {
+                throw '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/fs/types/rtti/test.f.d.ts

@@ -0,0 +1,34 @@
+declare const _default: {
+    typeof: {
+        [k: string]: (() => void)[];
+    };
+    or: {
+        flatten: {
+            shallow: () => void;
+            deep: () => void;
+            manualOrThunk: () => void;
+            selfReferential: () => void;
+        };
+        unknownCollapse: {
+            withConst: () => void;
+            withThunk: () => void;
+            nested: () => void;
+        };
+        dropPrimitiveSubset: {
+            number: () => void;
+            boolean: () => void;
+            string: () => void;
+            bigint: () => void;
+            keepIfThunkAbsent: () => void;
+            mixed: () => void;
+        };
+        dedup: {
+            sameThunkReference: () => void;
+            samePrimitive: () => void;
+            nanCollapses: () => void;
+            signedZeroDistinct: () => void;
+        };
+        emptyStillNever: () => void;
+    };
+};
+export default _default;

package/fs/types/rtti/test.f.js

@@ -0,0 +1,123 @@
+import { boolean, number, string, bigint, unknown, or, never } from "./module.f.js";
+import { assertEq } from "../../dev/module.f.js";
+const tests = {
+    undefined: [undefined],
+    boolean: [true, false],
+    string: ['hello'],
+    number: [3],
+    bigint: [4n],
+    object: [null, {}, []],
+    function: [() => undefined]
+};
+const variantsOf = (t) => {
+    if (typeof t !== 'function') {
+        throw 'expected an or thunk';
+    }
+    const info = t();
+    if (info[0] !== 'or') {
+        throw `expected an or thunk, got ${info[0]}`;
+    }
+    return info.slice(1);
+};
+export default {
+    typeof: Object.fromEntries(Object.entries(tests).map(([k, a]) => [k, a.map(v => () => {
+            if (typeof v !== k) {
+                throw `typeof ${v} !== ${k}`;
+            }
+        })])),
+    or: {
+        flatten: {
+            shallow: () => {
+                const v = variantsOf(or(or(boolean, number), string));
+                assertEq(v.length, 3);
+                assertEq(v[0], boolean);
+                assertEq(v[1], number);
+                assertEq(v[2], string);
+            },
+            deep: () => {
+                assertEq(variantsOf(or(or(or(boolean, number), string), bigint)).length, 4);
+            },
+            manualOrThunk: () => {
+                // Manually-constructed `() => ['or', ...]` thunks should also flatten.
+                const inner = () => ['or', boolean, number];
+                assertEq(variantsOf(or(inner, string)).length, 3);
+            },
+            selfReferential: () => {
+                // A self-referential `or` thunk terminates: it is expanded once,
+                // then kept as-is on the second encounter (via the visited set).
+                const t = (() => ['or', boolean, t]);
+                // expansion: t -> [boolean, t]; t (second) kept as-is; number kept.
+                assertEq(variantsOf(or(t, number)).length, 3);
+            },
+        },
+        unknownCollapse: {
+            withConst: () => {
+                const v = variantsOf(or(unknown, 42));
+                assertEq(v.length, 1);
+                assertEq(v[0], unknown);
+            },
+            withThunk: () => {
+                const v = variantsOf(or(number, unknown, string));
+                assertEq(v.length, 1);
+                assertEq(v[0], unknown);
+            },
+            nested: () => {
+                // nested `or` whose flattening surfaces an `unknown`
+                const v = variantsOf(or(or(boolean, unknown), 42));
+                assertEq(v.length, 1);
+                assertEq(v[0], unknown);
+            },
+        },
+        dropPrimitiveSubset: {
+            number: () => {
+                const v = variantsOf(or(42, number));
+                assertEq(v.length, 1);
+                assertEq(v[0], number);
+            },
+            boolean: () => {
+                const v = variantsOf(or(true, false, boolean));
+                assertEq(v.length, 1);
+                assertEq(v[0], boolean);
+            },
+            string: () => {
+                const v = variantsOf(or('hi', 'bye', string));
+                assertEq(v.length, 1);
+                assertEq(v[0], string);
+            },
+            bigint: () => {
+                const v = variantsOf(or(7n, bigint));
+                assertEq(v.length, 1);
+                assertEq(v[0], bigint);
+            },
+            keepIfThunkAbsent: () => {
+                // Without a matching primitive thunk, consts are kept.
+                assertEq(variantsOf(or(42, 'hello')).length, 2);
+            },
+            mixed: () => {
+                // `null`/`undefined` consts have no matching primitive thunk and remain.
+                assertEq(variantsOf(or(null, undefined, 42, number)).length, 3);
+            },
+        },
+        dedup: {
+            sameThunkReference: () => {
+                assertEq(variantsOf(or(boolean, boolean)).length, 1);
+            },
+            samePrimitive: () => {
+                assertEq(variantsOf(or(42, 42)).length, 1);
+            },
+            nanCollapses: () => {
+                // `Object.is(NaN, NaN)` is true, so duplicate `NaN` variants
+                // collapse — matching `constPrimitiveValidate` semantics.
+                assertEq(variantsOf(or(NaN, NaN)).length, 1);
+            },
+            signedZeroDistinct: () => {
+                // `Object.is(+0, -0)` is false, so they remain distinct.
+                assertEq(variantsOf(or(0, -0)).length, 2);
+            },
+        },
+        emptyStillNever: () => {
+            assertEq(variantsOf(or()).length, 0);
+            assertEq(variantsOf(never).length, 0);
+        },
+    },
+};

package/fs/types/rtti/validate/module.f.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Runtime validation of unknown values against RTTI schemas.
+ *
+ * The main entry point is `validate(rtti)`, which takes a schema `Type` and returns
+ * a `Validate<T>` function. When called with an unknown value, it returns a `Result`
+ * that is either `['ok', typedValue]` or `['error', { path, message }]`.
+ *
+ * ## Error path
+ *
+ * On failure, the error carries a `path` pointing at the offending sub-value:
+ * each step is the string property name (for structs/records) or the stringified
+ * index (for tuples/arrays). The path is empty when the failure is at the root.
+ *
+ * ## Dispatch strategy
+ *
+ * - **`Thunk`** schemas are evaluated lazily: the thunk is called once to obtain an
+ *   `Info` descriptor, then dispatched by tag:
+ *   - `'const'` — delegates to `constValidate`
+ *   - `'unknown'` — always succeeds (any DJS value is valid)
+ *   - `Tag1` (`'array'`, `'record'`) — delegates to `containerValidate`
+ *   - `Tag0` (`'boolean'`, `'number'`, `'string'`, `'bigint'`) — uses `typeof` check
+ *   - `'or'` — tries each variant; reports `'no match'` at the current location if all fail
+ * - **`Const`** schemas (primitives, tuples, structs) validate by exact equality or
+ *   recursive field/element checking.
+ *
+ * ## Recursion safety
+ *
+ * For `array` and `record` schemas, the inner item validator is instantiated lazily —
+ * only after confirming the container is non-empty. This prevents infinite recursion
+ * when validating recursive schemas like `const list = () => ['array', list]`.
+ *
+ * @module
+ */
+import type { Unknown } from '../../../djs/module.f.ts';
+import { type Info0, type Primitive0, type Type } from '../module.f.ts';
+import { type Error, type Result as CommonResult } from '../../result/module.f.ts';
+import type { Ts } from '../ts/module.f.ts';
+import type { Primitive } from '../../../djs/module.f.ts';
+/** A path to a sub-value within the validated structure. Each step is an object key or stringified array index. */
+export type Path = readonly string[];
+/** Detailed validation failure: the offending `path` plus a short `message`. */
+export type ValidationError = {
+    readonly path: Path;
+    readonly message: string;
+};
+/** Validation result: either the typed value or a `ValidationError`. */
+export type Result<T extends Type> = CommonResult<Ts<T>, ValidationError>;
+/** A function that validates an unknown value against schema `T`. */
+export type Validate<T extends Type> = (value: Unknown) => Result<T>;
+/** Builds an error result with empty path and the given message. */
+export declare const verror: (message: string) => Error<ValidationError>;
+/** Prepends `key` to the error's path, used to build the path bottom-up. */
+export declare const prependPath: (key: string, r: Error<ValidationError>) => Error<ValidationError>;
+/** Validates a `Tag0` primitive schema using `typeof`. */
+export declare const primitive0Validate: <K extends Primitive0, T extends Info0<K>>(tag: K) => Validate<T>;
+/**
+ * Validates a primitive `Const` schema using `Object.is` (SameValue).
+ *
+ * `Object.is` is used instead of `===` so that:
+ * - `NaN` const schemas match `NaN` values (`===` would always fail because `NaN !== NaN`).
+ * - `+0` and `-0` are treated as distinct const values.
+ */
+export declare const constPrimitiveValidate: <T extends Primitive>(rtti: T) => Validate<T>;
+/**
+ * Creates a validator function for the given RTTI schema.
+ *
+ * @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 `Validate<T>` function that checks an unknown value and returns
+ *   `['ok', value]` or `['error', { path, message }]`.
+ *
+ * @example
+ * ```ts
+ * const v = validate(array(number))
+ * v([1, 2, 3])         // ['ok', [1, 2, 3]]
+ * v([1, 'two'])        // ['error', { path: ['1'], message: 'unexpected value' }]
+ * v(['a'])             // ['error', { path: ['0'], message: 'unexpected value' }]
+ * ```
+ */
+export declare const validate: <T extends Type>(rtti: T) => Validate<T>;