functionalscript 0.43.0 → 0.44.0

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

@@ -1,118 +0,0 @@
-import type { Tag0, Tag1, Struct, Tuple, Type } from '../module.f.ts';
-import type { phantomKey } from '../../phantom/module.f.ts';
-import type { StringMap } from '../../object/module.f.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/module.f.ts`.
- * `Ts<>` detects the phantom key and returns `MyType` directly without recursing:
- *
- * ```ts
- * import { type Phantom } from '../types/phantom/module.f.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>;
-/**
- * Creates a printer that converts an RTTI schema `Type` to its TypeScript type expression as a string.
- *
- * Mirrors the compile-time `Ts<T>` mapped type at runtime.
- * Pass `true` to emit mutable (non-`readonly`) types.
- *
- * **Note:** recursive schemas (e.g. `const list = () => ['array', list] as const`)
- * will cause infinite recursion. Only acyclic schemas are supported.
- *
- * **Note:** the `unknown` schema produces the string `'unknown'` (TypeScript's built-in),
- * whereas `Ts<>` maps it to `DjsUnknown` from `djs/module.f.ts`.
- *
- * @example
- * ```ts
- * const toTs = printer()
- * toTs(boolean)                    // 'boolean'
- * toTs(array(number))              // 'readonly(number)[]'
- * toTs(record(string))             // '{readonly[k in string]?:string}'
- * toTs(or(string, number))         // 'string|number'
- * toTs(42)                         // '42'
- * toTs('hello')                    // '"hello"'
- * toTs([boolean, number])          // 'readonly[boolean,number]'
- * toTs({ x: string })              // '{readonly"x":string}'
- *
- * const toTsMut = printer(true)
- * toTsMut(array(number))           // '(number)[]'
- * toTsMut(record(string))          // '{[k in string]?:string}'
- * ```
- */
-export declare const printer: (mut?: true) => (rtti: Type) => string;
-export {};

package/fjs/types/rtti/ts/module.f.js

@@ -1,59 +0,0 @@
-/**
- * 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 mirrors `Ts<T>` at value level, returning a TypeScript
- * type expression string for a given RTTI schema.
- */
-import { primitive, union, printer as tsPrinter } from '../../ts/module.f.js';
-/**
- * Creates a printer that converts an RTTI schema `Type` to its TypeScript type expression as a string.
- *
- * Mirrors the compile-time `Ts<T>` mapped type at runtime.
- * Pass `true` to emit mutable (non-`readonly`) types.
- *
- * **Note:** recursive schemas (e.g. `const list = () => ['array', list] as const`)
- * will cause infinite recursion. Only acyclic schemas are supported.
- *
- * **Note:** the `unknown` schema produces the string `'unknown'` (TypeScript's built-in),
- * whereas `Ts<>` maps it to `DjsUnknown` from `djs/module.f.ts`.
- *
- * @example
- * ```ts
- * const toTs = printer()
- * toTs(boolean)                    // 'boolean'
- * toTs(array(number))              // 'readonly(number)[]'
- * toTs(record(string))             // '{readonly[k in string]?:string}'
- * toTs(or(string, number))         // 'string|number'
- * toTs(42)                         // '42'
- * toTs('hello')                    // '"hello"'
- * toTs([boolean, number])          // 'readonly[boolean,number]'
- * toTs({ x: string })              // '{readonly"x":string}'
- *
- * const toTsMut = printer(true)
- * toTsMut(array(number))           // '(number)[]'
- * toTsMut(record(string))          // '{[k in string]?:string}'
- * ```
- */
-export const printer = (mut) => {
-    const { tuple, struct, array, record } = tsPrinter(mut);
-    const constToTs = (rtti) => typeof rtti !== 'object' || rtti === null ? primitive(rtti) :
-        rtti instanceof Array ? tuple(rtti.map(toTs)) :
-            struct(Object.entries(rtti).map(([k, v]) => [k, toTs(v)]));
-    const toTs = (rtti) => {
-        if (typeof rtti !== 'function') {
-            return constToTs(rtti);
-        }
-        const [tag, ...rest] = rtti();
-        switch (tag) {
-            case 'const': return constToTs(rest[0]);
-            case 'array': return array(toTs(rest[0]));
-            case 'record': return record(toTs(rest[0]));
-            case 'or': return union(rest.map(toTs));
-            default: return tag; // tag0: 'boolean' | 'number' | 'string' | 'bigint' | 'unknown'
-        }
-    };
-    return toTs;
-};

package/fjs/types/rtti/ts/proof.f.js

@@ -1,75 +0,0 @@
-import { printer } from './module.f.js';
-import { boolean, number, string, bigint, unknown, array, record, or, option, never } from '../module.f.js';
-const toTs = printer();
-const toTsMut = printer(true);
-const eqMut = (rtti, expected) => {
-    const result = toTsMut(rtti);
-    if (result !== expected) {
-        throw `expected ${JSON.stringify(expected)}, got ${JSON.stringify(result)}`;
-    }
-};
-const eq = (rtti, expected) => {
-    const result = toTs(rtti);
-    if (result !== expected) {
-        throw `expected ${JSON.stringify(expected)}, got ${JSON.stringify(result)}`;
-    }
-};
-export const proof = {
-    tag0: {
-        boolean: () => eq(boolean, 'boolean'),
-        number: () => eq(number, 'number'),
-        string: () => eq(string, 'string'),
-        bigint: () => eq(bigint, 'bigint'),
-        unknown: () => eq(unknown, 'unknown'),
-    },
-    tag1: {
-        array: {
-            primitive: () => eq(array(number), 'readonly(number)[]'),
-            nested: () => eq(array(array(boolean)), 'readonly(readonly(boolean)[])[]'),
-            union: () => eq(array(or(number, string)), 'readonly(number|string)[]'),
-        },
-        record: {
-            primitive: () => eq(record(string), '{readonly[k in string]?:string}'),
-            nested: () => eq(record(record(number)), '{readonly[k in string]?:{readonly[k in string]?:number}}'),
-        },
-    },
-    const: {
-        null: () => eq(null, 'null'),
-        undefined: () => eq(undefined, 'undefined'),
-        true: () => eq(true, 'true'),
-        false: () => eq(false, 'false'),
-        number: () => eq(42, '42'),
-        nan: () => eq(NaN, 'number'),
-        inf: () => eq(Infinity, 'number'),
-        negInf: () => eq(-Infinity, 'number'),
-        string: () => eq('hello', '"hello"'),
-        bigint: () => eq(7n, '7n'),
-        emptyTuple: () => eq([], 'readonly[]'),
-        tuple: () => eq([12, true], 'readonly[12,true]'),
-        emptyStruct: () => eq({}, '{}'),
-        struct: () => eq({ a: number, b: string }, '{readonly"a":number,readonly"b":string}'),
-        nestedStruct: () => eq({ x: { y: boolean } }, '{readonly"x":{readonly"y":boolean}}'),
-        quotedKey: () => eq({ 'my-key': number }, '{readonly"my-key":number}'),
-        stringWithQuote: () => eq('say "hi"', '"say \\"hi\\""'),
-        keyWithQuote: () => eq({ 'a"b': number }, '{readonly"a\\"b":number}'),
-    },
-    constThunk: {
-        primitive: () => eq(() => ['const', 42n], '42n'),
-        string: () => eq(() => ['const', 'hi'], '"hi"'),
-    },
-    or: {
-        empty: () => eq(or(), 'never'),
-        consts: () => eq(or(false, 42, 'hello'), 'false|42|"hello"'),
-        thunks: () => eq(or(number, string), 'number|string'),
-        mixed: () => eq(or(42, string), '42|string'),
-    },
-    never: () => eq(never, 'never'),
-    option: () => eq(option(number), 'number|undefined'),
-    mut: {
-        array: () => eqMut(array(number), '(number)[]'),
-        nestedArray: () => eqMut(array(array(boolean)), '((boolean)[])[]'),
-        record: () => eqMut(record(string), '{[k in string]?:string}'),
-        tuple: () => eqMut([12, true], '[12,true]'),
-        struct: () => eqMut({ a: number, b: string }, '{"a":number,"b":string}'),
-    },
-};

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

@@ -1,4 +0,0 @@
-import { type Type } from '../module.f.ts';
-import { type Validate } from '../common/module.f.ts';
-export { constPrimitiveValidate, prependPath, primitive0Validate, verror, type Path, type Result, type Validate, type ValidationError, } from '../common/module.f.ts';
-export declare const validate: <T extends Type>(rtti: T) => Validate<T>;

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

@@ -1,74 +0,0 @@
-import {} from '../module.f.js';
-import { ok } from '../../result/module.f.js';
-import { constPrimitiveValidate, eachEntry, isArray, isObject, orVisit, primitive0Validate, verror, visit, } from '../common/module.f.js';
-export { constPrimitiveValidate, prependPath, primitive0Validate, verror, } from '../common/module.f.js';
-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 = (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 : 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 = (isContainer, getItem) => (rtti) => value => {
-    if (!isContainer(value)) {
-        return verror('unexpected value');
-    }
-    const r = eachEntry(Object.entries(rtti), (k, v) => 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 : ok(value);
-};
-const tupleValidate = constContainerValidate(isArray, (value, k) => value[Number(k)]);
-const structValidate = constContainerValidate(isObject, (value, k) => value[k]);
-const orValidate = (rtti) => orVisit(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
- * ```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' }]
- * ```
- */
-const validateVisitor = {
-    tuple: tupleValidate,
-    struct: structValidate,
-    array: arrayValidate,
-    record: recordValidate,
-    or: orValidate,
-    constPrimitive: constPrimitiveValidate,
-    primitive0: primitive0Validate,
-    unknown: () => ok,
-};
-export const validate = (rtti) => visit(validateVisitor)(rtti);

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

@@ -1,118 +0,0 @@
-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;
-};