functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,99 @@
+/**
+ * TypeScript type transformers for RTTI schemas.
+ *
+ * Each `*Ts` type maps a schema (or schema fragment) to its corresponding TypeScript type.
+ * The main entry point is `Ts<T>`.
+ *
+ * The runtime `toTs` function (`printer` in `./module.f.mjs`) mirrors `Ts<T>` at value
+ * level, returning a TypeScript type expression string for a given RTTI schema.
+ *
+ * @module
+ */
+import type { Tag0, Tag1, Struct, Tuple, Type } from '../types.ts';
+import type { phantomKey } from '../../phantom/types.ts';
+import type { StringMap } from '../../object/types.ts';
+/**
+ * The set of primitive literal types representable as rtti `Const` values.
+ * Defined here rather than imported from `djs` to keep rtti free of djs dependencies
+ * (djs depends on rtti, not the other way around — see [i665-rtti-defines-types]).
+ */
+export type Primitive = null | boolean | number | string | undefined | bigint;
+/**
+ * The TypeScript type that rtti's `unknown` schema validates — any value that
+ * an rtti schema can represent: a primitive, an array, or an object.
+ *
+ * This is the single source of truth for the rtti value domain: every rtti
+ * module (`common`, `validate`, `parse`, …) imports `Unknown`/`Primitive`
+ * from here, not from `djs`, keeping `rtti` free of a `djs` dependency (djs
+ * depends on rtti, not the other way around).
+ *
+ * The relationship to djs is a subset one — `djs.Unknown ⊆ rtti.Unknown` — not
+ * equality: the two happen to coincide today, but `rtti.Unknown` may widen to
+ * admit values djs cannot represent (e.g. functions) without djs following.
+ * Do not re-point rtti imports at `djs.Unknown` on the assumption they match.
+ */
+export type Unknown = Primitive | Array | Object;
+/** A read-only array of {@link Unknown} values. */
+export type Array = readonly Unknown[];
+/** A read-only record of {@link Unknown} values. */
+export type Object = {
+    readonly [k in string]?: Unknown;
+};
+/** Maps a `Tag0` to its TypeScript type. */
+export type Info0Ts<T extends Tag0> = T extends 'boolean' ? boolean : T extends 'number' ? number : T extends 'string' ? string : T extends 'bigint' ? bigint : T extends 'unknown' ? Unknown : never;
+/** Maps a `Const` schema to its TypeScript type. */
+export type ConstTs<T> = T extends readonly Type[] ? TupleTs<T> : T extends StringMap<Type> ? StructTs<T> : T;
+/** Maps a `Tag1` and inner type to its TypeScript type. */
+export type Info1Ts<K extends Tag1, T extends Type> = K extends 'array' ? ArrayTs<T> : K extends 'record' ? RecordTs<T> : never;
+/** Maps an array schema `T` to `readonly Ts<T>[]`. */
+export type ArrayTs<T extends Type> = ReadonlyArray<Ts<T>>;
+/** Maps a record schema `T` to `{ readonly[K in string]?: Ts<T> }`. */
+export type RecordTs<T extends Type> = {
+    readonly [K in string]?: Ts<T>;
+};
+/** Maps a tuple schema to a readonly tuple of resolved types. */
+export type TupleTs<T extends Tuple> = {
+    readonly [K in keyof T]: Ts<T[K]>;
+};
+type OptionalFields<T extends Struct> = {
+    readonly [K in keyof T as undefined extends Ts<T[K]> ? K : never]?: Ts<T[K]>;
+};
+type RequiredFields<T extends Struct> = {
+    readonly [K in keyof T as undefined extends Ts<T[K]> ? never : K]: Ts<T[K]>;
+};
+/** Maps a struct schema to a readonly object of resolved types, with optional fields for schemas that include `undefined`. */
+export type StructTs<T extends Struct> = (keyof OptionalFields<T> extends never ? unknown : OptionalFields<T>) & (keyof RequiredFields<T> extends never ? unknown : RequiredFields<T>);
+/**
+ * Converts a schema `Type` to its corresponding TypeScript type.
+ *
+ * - `Thunk` → evaluates the returned `Info` via `InfoTs`
+ * - `Const` → resolves via `ConstTs` (primitives map to themselves; structs/tuples recurse)
+ *
+ * **Recursive schemas and TS2589:** when a schema is self-referential, `StructTs` would
+ * expand infinitely and TypeScript raises TS2589. Break the cycle by annotating the
+ * schema value with `Phantom<typeof myThunk, MyType>` from `fjs/types/phantom/types.ts`.
+ * `Ts<>` detects the phantom key and returns `MyType` directly without recursing:
+ *
+ * ```ts
+ * import { type Phantom } from '../../phantom/types.ts'
+ *
+ * type MyType = { readonly self?: MyType }
+ * const myThunk = () => ['const', myConst] as const
+ * export const my: Phantom<typeof myThunk, MyType> = myThunk
+ * // Ts<typeof my>  →  MyType
+ * ```
+ *
+ * @example
+ * ```ts
+ * type A = Ts<typeof string>          // string
+ * type B = Ts<4>                      // 4
+ * type C = Ts<Array<typeof number>>   // readonly number[]
+ * type D = Ts<{ x: typeof boolean }>  // { readonly x: boolean }
+ * ```
+ */
+export type Ts<T extends Type> = unknown extends T ? Unknown : T extends {
+    readonly [phantomKey]?: infer O;
+} ? Exclude<O, undefined> : T extends () => infer I ? (I extends readonly ['const', infer C] ? ConstTs<C> : I extends readonly ['boolean'] ? boolean : I extends readonly ['number'] ? number : I extends readonly ['string'] ? string : I extends readonly ['bigint'] ? bigint : I extends readonly ['unknown'] ? Unknown : I extends readonly ['array', infer E extends Type] ? readonly Ts<E>[] : I extends readonly ['record', infer E extends Type] ? {
+    readonly [k in string]?: Ts<E>;
+} : I extends readonly ['or', ...infer A extends readonly Type[]] ? Ts<A[number]> : never) : ConstTs<T>;
+export {};

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

