functionalscript 0.13.0 → 0.14.0

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

@@ -0,0 +1,113 @@
+import {} from "../module.f.js";
+import { ok } from "../../result/module.f.js";
+import { constPrimitiveValidate, prependPath, primitive0Validate, verror, } from "../validate/module.f.js";
+import { isArray as commonIsArray } from "../../array/module.f.js";
+import { isObject as commonIsObject } from "../../object/module.f.js";
+import { find, map as listMap } from "../../list/module.f.js";
+const indexedFirstError = (results) => {
+    // TODO: findIndex breaks type inference,
+    //       we should replace it with something else.
+    const i = results.findIndex(r => r[0] === 'error');
+    return i < 0 ? null : [i, results[i]];
+};
+const keyedFirstError = (results) => {
+    const e = results.find(([, r]) => r[0] === 'error');
+    return e === undefined ? null : [e[0], e[1]];
+};
+const arrayParse = (item) => value => {
+    if (!commonIsArray(value)) {
+        return verror('unexpected value');
+    }
+    if (value.length === 0) {
+        return ok([]);
+    }
+    // Note: we shouldn't instantiate `itemParse` until we know the array is non-empty.
+    //       Otherwise, we can get infinite recursion on empty arrays for recursive schemas.
+    const itemParse = parse(item);
+    const results = value.map(itemParse);
+    const err = indexedFirstError(results);
+    return (err === null
+        ? ok(results.map(r => r[1]))
+        : prependPath(String(err[0]), err[1]));
+};
+const recordParse = (item) => value => {
+    if (!commonIsObject(value)) {
+        return verror('unexpected value');
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        return ok({});
+    }
+    const itemParse = parse(item);
+    const results = entries.map(([k, v]) => [k, itemParse(v)]);
+    const err = keyedFirstError(results);
+    return (err === null
+        ? ok(Object.fromEntries(results.map(([k, r]) => [k, r[1]])))
+        : prependPath(err[0], err[1]));
+};
+const tupleParse = (rtti) => value => {
+    if (!commonIsArray(value)) {
+        return verror('unexpected value');
+    }
+    const results = rtti.map((t, i) => parse(t)(value[i]));
+    const err = indexedFirstError(results);
+    return (err === null
+        ? ok(results.map(r => r[1]))
+        : prependPath(String(err[0]), err[1]));
+};
+const structParse = (rtti) => value => {
+    if (!commonIsObject(value)) {
+        return verror('unexpected value');
+    }
+    const results = Object.entries(rtti).map(([k, t]) => [k, parse(t)(value[k])]);
+    const err = keyedFirstError(results);
+    return (err === null
+        ? ok(Object.fromEntries(results.map(([k, r]) => [k, r[1]])))
+        : prependPath(err[0], err[1]));
+};
+const constObjectParse = (rtti) => commonIsArray(rtti)
+    ? tupleParse(rtti)
+    : structParse(rtti);
+const constParse = (rtti) => typeof rtti === 'object' && rtti !== null
+    ? constObjectParse(rtti)
+    : constPrimitiveValidate(rtti);
+const findFirst = find(verror('no match'))((k) => k[0] === 'ok');
+const orParse = (rtti) => value => findFirst(listMap(t => parse(t)(value))(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 }]
+ * ```
+ */
+export const parse = (rtti) => {
+    if (typeof rtti === 'function') {
+        const [tag, ...value] = rtti();
+        switch (tag) {
+            case 'const': return constParse(value[0]);
+            case 'array': return arrayParse(value[0]);
+            case 'record': return recordParse(value[0]);
+            case 'unknown': return ok;
+            case 'or': return orParse(value);
+        }
+        return primitive0Validate(tag);
+    }
+    return constParse(rtti);
+};

package/fs/types/rtti/parse/test.f.d.ts

@@ -0,0 +1,104 @@
+declare const _default: {
+    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;
+        };
+        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;
+    };
+};
+export default _default;

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

@@ -0,0 +1,316 @@
+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)),
+        },
+        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/validate/module.f.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 strict equality (`===`). */
+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>;