functionalscript 0.44.0 → 0.45.0

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

@@ -2,22 +2,268 @@
  * Runtime printer mirroring the `Ts<T>` type transformer for RTTI schemas.
  * See `./types.ts` for `Ts<T>` and the `*Ts` transformer types.
  *
+ * The printer routes through the serializable RTTI data form
+ * (`fjs/types/rtti/data`): `thunk RTTI → toData → dataToTs`. The data form
+ * is a finite graph, so recursive schemas — which the thunk graph represents
+ * as self-referencing functions with no leaves — terminate: every named rule
+ * becomes a TypeScript type-alias definition and every graph edge prints as
+ * that alias's identifier. Output is canonical: union members follow the
+ * data form's kind order and object keys its sorted order, so structurally
+ * different but equivalent schemas print identically.
+ *
  * @module
+ *
+ * @import { Printer, StructField } from '../../ts/types.ts'
+ * @import { Type } from '../types.ts'
+ * @import { ArraySet, Data, KindSet, Node, ObjectSet, RuleSet, UnionSet } from '../data/types.ts'
  */
+
+import { assertNotNullish } from '../../../asserts/module.f.mjs'
+import { at, definedEntries } from '../../object/module.f.mjs'
 import { primitive, union, printer as tsPrinter } from '../../ts/module.f.mjs'