@@ -0,0 +1,83 @@
+/**
+ * Type-level API for runtime type information (RTTI) — a type-safe schema
+ * system for describing and converting TypeScript types.
+ *
+ * ## Core concepts
+ *
+ * A `Type` is either a `Const` (used directly as its own schema) or a `Thunk`
+ * (a zero-argument function returning an `Info` descriptor). Thunks are the
+ * primary building block: they enable lazy evaluation and recursive type definitions.
+ *
+ * ```
+ * Type = Const | Thunk
+ * Thunk = () => Info
+ * Info = ['const', Const] | Info0<Tag0> | Info1<Tag1, Type>
+ * ```
+ *
+ * ## Nullary schemas (no type parameter)
+ *
+ * `boolean`, `number`, `string`, `bigint`, `unknown` are pre-built `Thunk` values
+ * that describe primitive types. Each is a `_Type0<Tag0>` — a thunk returning a
+ * single-element tag tuple.
+ *
+ * ## Unary schemas (one type parameter)
+ *
+ * `array(t)` and `record(t)` construct `Thunk` values parameterized by an inner
+ * `Type`. They return `Type1` thunks wrapping an `Info1` tuple.
+ *
+ * ## Const schemas
+ *
+ * Any `Primitive`, `Struct` (plain object), or `Tuple` (readonly array) can be
+ * used directly as a schema — it describes exactly the shape of that value.
+ * Inside a recursive `Thunk`-based definition, wrap consts with `() => ['const', c]`
+ * to keep the schema uniform.
+ *
+ * ## Converting to TypeScript types
+ *
+ * See `./ts/module.f.ts` for `Ts<T>` and the `*Ts` transformer types.
+ *
+ * @module
+ */
+import type { StringMap } from '../object/types.ts';
+import type { tag0List } from './module.f.mjs';
+/** A constant schema: a primitive literal, a struct object, or a tuple. */
+export type Const = null | boolean | number | string | undefined | bigint | {
+    readonly [K in string]: Type;
+} | readonly Type[];
+export type ConstObject = Struct | Tuple;
+/** A struct schema: plain object whose values are nested `Type`s. */
+export type Struct = StringMap<Type>;
+/** A tuple schema: readonly array whose elements are nested `Type`s. */
+export type Tuple = readonly Type[];
+export type Primitive0 = 'bigint' | 'boolean' | 'number' | 'string';
+/** Tags for nullary (zero-parameter) type schemas. */
+export type Tag0 = typeof tag0List[number];
+/** Info tuple for a nullary tag: `readonly[tag]`. */
+export type Info0<T extends Tag0> = T extends Tag0 ? readonly [T] : never;
+/** Any schema: a `Const` used directly, or a `Thunk` for tag-based/recursive schemas. */
+export type Type = (() => (readonly ['const', Const] | readonly ['bigint'] | readonly ['boolean'] | readonly ['number'] | readonly ['string'] | readonly ['unknown'] | readonly ['array', Type] | readonly ['record', Type] | readonly ['or', ...readonly Type[]])) | Const;
+/** The type of a nullary thunk for `Tag0`. */
+export type _Type0<T extends Tag0> = () => Info0<T>;
+/** Schema type for `boolean`. */
+export type Boolean = _Type0<'boolean'>;
+/** Schema type for `number`. */
+export type Number = _Type0<'number'>;
+/** Schema type for `string`. */
+export type String = _Type0<'string'>;
+/** Schema type for `bigint`. */
+export type Bigint = _Type0<'bigint'>;
+/** Schema type for any DJS value (`Primitive | UnknownRecord | UnknownArray`). */
+export type Unknown = _Type0<'unknown'>;
+/** Tags for unary (one-parameter) type schemas. */
+export type Tag1 = 'array' | 'record';
+/** Info tuple for a unary tag: `readonly[tag, innerType]`. */
+export type Info1<K extends Tag1, T extends Type> = K extends Tag1 ? readonly [K, T] : never;
+/** The type of a unary thunk for `Tag1` with inner type `T`. */
+export type Type1<K extends Tag1, T extends Type> = () => Info1<K, T>;
+export type _MakeType1<K extends Tag1> = <T extends Type>(t: T) => Type1<K, T>;
+/** Schema type for a readonly array with element type `T`. */
+export type Array<T extends Type> = Type1<'array', T>;
+/** Schema type for a record (index signature) with value type `T`. */
+export type Record<T extends Type> = Type1<'record', T>;
+/** Schema type for a union of types `T`. */
+export type Or<T extends readonly Type[]> = () => readonly ['or', ...T];

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

