functionalscript 0.13.1 → 0.14.1

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

@@ -0,0 +1,100 @@
+import { includes } from "../array/module.f.js";
+const primitive0List = ['bigint', 'boolean', 'number', 'string'];
+export const tag0List = [...primitive0List, 'unknown'];
+const type0 = (tag) => () => [tag];
+/** Schema that validates `boolean` values. */
+export const boolean = type0('boolean');
+/** Schema that validates `number` values. */
+export const number = type0('number');
+/** Schema that validates `string` values. */
+export const string = type0('string');
+/** Schema that validates `bigint` values. */
+export const bigint = type0('bigint');
+/** Schema that validates any DJS-compatible value. */
+export const unknown = type0('unknown');
+const tag1List = ['array', 'record'];
+export const isTag1 = includes(tag1List);
+const type1 = (key) => t => () => [key, t];
+/** Constructs a schema that validates `readonly Ts<T>[]`. */
+export const array = type1('array');
+/** Constructs a schema that validates `{ readonly[K in string]: Ts<T> }`. */
+export const record = type1('record');
+/** Reads the tag of a thunk variant, or returns `null` for a `Const`. */
+const variantTag = (t) => typeof t === 'function' ? t()[0] : null;
+const isPrim0 = includes(primitive0List);
+const flattenStep = ([visited, out], t) => {
+    if (typeof t === 'function' && !visited.has(t)) {
+        const nextVisited = new Set([...visited, t]);
+        const info = t();
+        if (info[0] === 'or') {
+            const [v, inner] = info.slice(1)
+                .reduce(flattenStep, [nextVisited, []]);
+            return [v, [...out, ...inner]];
+        }
+        return [nextVisited, [...out, t]];
+    }
+    return [visited, [...out, t]];
+};
+/**
+ * Walks `types` and produces a flat list of `or` variants:
+ *
+ * - Variants whose thunk resolves to `['or', ...]` are inlined.
+ * - Each thunk is resolved at most once; thunks reached a second time are
+ *   kept as-is, so self-referential `or` schemas terminate.
+ */
+const flattenOr = (types) => types.reduce(flattenStep, [new Set(), []])[1];
+const collectStep = ([u, p], t) => {
+    if (u) {
+        return [u, p];
+    }
+    const tag = variantTag(t);
+    if (tag === 'unknown') {
+        return [true, p];
+    }
+    return tag !== null && isPrim0(tag) ? [u, new Set([...p, tag])] : [u, p];
+};
+const dedupStep = ([primThunks, acc], t) => primThunks.has(typeof t) || acc.some(r => Object.is(r, t))
+    ? [primThunks, acc]
+    : [primThunks, [...acc, t]];
+/**
+ * Drops variants that are trivially subsumed by another variant.
+ *
+ * Trivial subset rules handled here:
+ * - any variant ⊆ `unknown` — if `unknown` is present, the entire union is
+ *   `unknown`.
+ * - a primitive const ⊆ its primitive type thunk — `42 ⊆ number`,
+ *   `'hi' ⊆ string`, `true ⊆ boolean`, `7n ⊆ bigint`.
+ *
+ * `Object.is` is used for deduplication, so `NaN` collapses with itself and
+ * `+0` and `-0` stay distinct — matching `constPrimitiveValidate`.
+ *
+ * Full structural subset (tuples/structs/`or`/recursive schemas) is left to
+ * a future change — see goals 1 and 3 of issue 130.
+ */
+const reduceOr = (types) => {
+    const flat = flattenOr(types);
+    const [hasUnknown, primThunks] = flat.reduce(collectStep, [false, new Set()]);
+    return hasUnknown
+        ? [unknown]
+        : flat.reduce(dedupStep, [primThunks, []])[1];
+};
+/**
+ * Constructs a schema that validates a value matching any of the given schemas.
+ *
+ * The resulting `or` is normalized at construction time:
+ * - nested `or` thunks are flattened into the outer union,
+ * - any `unknown` variant collapses the whole union to `unknown`,
+ * - primitive consts subsumed by a matching primitive thunk are dropped
+ *   (e.g. `or(42, number)` → `or(number)`),
+ * - duplicate variants are deduplicated via `Object.is`.
+ *
+ * See `issues/130-or-optimization.md`.
+ */
+export const or = (...types) => {
+    const reduced = reduceOr(types);
+    return (() => ['or', ...reduced]);
+};
+/** Constructs a schema that validates a value matching `T` or `undefined`. */
+export const option = (t) => or(t, undefined);
+/** Schema that never matches any value — the empty union, corresponding to TypeScript's `never`. */
+export const never = or();

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

@@ -0,0 +1,32 @@
+import { type Type } from '../module.f.ts';
+import { type Result as ValidateResult, type Validate } from '../validate/module.f.ts';
+export type { Path, ValidationError } from '../validate/module.f.ts';
+/** Parse result: either the freshly constructed typed value or a `ValidationError`. */
+export type Result<T extends Type> = ValidateResult<T>;
+/** A function that parses an unknown value into the schema `T`. */
+export type Parse<T extends Type> = Validate<T>;
+/**
+ * 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 declare const parse: <T extends Type>(rtti: T) => Parse<T>;

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,116 @@
+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;
+        };
+        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;
+    };
+};
+export default _default;