functionalscript 0.43.1 → 0.44.0

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

@@ -0,0 +1,183 @@
+/**
+ * Shared kernel for RTTI consumers (`validate`, `parse`).
+ *
+ * Both consumers traverse the same schema shape and produce the same
+ * `Result<T, ValidationError>` outcome. Only the per-variant handling differs
+ * — `validate` keeps the original value, `parse` constructs a fresh one.
+ *
+ * This module hosts the parts that do not differ:
+ *
+ * - The error shape (`ValidationError`, `Path`) and path bookkeeping
+ *   (`verror`, `prependPath`).
+ * - Primitive checks (`primitive0Validate`, `constPrimitiveValidate`).
+ * - The `Validate<T>`/`Result<T>` signatures — `parse` uses the same shape.
+ * - `visit`: a visitor over the `Type` ADT. Callers supply a `Visitor<R>`
+ *   with one handler per variant; `visit(v)(rtti)` recognizes `rtti` and
+ *   calls the matching handler. Both consumers compose their top-level
+ *   function from a visitor.
+ * - `eachEntry`: the container entry loop (array/record/tuple/struct), shared
+ *   by both consumers' container builders. Callers choose what (if anything)
+ *   to accumulate, so `validate`'s pure pass/fail check pays no allocation.
+ * - `orVisit`: the shared `or` handler — try each variant's recursive walker,
+ *   return the first match.
+ *
+ * Keeping the kernel here also removes `parse`'s incidental dependency on
+ * `validate` and gives future schema-driven consumers (e.g. the data form
+ * sketched in [i143](../../../../issues/README.md)) a stable shared base.
+ *
+ * @module
+ */
+/** @import { Primitive, Unknown } from '../ts/types.ts' */
+/** @import { Const, Info0, Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts' */
+/** @import { Error, Result as CommonResult } from '../../result/types.ts' */
+import { error, ok } from '../../result/module.f.mjs'
+import { isArray as commonIsArray } from '../../array/module.f.mjs'
+import { isObject as commonIsObject } from '../../object/module.f.mjs'
+/** @import { StringMap } from '../../object/types.ts' */
+/** @import { Validate, Visitor, IsContainer, Container, ResultE, ValidateE, ValidationError } from './types.ts' */
+
+/** Builds an error result with empty path and the given message. */
+/** @type {(message: string) => Error<ValidationError>} */
+export const verror = message =>
+    error({ path: [], message })
+
+/** Prepends `key` to the error's path, used to build the path bottom-up. */
+/** @type {(key: string, error: Error<ValidationError>) => Error<ValidationError>} */
+export const prependPath = (key, [,r]) =>
+    error({ path: [key, ...r.path], message: r.message })
+
+/** Validates a `Tag0` primitive schema using `typeof`. */
+export const primitive0Validate =
+    /**
+     * @template {Primitive0} K
+     * @template {Info0<K>} T
+     * @param {K} tag
+     * @returns {Validate<T>}
+     */
+    tag =>
+        value => typeof value === tag ? /** @type {any} */ (ok(value)) : verror('unexpected value')
+
+/**
+ * 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 const constPrimitiveValidate =
+    /**
+     * @template {Primitive} T
+     * @param {T} rtti
+     * @returns {Validate<T>}
+     */
+    rtti =>
+        value => Object.is(rtti, value)
+            ? /** @type {any} */ (ok(value))
+            : verror('unexpected value')
+
+/** @type {<R>(v: Visitor<R>) => (c: Const) => R} */
+const visitConst = v => c =>
+    typeof c === 'object' && c !== null
+        ? (commonIsArray(c) ? v.tuple(c) : v.struct(/** @type {Struct} */ (c)))
+        : v.constPrimitive(/** @type {Primitive} */ (c))
+
+/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+/** @type {IsContainer<ReadonlyArray<Unknown>>} */
+export const isArray =
+    value => commonIsArray(value)
+
+/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+/** @type {IsContainer<StringMap<Unknown>>} */
+export const isObject =
+    value => commonIsObject(value)
+
+/**
+ * Runs `item` over each `[key, value]` entry, bailing out with the first
+ * error, path-prefixed with that entry's key. On success, folds each item's
+ * result into `acc` (starting from `init`) with `accumulate` and returns the
+ * final accumulator.
+ *
+ * Shared by `validate` and `parse`'s container builders (array/record/tuple/
+ * struct), which differ only in what `item` does with the value and what
+ * they accumulate: `validate` has nothing to collect — its entire schema is
+ * "did every entry succeed?" — so it passes `undefined`/`(acc) => acc` and
+ * pays no allocation per entry; `parse` needs the rebuilt `[key, value]`
+ * pairs, so it folds them into a `List` (see its call site) and converts to
+ * an array once at the end.
+ */
+export const eachEntry =
+    /**
+     * @template V
+     * @template R
+     * @template A
+     * @param {ReadonlyArray<readonly [string, V]>} entries
+     * @param {(k: string, v: V) => CommonResult<R, ValidationError>} item
+     * @param {A} init
+     * @param {(acc: A, k: string, value: R) => A} accumulate
+     * @returns {CommonResult<A, ValidationError>}
+     */
+    (entries, item, init, accumulate) => {
+        let acc = init
+        for (const [k, v] of entries) {
+            const r = item(k, v)
+            if (r[0] === 'error') {
+                return prependPath(k, r)
+            }
+            acc = accumulate(acc, k, r[1])
+        }
+        return ok(acc)
+    }
+
+/**
+ * First variant in `variants` that `recurse` accepts, else `verror('no match')`.
+ *
+ * Shared `or` handler for `validate` and `parse`: both try each variant
+ * against the value and return the first `'ok'` verbatim, differing only in
+ * which recursive function (`validate` or `parse`) walks each variant. `recurse`
+ * is typed over the erased `ValidateE` alias — annotating it as `(t: Type) =>
+ * Validate<Type>` would itself instantiate `Validate<Type>` and hit TS2589 —
+ * so each caller passes its recursive function through one boundary cast.
+ *
+ * @type {(recurse: (t: Type) => ValidateE) => (variants: readonly Type[]) => (value: Unknown) => ResultE}
+ */
+export const orVisit =
+    recurse =>
+    variants => value => {
+        for (const t of variants) {
+            const r = recurse(t)(value)
+            if (r[0] === 'ok') {
+                return r
+            }
+        }
+        return verror('no match')
+    }
+
+/**
+ * Visits a schema `Type` by dispatching to the matching handler in `v`.
+ *
+ * - `Thunk` schemas are evaluated once to read the `Info` descriptor, then
+ *   routed by tag (`'const'`, `'array'`, `'record'`, `'unknown'`, `'or'`,
+ *   or a `Tag0` primitive).
+ * - `Const` schemas (primitives, tuples, structs) are routed directly to
+ *   `tuple`, `struct`, or `constPrimitive`.
+ */
+export const visit =
+    /**
+     * @template R
+     * @param {Visitor<R>} v
+     * @returns {(rtti: Type) => R}
+     */
+    v => rtti => {
+        if (typeof rtti === 'function') {
+            const [tag, ...value] = rtti()
+            switch (tag) {
+                case 'const': return visitConst(v)(/** @type {Const} */ (value[0]))
+                case 'array': return v.array(value[0])
+                case 'record': return v.record(value[0])
+                case 'unknown': return v.unknown()
+                case 'or': return v.or(value)
+            }
+            return v.primitive0(/** @type {Primitive0} */ (tag))
+        }
+        return visitConst(v)(rtti)
+    }

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