-/** @import { Const, Type } from '../types.ts' */
+import { cmp, toData, unitBit, unknown as top } from '../data/module.f.mjs'
+
+const nullBit = unitBit(null)
+const undefinedBit = unitBit(undefined)
+const falseBit = unitBit(false)
+const trueBit = unitBit(true)
+const booleanBits = falseBit | trueBit
 
 /**
- * Creates a printer that converts an RTTI schema `Type` to its TypeScript type expression as a string.
+ * Names that cannot name a TypeScript type alias: the predefined type
+ * names (`TS2457`), the ECMAScript reserved words — those reserved only in
+ * strict-mode code included, since every module is strict-mode code
+ * (`TS1214`) — and the type keywords that fail in the alias-name position.
+ */
+const reserved = /** @type {const} */ ([
+    // predefined type names
+    'any', 'bigint', 'boolean', 'false', 'never', 'null', 'number', 'object',
+    'string', 'symbol', 'true', 'undefined', 'unknown', 'void',
+    // ECMAScript reserved words
+    'await', 'break', 'case', 'catch', 'class', 'const', 'continue',
+    'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export',
+    'extends', 'finally', 'for', 'function', 'if', 'import', 'in',
+    'instanceof', 'new', 'return', 'super', 'switch', 'this', 'throw', 'try',
+    'typeof', 'var', 'while', 'with',
+    // reserved in strict-mode code — and every module is strict-mode code
+    'implements', 'interface', 'let', 'package', 'private', 'protected',
+    'public', 'static', 'yield',
+    // type-operator keywords, and `intrinsic` (TS2795 outside lib.d.ts)
+    'infer', 'intrinsic', 'keyof', 'readonly', 'unique',
+])
+
+/** @type {(c: string) => boolean} */
+const isIdStart = c => (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_' || c === '$'
+
+/** @type {(c: string) => boolean} */
+const isIdPart = c => isIdStart(c) || (c >= '0' && c <= '9')
+
+/** Whether `s` can name a TypeScript type alias. */
+/** @type {(s: string) => boolean} */
+const isTypeName = s =>
+    s !== ''
+    && [...s].every((c, i) => i === 0 ? isIdStart(c) : isIdPart(c))
+    && !reserved.some(p => p === s)
+
+/**
+ * Maps every rule name to a TypeScript type-alias identifier: the name
+ * itself when it can be one, else a deterministic generated `T<n>` that
+ * collides with no kept name.
  *
- * Mirrors the compile-time `Ts<T>` mapped type at runtime.
- * Pass `true` to emit mutable (non-`readonly`) types.
+ * @type {(rules: RuleSet) => readonly (readonly [string, string])[]}
+ */
+const identifiers = rules => {
+    const names = definedEntries(rules).map(([n]) => n)
+    const kept = names.filter(isTypeName)
+    /** @type {readonly (readonly [string, string])[]} */
+    let result = []
+    let i = 0
+    for (const name of names) {
+        if (isTypeName(name)) {
+            result = [...result, [name, name]]
+            continue
+        }
+        let id = `T${i}`
+        while (kept.some(k => k === id)) {
+            ++i
+            id = `T${i}`
+        }
+        ++i
+        result = [...result, [name, id]]
+    }
+    return result
+}
+
+/**
+ * @typedef {{
+ *  readonly ts: Printer
+ *  readonly ids: readonly (readonly [string, string])[]
+ *  readonly rules: RuleSet
+ * }} _Ctx
+ */
+
+/** @type {(ids: readonly (readonly [string, string])[], name: string) => string | undefined} */
+const idOf = (ids, name) => {
+    for (const [k, v] of ids) {
+        if (k === name) { return v }
+    }
+    return undefined
+}
+
+/**
+ * A reference prints as its definition's identifier; a reference naming a
+ * missing definition is malformed data and panics.
  *
- * **Note:** recursive schemas (e.g. `const list = () => ['array', list] as const`)
- * will cause infinite recursion. Only acyclic schemas are supported.
+ * @type {(ctx: _Ctx) => (n: Node) => string}
+ */
+const nodeToTs = ctx => n =>
+    typeof n === 'string'
+        ? assertNotNullish(idOf(ctx.ids, n), `missing definition: ${n}`)
+        : unionToTs(ctx)(n)
+
+/**
+ * The member expressions of one kind component: nothing when absent, the
+ * whole kind when `true`, one expression per member otherwise.
  *
- * **Note:** the `unknown` schema produces the string `'unknown'` (TypeScript's built-in),
- * whereas `Ts<>` maps it to `DjsUnknown` from `djs/module.f.ts`.
+ * @template T
+ * @param {KindSet<T> | undefined} k
+ * @param {string} whole
+ * @param {(v: T) => string} item
+ * @returns {readonly string[]}
+ */
+const kindToTs = (k, whole, item) =>
+    k === undefined ? [] :
+    k === true ? [whole] :
+    k.map(item)
+
+/** @type {(bits: number) => readonly string[]} */
+const unitToTs = bits => [
+    ...((bits & nullBit) === 0 ? [] : [primitive(null)]),
+    ...((bits & undefinedBit) === 0 ? [] : [primitive(undefined)]),
+    ...((bits & booleanBits) === booleanBits ? ['boolean']
+        : (bits & falseBit) !== 0 ? [primitive(false)]
+        : (bits & trueBit) !== 0 ? [primitive(true)]
+        : []),
+]
+
+/**
+ * A tuple prints its prefix, an array its element type, and a
+ * tuple-with-rest combines them with a rest element:
+ * `readonly[A,...readonly(R)[]]`.
+ *
+ * @type {(ctx: _Ctx) => (p: ArraySet) => string}
+ */
+const arraySetToTs = ctx => p => {
+    const items = p.prefix.map(nodeToTs(ctx))
+    const { rest } = p
+    if (rest === undefined) { return ctx.ts.tuple(items) }
+    const restTs = ctx.ts.array(nodeToTs(ctx)(rest))
+    return items.length === 0 ? restTs : ctx.ts.tuple([...items, `...${restTs}`])
+}
+
+/**
+ * Whether the node's value set admits `undefined` — its unit bit, read
+ * through a reference (own-property only) if needed.
+ *
+ * @type {(ctx: _Ctx) => (n: Node) => boolean}
+ */
+const admitsUndefined = ctx => n => {
+    const u = typeof n === 'string' ? assertNotNullish(at(n)(ctx.rules)) : n
+    return ((u.unit ?? 0) & undefinedBit) !== 0
+}
+
+/** @type {(list: readonly string[]) => readonly string[]} */
+const dedup = list => list.filter((s, i) => list.indexOf(s) === i)
+
+/**
+ * A struct prints its fields — a key whose value set admits `undefined` may
+ * also be absent, so it prints optional, mirroring `Ts<>` — and a record
+ * prints its value type. A props-with-rest set combines them with an
+ * intersection; TypeScript requires an index signature to cover the
+ * declared keys too, so the index type widens to the union of the rest and
+ * the declared value types — the closest expressible supertype.
+ *
+ * @type {(ctx: _Ctx) => (p: ObjectSet) => string}
+ */
+const objectSetToTs = ctx => p => {
+    /** @type {readonly StructField[]} */
+    const fields = definedEntries(p.props).map(([k, v]) => {
+        const ts = nodeToTs(ctx)(v)
+        return admitsUndefined(ctx)(v) ? [k, ts, true] : [k, ts]
+    })
+    const { rest } = p
+    if (rest === undefined) { return ctx.ts.struct(fields) }
+    const restTs = ctx.ts.record(union(dedup([...fields.map(([, v]) => v), nodeToTs(ctx)(rest)])))
+    return fields.length === 0 ? restTs : `${ctx.ts.struct(fields)}&${restTs}`
+}
+
+/** @type {(u: UnionSet) => boolean} */
+const isTop = u => cmp([{}, u])([{}, top]) === 0
+
+/** @type {(ctx: _Ctx) => (u: UnionSet) => string} */
+const unionToTs = ctx => u => {
+    if (isTop(u)) { return 'unknown' }
+    return union([
+        ...unitToTs(u.unit ?? 0),
+        ...kindToTs(u.number, 'number', primitive),
+        ...kindToTs(u.string, 'string', primitive),
+        ...kindToTs(u.bigint, 'bigint', primitive),
+        ...kindToTs(u.array, ctx.ts.array('unknown'), arraySetToTs(ctx)),
+        ...kindToTs(u.object, ctx.ts.record('unknown'), objectSetToTs(ctx)),
+    ])
+}
+
+/**
+ * Renders a serializable RTTI {@link Data} (from `toData`) as TypeScript:
+ * the rule definitions as sorted `[identifier, expression]` pairs — render
+ * each as `type <identifier> = <expression>` — plus the entry expression,
+ * which references those identifiers. A schema with no reference cycles has
+ * no definitions and the entry expression stands alone.
+ *
+ * Rule names come from the data form; one that cannot name a type alias —
+ * not an identifier, a predefined type name, an ECMAScript reserved word,
+ * or a type-operator keyword — gets a deterministic generated identifier
+ * (`T0`, `T1`, …). A reference naming a missing definition panics.
+ *
+ * @example
+ * ```js
+ * const list = () => ['array', list]
+ * dataToTs()(toData(list))
+ * // [[['list', 'readonly(list)[]']], 'list']
+ * // i.e. `type list = readonly(list)[]` and the entry expression `list`
+ * ```
+ *
+ * @type {(mut?: true) => (data: Data) => readonly [readonly (readonly [string, string])[], string]}
+ */
+export const dataToTs = mut => ([rules, entry]) => {
+    /** @type {_Ctx} */
+    const ctx = { ts: tsPrinter(mut), ids: identifiers(rules), rules }
+    return [
+        definedEntries(rules).map(([n, u]) =>
+            /** @type {const} */ ([nodeToTs(ctx)(n), unionToTs(ctx)(u)])),
+        nodeToTs(ctx)(entry),
+    ]
+}
+
+/**
+ * Creates a printer that converts an RTTI schema `Type` to its TypeScript
+ * type expression as a string, through the canonical data form: `toData`
+ * first, then {@link dataToTs}.
+ *
+ * Mirrors the compile-time `Ts<T>` mapped type at runtime, in the data
+ * form's canonical order — union members follow its kind order (e.g.
+ * `option(number)` prints `'undefined|number'`) and structurally different
+ * but equivalent schemas print identically (`or(true, false)` prints
+ * `'boolean'`). Pass `true` to emit mutable (non-`readonly`) types.
+ *
+ * A recursive schema prints as the identifier of its definition — use
+ * {@link dataToTs} to also obtain the `type <identifier> = <expression>`
+ * definitions the expression references; a schema with no reference cycles
+ * needs none.
+ *
+ * **Note:** the `unknown` schema produces the string `'unknown'`
+ * (TypeScript's built-in), whereas `Ts<>` maps it to `DjsUnknown` from
+ * `djs/module.f.ts`.
  *
  * @example
  * ```js
@@ -25,12 +271,15 @@ import { primitive, union, printer as tsPrinter } from '../../ts/module.f.mjs'
  * toTs(boolean)                    // 'boolean'
  * toTs(array(number))              // 'readonly(number)[]'
  * toTs(record(string))             // '{readonly[k in string]?:string}'
- * toTs(or(string, number))         // 'string|number'
+ * toTs(or(string, number))         // 'number|string'
  * toTs(42)                         // '42'
  * toTs('hello')                    // '"hello"'
  * toTs([boolean, number])          // 'readonly[boolean,number]'
  * toTs({ x: string })              // '{readonly"x":string}'
  *
+ * const list = () => ['array', list]
+ * toTs(list)                       // 'list' — see `dataToTs` for the definition
+ *
  * const toTsMut = printer(true)
  * toTsMut(array(number))           // '(number)[]'
  * toTsMut(record(string))          // '{[k in string]?:string}'
@@ -39,26 +288,9 @@ import { primitive, union, printer as tsPrinter } from '../../ts/module.f.mjs'
  * @type {(mut?: true) => (rtti: Type) => string}
  */
 export const printer = mut => {
-    const { tuple, struct, array, record } = tsPrinter(mut)
-
-    /** @type {(rtti: Const) => string} */
-    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)]))
-
-    /** @type {(rtti: Type) => string} */
-    const toTs = rtti => {
-        if (typeof rtti !== 'function') { return constToTs(rtti) }
-        const [tag, ...rest] = rtti()
-        switch (tag) {
-            case 'const': return constToTs(/** @type {Const} */ (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'
-        }
+    const toTs = dataToTs(mut)
+    return rtti => {
+        const [, entry] = toTs(toData(rtti))
+        return entry
     }
-
-    return toTs
 }

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

@@ -1,3 +1,15 @@
+/**
+ * @import { Type } from '../types.ts'
+ * @import { Data } from '../data/types.ts'
+ */
+import { number, string } from '../module.f.mjs';
+export type _List = () => readonly ['array', _List];
+export type _Tree = () => readonly ['or', typeof number, _Forest];
+export type _Forest = () => readonly ['array', _Tree];
+export type _Lock = () => readonly ['record', () => readonly ['or', typeof string, _Lock]];
+export type _StringNamed = () => readonly ['array', _StringNamed];
+export type _T0Named = () => readonly ['array', _T0Named];
+export type _IfNamed = () => readonly ['array', _IfNamed];
 export declare const proof: {
     tag0: {
         boolean: () => void;
@@ -49,6 +61,35 @@ export declare const proof: {
     };
     never: () => void;
     option: () => void;
+    normalization: {
+        booleanFromConsts: () => void;
+        literalAbsorbed: () => void;
+        sortedLiterals: () => void;
+        sortedBigints: () => void;
+        canonicalIdentity: () => void;
+        optionalProp: () => void;
+        mixedProps: () => void;
+    };
+    recursion: {
+        selfList: () => void;
+        mutual: () => void;
+        recursiveUnion: () => void;
+        mutable: () => void;
+    };
+    identifiers: {
+        emptyName: () => void;
+        predefinedName: () => void;
+        reservedName: () => void;
+        typeOperatorName: () => void;
+        strictModeReservedName: () => void;
+        generatedCollision: () => void;
+    };
+    data: {
+        tupleWithRest: () => void;
+        structWithRest: () => void;
+        optionalByReference: () => void;
+        wholeKinds: () => void;
+    };
     mut: {
         array: () => void;
         nestedArray: () => void;
@@ -56,4 +97,7 @@ export declare const proof: {
         tuple: () => void;
         struct: () => void;
     };
+    throw: {
+        missingDefinition: () => readonly [readonly (readonly [string, string])[], string];
+    };
 };

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

@@ -1,20 +1,71 @@
-import { printer } from './module.f.mjs'
+/**
+ * @import { Type } from '../types.ts'
+ * @import { Data } from '../data/types.ts'
+ */
+
+import { assertEq } from '../../../asserts/module.f.mjs'
+import { toData, unitBit } from '../data/module.f.mjs'
 import { boolean, number, string, bigint, unknown, array, record, or, option, never } from '../module.f.mjs'
-/** @import { Type } from '../types.ts' */
+import { dataToTs, printer } from './module.f.mjs'
 
 const toTs = printer()
 const toTsMut = printer(true)
+
 /** @type {(rtti: Type, expected: string) => void} */
 const eqMut = (rtti, expected) => {
     const result = toTsMut(rtti)
     if (result !== expected) { throw `expected ${JSON.stringify(expected)}, got ${JSON.stringify(result)}` }
 }
+
 /** @type {(rtti: Type, expected: string) => void} */
 const eq = (rtti, expected) => {
     const result = toTs(rtti)
     if (result !== expected) { throw `expected ${JSON.stringify(expected)}, got ${JSON.stringify(result)}` }
 }
 
+/** @type {(data: Data, expected: unknown) => void} */
+const eqData = (data, expected) => {
+    const result = JSON.stringify(dataToTs()(data))
+    const exp = JSON.stringify(expected)
+    assertEq(result, exp, [result, exp])
+}
+
+/** A recursive list: `type list = readonly list[]`. */
+/** @typedef {() => readonly ['array', _List]} _List */
+/** @type {_List} */
+const list = () => ['array', list]
+
+/** Mutual recursion through a container. */
+/** @typedef {() => readonly ['or', typeof number, _Forest]} _Tree */
+/** @typedef {() => readonly ['array', _Tree]} _Forest */
+/** @type {_Tree} */
+const tree = () => ['or', number, forest]
+/** @type {_Forest} */
+const forest = () => ['array', tree]
+
+/** A cycle closing through an anonymous `or` thunk — an empty rule name. */
+/** @typedef {() => readonly ['record', () => readonly ['or', typeof string, _Lock]]} _Lock */
+/** @type {_Lock} */
+const lock = () => ['record', or(string, lock)]
+
+/** A recursive rule whose function name is the predefined type name `string`. */
+/** @typedef {() => readonly ['array', _StringNamed]} _StringNamed */
+/** @type {{ readonly string: _StringNamed }} */
+const stringNamedHolder = { string: () => ['array', stringNamedHolder.string] }
+const stringNamed = stringNamedHolder.string
+
+/** A recursive rule whose function name is `T0` — the first generated identifier. */
+/** @typedef {() => readonly ['array', _T0Named]} _T0Named */
+/** @type {{ readonly T0: _T0Named }} */
+const t0NamedHolder = { T0: () => ['array', t0NamedHolder.T0] }
+const t0Named = t0NamedHolder.T0
+
+/** A recursive rule whose function name is the reserved word `if`. */
+/** @typedef {() => readonly ['array', _IfNamed]} _IfNamed */
+/** @type {{ readonly if: _IfNamed }} */
+const ifNamedHolder = { if: () => ['array', ifNamedHolder.if] }
+const ifNamed = ifNamedHolder.if
+
 export const proof = {
     tag0: {
         boolean: () => eq(boolean, 'boolean'),
@@ -47,7 +98,8 @@ export const proof = {
         bigint: () => eq(7n, '7n'),
         emptyTuple: () => eq([], 'readonly[]'),
         tuple: () => eq([12, true], 'readonly[12,true]'),
-        emptyStruct: () => eq({}, '{}'),
+        // an unconstrained struct is the whole object kind
+        emptyStruct: () => eq({}, '{readonly[k in string]?:unknown}'),
         struct: () => eq(
             { a: number, b: string },
             '{readonly"a":number,readonly"b":string}',
@@ -77,7 +129,99 @@ export const proof = {
         mixed: () => eq(or(42, string), '42|string'),
     },
     never: () => eq(never, 'never'),
-    option: () => eq(option(number), 'number|undefined'),
+    // union members follow the canonical kind order, `undefined` first
+    option: () => eq(option(number), 'undefined|number'),
+    normalization: {
+        booleanFromConsts: () => eq(or(true, false), 'boolean'),
+        literalAbsorbed: () => eq(or(42, number), 'number'),
+        sortedLiterals: () => eq(or(2, 1), '1|2'),
+        sortedBigints: () => eq(or(2n, 1n), '1n|2n'),
+        canonicalIdentity: () => {
+            assertEq(toTs(or(string, number)), toTs(or(number, string)))
+        },
+        // a key admitting `undefined` may be absent — it prints optional
+        optionalProp: () => eq({ x: option(string) }, '{readonly"x"?:undefined|string}'),
+        mixedProps: () => eq(
+            { a: number, b: option(number) },
+            '{readonly"a":number,readonly"b"?:undefined|number}'),
+    },
+    recursion: {
+        selfList: () => {
+            eq(list, 'list')
+            eqData(toData(list), [[['list', 'readonly(list)[]']], 'list'])
+        },
+        mutual: () => {
+            eqData(toData(tree), [[['tree', 'number|readonly(tree)[]']], 'tree'])
+            eqData(toData(forest), [[['tree', 'number|readonly(tree)[]']], 'readonly(tree)[]'])
+        },
+        recursiveUnion: () => {
+            eqData(toData(or(number, list)), [[['list', 'readonly(list)[]']], 'number|readonly(list)[]'])
+        },
+        mutable: () => {
+            const [defs, entry] = dataToTs(true)(toData(list))
+            assertEq(JSON.stringify([defs, entry]), JSON.stringify([[['list', '(list)[]']], 'list']))
+        },
+    },
+    identifiers: {
+        // the empty rule name is not an identifier — generated `T0`
+        emptyName: () => {
+            eqData(toData(lock), [
+                [['T0', 'string|{readonly[k in string]?:T0}']],
+                '{readonly[k in string]?:T0}',
+            ])
+        },
+        // a predefined type name cannot name an alias — generated `T0`
+        predefinedName: () => {
+            eqData(toData(stringNamed), [[['T0', 'readonly(T0)[]']], 'T0'])
+        },
+        // reserved words cannot name an alias either — generated `T0`
+        reservedName: () => {
+            eqData(toData(ifNamed), [[['T0', 'readonly(T0)[]']], 'T0'])
+        },
+        typeOperatorName: () => {
+            eqData([{ infer: { array: [{ prefix: [], rest: 'infer' }] } }, 'infer'],
+                [[['T0', 'readonly(T0)[]']], 'T0'])
+        },
+        // reserved only in strict-mode code — but every module is strict
+        strictModeReservedName: () => {
+            eqData([{ let: { array: [{ prefix: [], rest: 'let' }] } }, 'let'],
+                [[['T0', 'readonly(T0)[]']], 'T0'])
+            eqData([{ intrinsic: { array: [{ prefix: [], rest: 'intrinsic' }] } }, 'intrinsic'],
+                [[['T0', 'readonly(T0)[]']], 'T0'])
+        },
+        // a generated identifier skips names already kept
+        generatedCollision: () => {
+            eqData(toData(/** @type {const} */ ([t0Named, lock])), [
+                [['T1', 'string|{readonly[k in string]?:T1}'], ['T0', 'readonly(T0)[]']],
+                'readonly[T0,{readonly[k in string]?:T1}]',
+            ])
+        },
+    },
+    data: {
+        tupleWithRest: () => {
+            eqData([{}, { array: [{ prefix: [{ number: true }], rest: { string: true } }] }],
+                [[], 'readonly[number,...readonly(string)[]]'])
+        },
+        structWithRest: () => {
+            // the index signature must cover the declared keys too, so the
+            // rest type widens to include the declared value types
+            eqData([{}, { object: [{ props: { a: { number: true } }, rest: { string: true } }] }],
+                [[], '{readonly"a":number}&{readonly[k in string]?:number|string}'])
+            eqData([{}, { object: [{ props: { a: { string: true } }, rest: { string: true } }] }],
+                [[], '{readonly"a":string}&{readonly[k in string]?:string}'])
+        },
+        optionalByReference: () => {
+            eqData([{ r: { unit: unitBit(null) | unitBit(undefined), number: true } },
+                { object: [{ props: { p: 'r' } }] }],
+                [[['r', 'null|undefined|number']], '{readonly"p"?:r}'])
+            eqData([{ r: { number: true } }, { object: [{ props: { p: 'r' } }] }],
+                [[['r', 'number']], '{readonly"p":r}'])
+        },
+        wholeKinds: () => {
+            eqData([{}, { array: true, object: true }],
+                [[], 'readonly(unknown)[]|{readonly[k in string]?:unknown}'])
+        },
+    },
     mut: {
         array: () => eqMut(array(number), '(number)[]'),
         nestedArray: () => eqMut(array(array(boolean)), '((boolean)[])[]'),
@@ -85,4 +229,8 @@ export const proof = {
         tuple: () => eqMut([12, true], '[12,true]'),
         struct: () => eqMut({ a: number, b: string }, '{"a":number,"b":string}'),
     },
+    throw: {
+        // a dangling reference is malformed data
+        missingDefinition: () => dataToTs()([{}, 'nope']),
+    },
 }

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

@@ -1,3 +1,14 @@
+/**
+ * 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';

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

@@ -1,3 +1,43 @@
+/**
+ * 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. */

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

@@ -1,6 +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';
-/** @import { Container, IsContainer, Validate, ValidateE, Visitor } 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>;