functionalscript 0.44.0 → 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

@@ -1,11 +1,18 @@
+/**
+ * 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';
-/** @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 */
@@ -53,7 +60,7 @@ export declare const record: _MakeType1<'record'>;
  * `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`.
+ * — see `./data/README.md`.
  *
  * @template {readonly Type[]} T
  * @param {T} types

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

@@ -3,12 +3,14 @@
  * 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'
-/** @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'])
 
@@ -84,7 +86,7 @@ export const record = type1('record')
  * `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`.
+ * — see `./data/README.md`.
  *
  * @template {readonly Type[]} T
  * @param {T} types

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

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

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

@@ -27,12 +27,17 @@
  * 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 { Info1, Struct, Tag1, Tuple, Type } from '../types.ts' */
-/** @import { Result as CommonResult } from '../../result/types.ts' */
+
 import { ok } from '../../result/module.f.mjs'
-/** @import { StringMap } from '../../object/types.ts' */
-/** @import { List } from '../../list/types.ts' */
 import { reverse, toArray } from '../../list/module.f.mjs'
 import {
     constPrimitiveValidate,
@@ -44,9 +49,6 @@ import {
     verror,
     visit,
 } from '../common/module.f.mjs'
-/** @import { Container, IsContainer, ValidateE, ValidationError, Visitor } from '../common/types.ts' */
-/** @import { Unknown } from '../ts/types.ts' */
-/** @import { Parse } from './types.ts' */
 
 const { entries } = Object
 

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

@@ -8,7 +8,11 @@
 
 import { parse } from './module.f.mjs'
 import { boolean, number, string, bigint, unknown, array, record, or, option } from '../module.f.mjs'
-import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import {
+    assert,
+    assertEq,
+    assertStructurallySame,
+} from '../../../asserts/module.f.mjs'
 
 /** @type {(r: readonly [string, unknown]) => void} */
 const assertOk = ([k]) => { assertEq(k, 'ok', 'expected ok') }
@@ -31,33 +35,9 @@ const assertErrorPath = expected =>
     r => {
         assert(r[0] === 'error', 'expected error')
         const e = /** @type {ValidationError} */ (r[1])
-        if (e.path.length !== expected.length) { throw `path length ${e.path.length} != ${expected.length}` }
-        for (let i = 0; i < expected.length; i++) {
-            if (e.path[i] !== expected[i]) { throw `path[${i}] ${e.path[i]} != ${expected[i]}` }
-        }
+        assertStructurallySame(e.path, expected, 'unexpected error path')
     }
 
-/** @type {(a: unknown, b: unknown) => void} */
-const assertDeepEqual = (a, b) => {
-    if (a === b) { return }
-    if (a instanceof Array && b instanceof Array) {
-        if (a.length !== b.length) { throw `array length ${a.length} != ${b.length}` }
-        for (let i = 0; i < a.length; i++) { assertDeepEqual(a[i], b[i]) }
-        return
-    }
-    if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
-        const ka = Object.keys(a).sort()
-        const kb = Object.keys(b).sort()
-        if (ka.length !== kb.length) { throw `key count ${ka.length} != ${kb.length}` }
-        for (let i = 0; i < ka.length; i++) {
-            if (ka[i] !== kb[i]) { throw `key ${ka[i]} != ${kb[i]}` }
-            assertDeepEqual((/** @type {any} */ (a))[ka[i]], (/** @type {any} */ (b))[kb[i]])
-        }
-        return
-    }
-    throw `not deep-equal: ${String(a)} vs ${String(b)}`
-}
-
 export const proof = {
     boolean: {
         ok: () => {
@@ -173,12 +153,12 @@ export const proof = {
             ok: () => {
                 const t = /** @type {const} */ ([42, 'hello'])
                 const r = parse(t)([42, 'hello'])
-                assertDeepEqual(unwrap(r), [42, 'hello'])
+                assertStructurallySame(unwrap(r), [42, 'hello'])
             },
             // The key behavior change vs `validate`: extra tuple elements are dropped.
             extraItemsDropped: () => {
                 const r = parse(/** @type {const} */ ([42]))([42, 'extra'])
-                assertDeepEqual(unwrap(r), [42])
+                assertStructurallySame(unwrap(r), [42])
             },
             error: () => {
                 assertError(parse(/** @type {const} */ ([42]))([99]))
@@ -189,12 +169,12 @@ export const proof = {
             ok: () => {
                 const t = /** @type {const} */ ({ a: 42, b: 'hello' })
                 const r = parse(t)({ a: 42, b: 'hello' })
-                assertDeepEqual(unwrap(r), { a: 42, b: 'hello' })
+                assertStructurallySame(unwrap(r), { a: 42, b: 'hello' })
             },
             // Undeclared properties are dropped from the constructed value.
             extraKeysDropped: () => {
                 const r = parse(/** @type {const} */ ({ a: /** @type {const} */ (42) }))({ a: 42, b: 'extra' })
-                assertDeepEqual(unwrap(r), { a: 42 })
+                assertStructurallySame(unwrap(r), { a: 42 })
             },
             error: () => {
                 assertError(parse(/** @type {const} */ ({ a: 42 }))({ a: 99 }))
@@ -205,11 +185,11 @@ export const proof = {
     array: {
         empty: () => {
             const r = parse(array(number))([])
-            assertDeepEqual(unwrap(r), [])
+            assertStructurallySame(unwrap(r), [])
         },
         ok: () => {
             const r = parse(array(number))([1, 2, 3])
-            assertDeepEqual(unwrap(r), [1, 2, 3])
+            assertStructurallySame(unwrap(r), [1, 2, 3])
         },
         // `parse` always constructs a new array, even when the inner type is a primitive.
         freshArray: () => {
@@ -217,7 +197,7 @@ export const proof = {
             /** @type {readonly number[]} */
             const out = unwrap(parse(array(number))(input))
             assert(out !== /** @type {unknown} */ (input), 'expected a fresh array')
-            assertDeepEqual(out, [1, 2, 3])
+            assertStructurallySame(out, [1, 2, 3])
         },
         error: () => {
             assertError(parse(array(number))([1, 'two', 3]))
@@ -226,18 +206,18 @@ export const proof = {
         },
         nested: () => {
             const r = parse(array(array(boolean)))([[true, false], [false]])
-            assertDeepEqual(unwrap(r), [[true, false], [false]])
+            assertStructurallySame(unwrap(r), [[true, false], [false]])
             assertError(parse(array(array(boolean)))([[true, 42]]))
         },
     },
     record: {
         empty: () => {
             const r = parse(record(number))({})
-            assertDeepEqual(unwrap(r), {})
+            assertStructurallySame(unwrap(r), {})
         },
         ok: () => {
             const r = parse(record(string))({ a: 'hello', b: 'world' })
-            assertDeepEqual(unwrap(r), { a: 'hello', b: 'world' })
+            assertStructurallySame(unwrap(r), { a: 'hello', b: 'world' })
         },
         // `parse` always constructs a new record.
         freshRecord: () => {
@@ -245,7 +225,7 @@ export const proof = {
             /** @type {Record<string, number>} */
             const out = unwrap(parse(record(number))(input))
             assert(out !== /** @type {unknown} */ (input), 'expected a fresh record')
-            assertDeepEqual(out, { a: 1, b: 2 })
+            assertStructurallySame(out, { a: 1, b: 2 })
         },
         error: () => {
             assertError(parse(record(number))({ a: 1, b: 'two' }))
@@ -294,7 +274,7 @@ export const proof = {
             /** @type {readonly number[]} */
             const out = unwrap(parse(t)([1, 2, 3]))
             // The const tuple `[number]` matches first and returns a length-1 result.
-            assertDeepEqual(out, [1])
+            assertStructurallySame(out, [1])
         },
     },
     option: {

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

@@ -1,4 +1,6 @@
-/** @import { StringMap } from '../object/types.ts' */
+/**
+ * @import { StringMap } from '../object/types.ts'
+ */
 import type { StringMap } from '../object/types.ts';
 export type _Tests = StringMap<readonly unknown[]>;
 export declare const proof: {

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

@@ -1,4 +1,6 @@
-/** @import { StringMap } from '../object/types.ts' */
+/**
+ * @import { StringMap } from '../object/types.ts'
+ */
 
 /** @typedef {StringMap<readonly unknown[]>} _Tests */
 

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

@@ -1,16 +1,72 @@
+/**
+ * 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 type { Printer } from '../../ts/types.ts';
 import type { Type } from '../types.ts';
-/** @import { Const, Type } from '../types.ts' */
+import type { Data, RuleSet } from '../data/types.ts';
+export type _Ctx = {
+    readonly ts: Printer;
+    readonly ids: readonly (readonly [string, string])[];
+    readonly rules: RuleSet;
+};
+/**
+ * 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 declare const dataToTs: (mut?: true) => (data: Data) => readonly [readonly (readonly [string, string])[], string];
 /**
- * Creates a printer that converts an RTTI schema `Type` to its TypeScript type expression as a string.
+ * 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.
- * Pass `true` to emit mutable (non-`readonly`) types.
+ * 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.
  *
- * **Note:** recursive schemas (e.g. `const list = () => ['array', list] as const`)
- * will cause infinite recursion. Only acyclic schemas are supported.
+ * 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`.
+ * **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
@@ -18,12 +74,15 @@ import type { Type } from '../types.ts';
  * 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}'