functionalscript 0.43.1 → 0.45.0

package/fjs/types/rtti/data/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Types for the serializable RTTI data form.
+ *
+ * A schema in data form denotes a set of values. The representation
+ * partitions that set into six disjoint *kinds* — unit values (`null`,
+ * `undefined`, `false`, `true`), numbers, strings, bigints, arrays and
+ * objects — so that union, equality and subset reduce to kind-wise set
+ * operations. See `./README.md` for the design rationale.
+ *
+ * @module
+ */
+import type { StringMap } from '../../object/types.ts';
+/**
+ * A set of values of one kind: `true` is the whole kind, an array lists its
+ * members (literals or patterns), canonically sorted and deduplicated. An
+ * empty kind is an absent property of {@link UnionSet}, never an empty array.
+ */
+export type KindSet<T> = true | readonly T[];
+/**
+ * A set of arrays: a tuple with an optional rest.
+ *
+ * - `prefix` constrains the value set of each leading position.
+ * - `rest` present: the array may be any length `>= prefix.length`, and every
+ *   element past the prefix belongs to `rest`.
+ * - `rest` absent: the array length is exactly `prefix.length`.
+ *
+ * A tuple schema is `{ prefix }`; a uniform array schema is
+ * `{ prefix: [], rest }`. Both are points of the same kind, so
+ * `readonly [number] ⊂ readonly number[]` is a plain pattern inclusion.
+ */
+export type ArraySet = {
+    readonly prefix: readonly Node[];
+    readonly rest?: Node;
+};
+/**
+ * A set of objects: per-key value sets with an optional rest.
+ *
+ * - `props` constrains, per declared key, the value *read* at that key — an
+ *   absent property reads as `undefined`, so a key is required exactly when
+ *   its set excludes `undefined`. Keys are canonically sorted, and a key
+ *   whose set is the whole value domain is omitted.
+ * - `rest` present: the value at every other *present* key belongs to `rest`.
+ * - `rest` absent: other keys are unconstrained.
+ *
+ * A struct schema is `{ props }`; a uniform record schema is
+ * `{ props: {}, rest }`.
+ */
+export type ObjectSet = {
+    readonly props: StringMap<Node>;
+    readonly rest?: Node;
+};
+/**
+ * A set of values as a disjoint union over the six kinds. An absent
+ * component is the empty set of that kind, so `{}` is `never` and a union
+ * with every component at its maximum (see `unknown` in `./module.f.mjs`)
+ * is `unknown`.
+ *
+ * `unit` is a bitset over the four singleton values; bit `1 << i` stands for
+ * `unitList[i]` from `./module.f.mjs` (`['null', 'undefined', 'false',
+ * 'true']`), so `or(true, false)` collapses to the two boolean bits with no
+ * special-case rule.
+ */
+export type UnionSet = {
+    readonly unit?: number;
+    readonly number?: KindSet<number>;
+    readonly string?: KindSet<string>;
+    readonly bigint?: KindSet<bigint>;
+    readonly array?: KindSet<ArraySet>;
+    readonly object?: KindSet<ObjectSet>;
+};
+/**
+ * A nested type position: an inline {@link UnionSet}, or the name of a rule
+ * in the enclosing {@link RuleSet}. Only recursive definitions are named;
+ * everything else is inlined, so non-recursive schemas are pure trees.
+ */
+export type Node = UnionSet | string;
+/** Named recursive definitions, referenced by {@link Node} strings. */
+export type RuleSet = StringMap<UnionSet>;
+/**
+ * A complete serializable schema: the named recursive definitions plus the
+ * entry node. Produced by `toData` in `./module.f.mjs`.
+ */
+export type Data = readonly [RuleSet, Node];

package/fjs/types/rtti/module.f.d.mts