@@ -0,0 +1,41 @@
+/**
+ * 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
+ *
+ * Schema recognition is delegated to `visit` in `../common/module.f.mjs`,
+ * which routes each `Type` variant to a handler in the `Visitor` record
+ * defined below. `validate` returns the original value on success — no
+ * fresh allocation — which is the only behavior that distinguishes it
+ * from `parse`.
+ *
+ * ## 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]`.
+ *
+ * See `./types.ts` for the `Path`/`Result`/`Validate`/`ValidationError` type-level API.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { Container, IsContainer, Validate, ValidateE, Visitor } from '../common/types.ts'
+ */
+import type { Type } from '../types.ts';
+import type { Validate } from '../common/types.ts';
+export { constPrimitiveValidate, prependPath, primitive0Validate, verror, } from '../common/module.f.mjs';
+/** @type {<T extends Type>(rtti: T) => Validate<T>} */
+export declare const validate: <T extends Type>(rtti: T) => Validate<T>;

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

@@ -0,0 +1,171 @@
+/**
+ * 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
+ *
+ * Schema recognition is delegated to `visit` in `../common/module.f.mjs`,
+ * which routes each `Type` variant to a handler in the `Visitor` record
+ * defined below. `validate` returns the original value on success — no
+ * fresh allocation — which is the only behavior that distinguishes it
+ * from `parse`.
+ *
+ * ## 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]`.
+ *
+ * See `./types.ts` for the `Path`/`Result`/`Validate`/`ValidationError` type-level API.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { Container, IsContainer, Validate, ValidateE, Visitor } from '../common/types.ts'
+ */
+
+import { ok } from '../../result/module.f.mjs'
+import {
+    constPrimitiveValidate,
+    eachEntry,
+    isArray,
+    isObject,
+    orVisit,
+    primitive0Validate,
+    verror,
+    visit,
+} from '../common/module.f.mjs'
+
+export {
+    constPrimitiveValidate,
+    prependPath,
+    primitive0Validate,
+    verror,
+} from '../common/module.f.mjs'
+
+const { entries } = Object
+
+/** `validate` has nothing to collect from a successful entry — only pass/fail matters. */
+const noAccumulate = () => undefined
+
+/**
+ * Builds a validator for `array` or `record` schemas.
+ * The inner item validator is instantiated lazily (only when the container is
+ * non-empty) to avoid infinite recursion with recursive schemas.
+ */
+const containerValidate =
+    /**
+     * @template {Tag1} K
+     * @param {IsContainer<Container<K>>} isContainer
+     * @returns {<I extends Type>(item: I) => Validate<Info1<K, I>>}
+     */
+    isContainer =>
+    item => value => {
+        if (!isContainer(value)) {
+            return verror('unexpected value')
+        }
+        const e = entries(value)
+        if (e.length === 0) {
+            return ok(value)
+        }
+        // Note: we shouldn't instantiate `itemValidate` until we make sure `entries` is not empty.
+        //       Otherwise, we can get infinite recursion on empty arrays and objects
+        const itemValidate = validate(item)
+        const r = eachEntry(e, (_k, v) => itemValidate(v), undefined, noAccumulate)
+        // `value` is Container<K>, but Ts<Info1<K,I>> = readonly Ts<I>[] | Record<string,Ts<I>>.
+        // TypeScript can't narrow the container's element types through the validation loop.
+        return r[0] === 'error' ? r : /** @type {any} */ (ok(value))
+    }
+
+const arrayValidate = containerValidate(isArray)
+
+const recordValidate = containerValidate(isObject)
+
+/**
+ * Builds a validator for `Tuple` or `Struct` const schemas.
+ * Iterates over the schema's entries and validates each corresponding
+ * element/property of the value.
+ */
+const constContainerValidate =
+    /**
+     * @template {Unknown} C
+     * @param {IsContainer<C>} isContainer
+     * @param {(value: C, k: string) => Unknown} getItem
+     * @returns {<T extends Tuple | Struct>(rtti: T) => Validate<T>}
+     */
+    (isContainer, getItem) =>
+    rtti => value => {
+        if (!isContainer(value)) {
+            return verror('unexpected value')
+        }
+        const r = eachEntry(
+            Object.entries(rtti),
+            (k, v) => /** @type {any} */ (validate(v))(getItem(value, k)),
+            undefined,
+            noAccumulate,
+        )
+        // `value` is C (Unknown container), but Ts<T> for T extends Tuple|Struct is not
+        // structurally equivalent to C — TypeScript can't narrow element types through the loop.
+        return r[0] === 'error' ? r : /** @type {any} */ (ok(value))
+    }
+
+const tupleValidate = constContainerValidate(
+    isArray,
+    (value, k) => value[Number(k)]
+)
+
+const structValidate = constContainerValidate(
+    isObject,
+    (value, k) => value[k]
+)
+
+const orValidate =
+    /**
+     * @template {readonly Type[]} T
+     * @param {T} rtti
+     * @returns {Validate<() => readonly ['or', ...T]>}
+     */
+    rtti =>
+        /** @type {any} */ (orVisit(/** @type {(t: Type) => ValidateE} */ (/** @type {any} */ (validate)))(rtti))
+
+/**
+ * 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
+ * ```js
+ * 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' }]
+ * ```
+ */
+const validateVisitor = /** @type {any} */ ({
+    tuple: tupleValidate,
+    struct: structValidate,
+    array: arrayValidate,
+    record: recordValidate,
+    or: orValidate,
+    constPrimitive: constPrimitiveValidate,
+    primitive0: primitive0Validate,
+    unknown: () => ok,
+})
+
+/** @type {<T extends Type>(rtti: T) => Validate<T>} */
+export const validate = rtti =>
+    /** @type {any} */ (visit(validateVisitor)(rtti))

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

@@ -0,0 +1,125 @@
+/**
+ * @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;
+            extraItems: () => void;
+            error: () => void;
+        };
+        struct: {
+            ok: () => void;
+            extraKeys: () => void;
+            error: () => void;
+        };
+    };
+    array: {
+        empty: () => void;
+        ok: () => void;
+        error: () => void;
+        nested: () => void;
+    };
+    record: {
+        empty: () => void;
+        ok: () => void;
+        error: () => void;
+    };
+    constThunk: {
+        primitive: () => void;
+    };
+    or: {
+        consts: {
+            ok: () => void;
+            error: () => void;
+        };
+        thunks: {
+            ok: () => void;
+            error: () => void;
+        };
+        mixed: {
+            ok: () => void;
+            error: () => 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;
+    };
+    funcParam: () => () => void;
+    funcObj: () => () => void;
+};