@@ -0,0 +1,9 @@
+export type _Entries = ReadonlyArray<readonly [string, number]>;
+export declare const proof: {
+    empty: () => void;
+    allOk: () => void;
+    noAccumulate: () => void;
+    firstErrorWins: () => void;
+    shortCircuits: () => void;
+    pathPrefixed: () => void;
+};

package/fjs/types/rtti/common/proof.f.mjs

@@ -0,0 +1,64 @@
+import { eachEntry } from './module.f.mjs'
+/** @import { Result } from '../../result/types.ts' */
+import { error, ok } from '../../result/module.f.mjs'
+/** @import { ValidationError } from './types.ts' */
+import { assert, assertEq } from '../../../asserts/module.f.mjs'
+
+/** @typedef {ReadonlyArray<readonly [string, number]>} _Entries */
+
+/** @type {(k: string, v: number) => Result<number, ValidationError>} */
+const item = (k, v) =>
+    v < 0 ? error({ path: [], message: `negative at ${k}` }) : ok(v * 2)
+
+/** Mirrors `parse`'s accumulate step, kept simple (a small test list, not a `List`). */
+/** @type {(acc: _Entries, k: string, v: number) => _Entries} */
+const collect = (acc, k, v) => [...acc, [k, v]]
+
+export const proof = {
+    empty: () => {
+        const r = eachEntry(/** @type {_Entries} */ ([]), item, /** @type {_Entries} */ ([]), collect)
+        assert(r[0] === 'ok')
+        assertEq(r[1].length, 0)
+    },
+    allOk: () => {
+        const r = eachEntry([['a', 1], ['b', 2]], item, /** @type {_Entries} */ ([]), collect)
+        assert(r[0] === 'ok')
+        assertEq(r[1].length, 2)
+        assertEq(r[1][0][0], 'a')
+        assertEq(r[1][0][1], 2)
+        assertEq(r[1][1][0], 'b')
+        assertEq(r[1][1][1], 4)
+    },
+    // Mirrors `validate`'s usage: nothing is collected, only pass/fail matters.
+    noAccumulate: () => {
+        const r = eachEntry([['a', 1]], item, undefined, () => undefined)
+        assert(r[0] === 'ok')
+        assertEq(r[1], undefined)
+    },
+    firstErrorWins: () => {
+        const r = eachEntry([['a', -1], ['b', -2]], item, /** @type {_Entries} */ ([]), collect)
+        assert(r[0] === 'error')
+        assertEq(r[1].message, 'negative at a')
+    },
+    shortCircuits: () => {
+        let calls = 0
+        /** @type {(k: string, v: number) => Result<number, ValidationError>} */
+        const counting = (k, v) => {
+            calls++
+            return item(k, v)
+        }
+        const r = eachEntry([['a', -1], ['b', -2], ['c', -3]], counting, /** @type {_Entries} */ ([]), collect)
+        assert(r[0] === 'error')
+        assertEq(calls, 1)
+    },
+    pathPrefixed: () => {
+        /** @type {(k: string, v: number) => Result<number, ValidationError>} */
+        const nested = (k, v) =>
+            v < 0 ? error({ path: ['inner'], message: 'bad' }) : ok(v)
+        const r = eachEntry([['outer', -1]], nested, /** @type {_Entries} */ ([]), collect)
+        assert(r[0] === 'error')
+        assertEq(r[1].path.length, 2)
+        assertEq(r[1].path[0], 'outer')
+        assertEq(r[1].path[1], 'inner')
+    },
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Type-level API shared by RTTI consumers (`validate`, `parse`).
+ *
+ * @module
+ */
+import type { Primitive, Unknown } from '../ts/types.ts';
+import type { Primitive0, Struct, Tag1, Tuple, Type } from '../types.ts';
+import type { Result as CommonResult } from '../../result/types.ts';
+import type { Ts } from '../ts/types.ts';
+import type { StringMap } from '../../object/types.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/parse result: either the typed value or a `ValidationError`. */
+export type Result<T extends Type> = CommonResult<Ts<T>, ValidationError>;
+/** A function that checks an unknown value against schema `T`. Shared by `validate` and `parse`. */
+export type Validate<T extends Type> = (value: Unknown) => Result<T>;
+/**
+ * One handler per `Type` variant. Both `validate` and `parse` provide a
+ * `Visitor<R>` where `R` is the per-variant output (e.g. a `Validate` function).
+ */
+export type Visitor<R> = {
+    readonly tuple: (rtti: Tuple) => R;
+    readonly struct: (rtti: Struct) => R;
+    readonly array: (item: Type) => R;
+    readonly record: (item: Type) => R;
+    readonly or: (variants: readonly Type[]) => R;
+    readonly constPrimitive: (p: Primitive) => R;
+    readonly primitive0: (tag: Primitive0) => R;
+    readonly unknown: () => R;
+};
+/** Type guard narrowing `Unknown` to a specific container type `C`. */
+export type IsContainer<C extends Unknown> = (value: Unknown) => value is C;
+/** Maps a `Tag1` to its runtime container type. */
+export type Container<K extends Tag1> = K extends 'array' ? ReadonlyArray<Unknown> : StringMap<Unknown>;
+/** `Result` with the payload type erased; avoids instantiating `Ts<Type>`. */
+export type ResultE = CommonResult<Unknown, ValidationError>;
+/** A `Validate`-shaped function with the payload type erased. */
+export type ValidateE = (value: Unknown) => ResultE;

package/fjs/types/rtti/common/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,76 @@
+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';
+/** @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' */
+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 `issues/143-rtti-data.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,110 @@
+/**
+ * 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/module.f.mjs'
+/** @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' */
+
+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 `issues/143-rtti-data.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,9 @@
+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>;