@@ -0,0 +1,83 @@
+/**
+ * Runtime type information (RTTI) — a type-safe schema system for describing and
+ * converting TypeScript types. See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Includes } from '../array/types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts'
+ */
+import type { Includes } from '../array/types.ts';
+import type { Assert } from '../../asserts/types.ts';
+import type { Equal } from '../ts/types.ts';
+import type { Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Or, Type } from './types.ts';
+declare const primitive0List: readonly ['bigint', 'boolean', 'number', 'string'];
+export type _Primitive0Pinned = Assert<Equal<Primitive0, typeof primitive0List[number]>>;
+/** @typedef {Assert<Equal<Primitive0, typeof primitive0List[number]>>} _Primitive0Pinned */
+export declare const tag0List: readonly ["bigint", "boolean", "number", "string", "unknown"];
+/**
+ * Schema that validates `boolean` values.
+ */
+export declare const boolean: _Type0<"boolean">;
+/**
+ * Schema that validates `number` values.
+ */
+export declare const number: _Type0<"number">;
+/**
+ * Schema that validates `string` values.
+ */
+export declare const string: _Type0<"string">;
+/**
+ * Schema that validates `bigint` values.
+ * @type {Bigint}
+ */
+export declare const bigint: Bigint;
+/**
+ * Schema that validates any DJS-compatible value.
+ * @type {Unknown}
+ */
+export declare const unknown: Unknown;
+declare const tag1List: readonly ['array', 'record'];
+export type _Tag1Pinned = Assert<Equal<Tag1, typeof tag1List[number]>>;
+/** @typedef {Assert<Equal<Tag1, typeof tag1List[number]>>} _Tag1Pinned */
+/** @type {Includes<string, typeof tag1List>} */
+export declare const isTag1: Includes<string, typeof tag1List>;
+/**
+ * Constructs a schema that validates `readonly Ts<T>[]`.
+ * @type {_MakeType1<'array'>}
+ */
+export declare const array: _MakeType1<'array'>;
+/**
+ * Constructs a schema that validates `{ readonly[K in string]: Ts<T> }`.
+ * @type {_MakeType1<'record'>}
+ */
+export declare const record: _MakeType1<'record'>;
+/**
+ * Constructs a schema that validates a value matching any of the given schemas.
+ *
+ * `or` is intentionally a lazy, allocation-free constructor: it captures its
+ * arguments in a thunk and does no flattening, deduplication, subset analysis,
+ * or canonical-form work. All such algebra lives on the serializable data form
+ * — see `./data/README.md`.
+ *
+ * @template {readonly Type[]} T
+ * @param {T} types
+ * @returns {Or<T>}
+ */
+export declare const or: <T extends readonly Type[]>(...types: T) => Or<T>;
+/**
+ * Constructs a schema that validates a value matching `T` or `undefined`.
+ *
+ * @template {Type} T
+ * @param {T} t
+ * @returns {Or<readonly [T, undefined]>}
+ */
+export declare const option: <T extends Type>(t: T) => Or<readonly [T, undefined]>;
+/**
+ * Schema that never matches any value — the empty union, corresponding to TypeScript's `never`.
+ * @type {Or<readonly []>}
+ */
+export declare const never: Or<readonly []>;
+export {};

package/fjs/types/rtti/module.f.mjs

@@ -0,0 +1,112 @@
+/**
+ * Runtime type information (RTTI) — a type-safe schema system for describing and
+ * converting TypeScript types. See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Includes } from '../array/types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ * @import { Tag0, Primitive0, _Type0, Bigint, Unknown, Tag1, _MakeType1, Array, Record, Or, Type } from './types.ts'
+ */
+
+import { includes } from '../array/module.f.mjs'
+
+const primitive0List = /** @type {const} */ (['bigint', 'boolean', 'number', 'string'])
+
+/** @typedef {Assert<Equal<Primitive0, typeof primitive0List[number]>>} _Primitive0Pinned */
+
+export const tag0List = /** @type {const} */ ([...primitive0List, 'unknown'])
+
+const type0 =
+    /**
+     * @template {Tag0} T
+     * @param {T} tag
+     * @returns {_Type0<T>}
+     */
+    tag => () => /** @type {any} */ ([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.
+ * @type {Bigint}
+ */
+export const bigint = type0('bigint')
+
+/**
+ * Schema that validates any DJS-compatible value.
+ * @type {Unknown}
+ */
+export const unknown = type0('unknown')
+
+const tag1List = /** @type {const} */ (['array', 'record'])
+
+/** @typedef {Assert<Equal<Tag1, typeof tag1List[number]>>} _Tag1Pinned */
+
+/** @type {Includes<string, typeof tag1List>} */
+export const isTag1 = includes(tag1List)
+
+const type1 =
+    /**
+     * @template {Tag1} K
+     * @param {K} key
+     * @returns {_MakeType1<K>}
+     */
+    key => t => () => /** @type {any} */ ([key, t])
+
+/**
+ * Constructs a schema that validates `readonly Ts<T>[]`.
+ * @type {_MakeType1<'array'>}
+ */
+export const array = type1('array')
+
+/**
+ * Constructs a schema that validates `{ readonly[K in string]: Ts<T> }`.
+ * @type {_MakeType1<'record'>}
+ */
+export const record = type1('record')
+
+/**
+ * Constructs a schema that validates a value matching any of the given schemas.
+ *
+ * `or` is intentionally a lazy, allocation-free constructor: it captures its
+ * arguments in a thunk and does no flattening, deduplication, subset analysis,
+ * or canonical-form work. All such algebra lives on the serializable data form
+ * — see `./data/README.md`.
+ *
+ * @template {readonly Type[]} T
+ * @param {T} types
+ * @returns {Or<T>}
+ */
+export const or = (...types) =>
+    () => ['or', ...types]
+
+/**
+ * Constructs a schema that validates a value matching `T` or `undefined`.
+ *
+ * @template {Type} T
+ * @param {T} t
+ * @returns {Or<readonly [T, undefined]>}
+ */
+export const option = t =>
+    or(t, undefined)
+
+/**
+ * Schema that never matches any value — the empty union, corresponding to TypeScript's `never`.
+ * @type {Or<readonly []>}
+ */
+export const never = or()

package/fjs/types/rtti/parse/module.f.d.mts

@@ -0,0 +1,47 @@
+/**
+ * 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.mjs`; only container construction differs.
+ *
+ * See `./types.ts` for the `Result`/`Parse` type-level API.
+ *
+ * @module
+ *
+ * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Result as CommonResult } from '../../result/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { List } from '../../list/types.ts'
+ * @import { Container, IsContainer, ValidateE, ValidationError, Visitor } from '../common/types.ts'
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { Parse } from './types.ts'
+ */
+import type { Type } from '../types.ts';
+import type { Result as CommonResult } from '../../result/types.ts';
+import type { ValidationError } from '../common/types.ts';
+import type { Unknown } from '../ts/types.ts';
+import type { Parse } from './types.ts';
+export type _ItemResult = CommonResult<Unknown, ValidationError>;
+export type _Rebuild = (entries: ReadonlyArray<readonly [string, Unknown]>) => Unknown;
+/** @type {<T extends Type>(rtti: T) => Parse<T>} */
+export declare const parse: <T extends Type>(rtti: T) => Parse<T>;

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

@@ -0,0 +1,198 @@
+/**
+ * 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.mjs`; only container construction differs.
+ *
+ * See `./types.ts` for the `Result`/`Parse` type-level API.
+ *
+ * @module
+ *
+ * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Result as CommonResult } from '../../result/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { List } from '../../list/types.ts'
+ * @import { Container, IsContainer, ValidateE, ValidationError, Visitor } from '../common/types.ts'
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { Parse } from './types.ts'
+ */
+
+import { ok } from '../../result/module.f.mjs'
+import { reverse, toArray } from '../../list/module.f.mjs'
+import {
+    constPrimitiveValidate,
+    eachEntry,
+    isArray,
+    isObject,
+    orVisit,
+    primitive0Validate,
+    verror,
+    visit,
+} from '../common/module.f.mjs'
+
+const { entries } = Object
+
+/** @typedef {CommonResult<Unknown, ValidationError>} _ItemResult */
+
+/** Rebuilds a parsed container from its `[key, parsedValue]` entries. */
+/** @typedef {(entries: ReadonlyArray<readonly [string, Unknown]>) => Unknown} _Rebuild */
+
+/** @type {_Rebuild} */
+const arrayRebuild = entries => entries.map(([, v]) => v)
+
+/** @type {_Rebuild} */
+const recordRebuild = entries => Object.fromEntries(entries)
+
+/** `eachEntry`'s accumulator seed: entries are consed on in reverse as they parse. */
+/** @type {List<readonly [string, Unknown]>} */
+const emptyEntries = null
+
+/** `eachEntry`'s accumulate step: an O(1) prepend, unlike rebuilding an array on every entry. */
+/** @type {(acc: List<readonly [string, Unknown]>, k: string, v: Unknown) => List<readonly [string, Unknown]>} */
+const consEntry = (acc, k, v) =>
+    ({ first: [k, v], tail: acc })
+
+/** Restores forward order from `consEntry`'s reverse-order list, in one linear pass. */
+/** @type {(list: List<readonly [string, Unknown]>) => ReadonlyArray<readonly [string, Unknown]>} */
+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 =
+    /**
+     * @template {Tag1} K
+     * @param {IsContainer<Container<K>>} isContainer
+     * @param {_Rebuild} rebuild
+     * @returns {<I extends Type>(item: I) => Parse<Info1<K, I>>}
+     */
+    (isContainer, rebuild) =>
+    item => value => {
+        if (!isContainer(value)) {
+            return verror('unexpected value')
+        }
+        const e = entries(value)
+        if (e.length === 0) {
+            return /** @type {any} */ (ok(rebuild([])))
+        }
+        const itemParse = /** @type {(v: Unknown) => _ItemResult} */ (/** @type {any} */ (parse(item)))
+        const r = eachEntry(e, (_k, v) => itemParse(v), emptyEntries, consEntry)
+        return r[0] === 'error' ? r : /** @type {any} */ (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 =
+    /**
+     * @template {Unknown} C
+     * @param {IsContainer<C>} isContainer
+     * @param {(value: C, k: string) => Unknown} getItem
+     * @param {_Rebuild} rebuild
+     * @returns {<T extends Tuple | Struct>(rtti: T) => Parse<T>}
+     */
+    (isContainer, getItem, rebuild) =>
+    rtti => value => {
+        if (!isContainer(value)) {
+            return verror('unexpected value')
+        }
+        const r = eachEntry(
+            entries(rtti),
+            (k, t) => /** @type {_ItemResult} */ (/** @type {any} */ (parse(t))(getItem(value, k))),
+            emptyEntries,
+            consEntry,
+        )
+        return r[0] === 'error' ? r : /** @type {any} */ (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 =
+    /**
+     * @template {readonly Type[]} T
+     * @param {T} rtti
+     * @returns {Parse<() => readonly ['or', ...T]>}
+     */
+    rtti =>
+        /** @type {any} */ (orVisit(/** @type {(t: Type) => ValidateE} */ (/** @type {any} */ (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
+ * ```js
+ * 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])([1, 2, 3]) // ['ok', [1, 2]]
+ *
+ * // structs drop undeclared keys
+ * parse({ a: number })({ a: 1, b: 2 }) // ['ok', { a: 1 }]
+ * ```
+ */
+const parseVisitor = /** @type {any} */ ({
+    tuple: tupleParse,
+    struct: structParse,
+    array: arrayParse,
+    record: recordParse,
+    or: orParse,
+    constPrimitive: constPrimitiveValidate,
+    primitive0: primitive0Validate,
+    unknown: () => ok,
+})
+
+/** @type {<T extends Type>(rtti: T) => Parse<T>} */
+export const parse = rtti =>
+    /** @type {any} */ (visit(parseVisitor)(rtti))

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

@@ -0,0 +1,122 @@
+/**
+ * @import { ValidationError } from '../common/types.ts'
+ * @import { Equal } from '../../ts/types.ts'
+ * @import { Ts } from '../ts/types.ts'
+ * @import { Unknown as DjsUnknown } from '../../../djs/types.ts'
+ * @import { Assert } from '../../../asserts/types.ts'
+ */
+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;
+    };
+};