functionalscript 0.44.0 → 0.46.0

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

@@ -5,21 +5,25 @@
  *
  * @example
  *
- * ```ts
- * import { error, ok, unwrap, type Result } from './module.f.ts'
+ * ```js
+ * import { error, ok, okThen, unwrap } from './module.f.mjs'
  *
- * const success: Result<number, string> = ok(42)
- * const failure: Result<number, string> = error('Something went wrong')
+ * const success = ok(42)
+ * const failure = error('Something went wrong')
  *
  * if (unwrap(success) !== 42) { throw 'error' }
  * const [kind, v] = failure
  * if (kind !== 'error') { throw 'error' }
- * // `v` is inferred as `string` here
- * if (v !== 'Something went wrong') { throw 'error' }
+ * // `v` is `'Something went wrong'` here
+ *
+ * // `okThen` chains; an `error` skips the rest of the chain unchanged.
+ * const half = n => n % 2 === 0 ? ok(n / 2) : error('odd')
+ * if (unwrap(okThen(half)(success)) !== 21) { throw 'error' }
  * ```
+ *
+ * @import { Ok, Error, Result } from './types.ts'
  */
 import type { Ok, Error, Result } from './types.ts';
-/** @import { Ok, Error, Result } from './types.ts' */
 /**
  * Creates a successful result.
  *
@@ -57,3 +61,29 @@ export declare const invert: <T, E>([k, v]: Result<T, E>) => Result<E, T>;
  * @type {<T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) => Result<R, E>}
  */
 export declare const mapOk: <T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) => Result<R, E>;
+/**
+ * Chains a `Result`-returning step onto a `Result`, passing an `error` through
+ * unchanged. The monadic bind to {@link mapOk}'s functor map, and the pure
+ * sibling of the branch `fjs/effects`'s `step` writes for an effect that
+ * also performs operations.
+ *
+ * The two error types are **unioned, not unified**. A validation chain
+ * typically widens its error as it goes — a JSON parse failure (`string`)
+ * followed by an rtti schema failure (`ValidationError`) — and the hand-written
+ * form expressed that by rebuilding the incoming error with `error(v)` purely
+ * to retag it into the wider type. `E | F` states the widening in the type
+ * instead, so neither side has to be pre-widened and the passed-through
+ * `error` stays the very tuple it arrived as.
+ *
+ * `F` binds on the second arrow, as in {@link mapOk}: `f` alone determines the
+ * value types, so one `okThen(f)` applies to results carrying any error type.
+ *
+ * Reach for it when the step needs **only** the value it is handed. A chain
+ * whose later steps also read an earlier one's value would have to nest a
+ * closure per link to keep those values in scope, which `fjs/AGENTS.md` §3.4 rules
+ * out for the same reason it rules out nested `step`; write those as a flat
+ * sequence of guards.
+ *
+ * @type {<T, R, E>(f: (value: T) => Result<R, E>) => <F>(r: Result<T, F>) => Result<R, E | F>}
+ */
+export declare const okThen: <T, R, E>(f: (value: T) => Result<R, E>) => <F>(r: Result<T, F>) => Result<R, E | F>;

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

@@ -5,22 +5,25 @@
  *
  * @example
  *
- * ```ts
- * import { error, ok, unwrap, type Result } from './module.f.ts'
+ * ```js
+ * import { error, ok, okThen, unwrap } from './module.f.mjs'
  *
- * const success: Result<number, string> = ok(42)
- * const failure: Result<number, string> = error('Something went wrong')
+ * const success = ok(42)
+ * const failure = error('Something went wrong')
  *
  * if (unwrap(success) !== 42) { throw 'error' }
  * const [kind, v] = failure
  * if (kind !== 'error') { throw 'error' }
- * // `v` is inferred as `string` here
- * if (v !== 'Something went wrong') { throw 'error' }
+ * // `v` is `'Something went wrong'` here
+ *
+ * // `okThen` chains; an `error` skips the rest of the chain unchanged.
+ * const half = n => n % 2 === 0 ? ok(n / 2) : error('odd')
+ * if (unwrap(okThen(half)(success)) !== 21) { throw 'error' }
  * ```
+ *
+ * @import { Ok, Error, Result } from './types.ts'
  */
 
-/** @import { Ok, Error, Result } from './types.ts' */
-
 /**
  * Creates a successful result.
  *
@@ -65,3 +68,30 @@ export const invert = ([k, v]) => k === 'ok' ? error(v) : ok(v)
  * @type {<T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) => Result<R, E>}
  */
 export const mapOk = f => r => r[0] === 'ok' ? ok(f(r[1])) : r
+
+/**
+ * Chains a `Result`-returning step onto a `Result`, passing an `error` through
+ * unchanged. The monadic bind to {@link mapOk}'s functor map, and the pure
+ * sibling of the branch `fjs/effects`'s `step` writes for an effect that
+ * also performs operations.
+ *
+ * The two error types are **unioned, not unified**. A validation chain
+ * typically widens its error as it goes — a JSON parse failure (`string`)
+ * followed by an rtti schema failure (`ValidationError`) — and the hand-written
+ * form expressed that by rebuilding the incoming error with `error(v)` purely
+ * to retag it into the wider type. `E | F` states the widening in the type
+ * instead, so neither side has to be pre-widened and the passed-through
+ * `error` stays the very tuple it arrived as.
+ *
+ * `F` binds on the second arrow, as in {@link mapOk}: `f` alone determines the
+ * value types, so one `okThen(f)` applies to results carrying any error type.
+ *
+ * Reach for it when the step needs **only** the value it is handed. A chain
+ * whose later steps also read an earlier one's value would have to nest a
+ * closure per link to keep those values in scope, which `fjs/AGENTS.md` §3.4 rules
+ * out for the same reason it rules out nested `step`; write those as a flat
+ * sequence of guards.
+ *
+ * @type {<T, R, E>(f: (value: T) => Result<R, E>) => <F>(r: Result<T, F>) => Result<R, E | F>}
+ */
+export const okThen = f => r => r[0] === 'error' ? r : f(r[1])

package/fjs/types/result/module.mjs

@@ -1,4 +1,12 @@
-/** @import { Result } from './types.ts' */
+/**
+ * Impure `Result` companions: capture thrown exceptions as `Result` values,
+ * since `try`/`catch` is not allowed in FunctionalScript itself.
+ *
+ * @module
+ *
+ * @import { Result } from './types.ts'
+ */
+
 import { ok, error } from './module.f.mjs'
 
 /** @type {<T>(f: () => T) => Result<T, unknown>} */

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

@@ -1,10 +1,15 @@
+/**
+ * @import { Result } from './types.ts'
+ */
 declare const example: () => void;
 declare const invertTest: () => void;
 declare const mapOkTest: () => void;
+declare const okThenTest: () => void;
 export declare const proof: {
     example: typeof example;
     invertTest: typeof invertTest;
     mapOkTest: typeof mapOkTest;
+    okThenTest: typeof okThenTest;
     throw: {
         unwrapError: () => string;
     };

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

@@ -1,5 +1,8 @@
-import { error, ok, unwrap, invert, mapOk } from './module.f.mjs'
-/** @import { Result } from './types.ts' */
+/**
+ * @import { Result } from './types.ts'
+ */
+
+import { error, ok, unwrap, invert, mapOk, okThen } from './module.f.mjs'
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 
 const example = () => {
@@ -31,10 +34,27 @@ const mapOkTest = () => {
     assert(!(k1 !== 'error' || v1 !== 'oops'), [k1, v1])
 }
 
+const okThenTest = () => {
+    /** @type {(n: number) => Result<string, string>} */
+    const half = n => n % 2 === 0 ? ok(`${n / 2}`) : error('odd')
+    const [k0, v0] = okThen(half)(ok(42))
+    assert(!(k0 !== 'ok' || v0 !== '21'), [k0, v0])
+    // `f` itself failing: the chain reports `f`'s own error.
+    const [k1, v1] = okThen(half)(ok(41))
+    assert(!(k1 !== 'error' || v1 !== 'odd'), [k1, v1])
+    // An incoming `error` skips `f` and passes through unchanged, keeping its
+    // own error type: the result is `Result<string, string | number>`.
+    /** @type {Result<number, number>} */
+    const incoming = error(7)
+    const [k2, v2] = okThen(half)(incoming)
+    assert(!(k2 !== 'error' || v2 !== 7), [k2, v2])
+}
+
 export const proof = {
     example,
     invertTest,
     mapOkTest,
+    okThenTest,
     throw: {
         unwrapError: () => unwrap(error('oops')),
     },

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

@@ -1,10 +1,42 @@
+/**
+ * Shared kernel for RTTI consumers.
+ *
+ * `parse` (`../parse/module.f.mjs`) is the schema-form consumer; the data form
+ * (`../data/module.f.mjs`) is the other, walking a `Data` instead of a thunk
+ * graph. They produce the same `Result<T, ValidationError>` outcome and differ
+ * in how they dispatch, so 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, which `parse` reuses
+ *   (`Parse<T> = Validate<T>`).
+ * - `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. `parse` composes its top-level function from
+ *   a visitor.
+ * - `eachEntry`: the container entry loop (array/record/tuple/struct). Callers
+ *   choose what (if anything) to accumulate, so a caller that only needs
+ *   pass/fail pays no allocation per entry.
+ * - `orVisit`: the shared `or` handler — try each variant's recursive walker,
+ *   return the first match.
+ *
+ * Keeping the kernel here gives schema-driven consumers a stable shared base
+ * that does not depend on any one of them.
+ *
+ * @module
+ *
+ * @import { Primitive, Unknown } from '../ts/types.ts'
+ * @import { Const, Info0, Primitive0, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Error, Result as CommonResult } from '../../result/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { Validate, Visitor, IsContainer, Container, ResultE, ValidateE, ValidationError } from './types.ts'
+ */
 import type { Primitive, Unknown } from '../ts/types.ts';
 import type { Info0, Primitive0, Type } from '../types.ts';
 import type { Error, Result as CommonResult } from '../../result/types.ts';
 import type { StringMap } from '../../object/types.ts';
 import type { Validate, Visitor, IsContainer, ResultE, ValidateE, ValidationError } from './types.ts';
-/** @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 declare const verror: (message: string) => Error<ValidationError>;
@@ -34,10 +66,10 @@ export declare const constPrimitiveValidate: <T extends Primitive>(
  * @returns {Validate<T>}
  */
 rtti: T) => Validate<T>;
-/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+/** `IsContainer` guard for arrays. */
 /** @type {IsContainer<ReadonlyArray<Unknown>>} */
 export declare const isArray: IsContainer<ReadonlyArray<Unknown>>;
-/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+/** `IsContainer` guard for records/structs. */
 /** @type {IsContainer<StringMap<Unknown>>} */
 export declare const isObject: IsContainer<StringMap<Unknown>>;
 /**
@@ -46,21 +78,19 @@ export declare const isObject: IsContainer<StringMap<Unknown>>;
  * 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.
+ * Used by `parse`'s container builders (array/record/tuple/struct), which
+ * need the rebuilt `[key, value]` pairs, so they fold them into a `List` (see
+ * the call site) and convert to an array once at the end. A caller whose
+ * whole question is "did every entry succeed?" passes `undefined`/`acc => acc`
+ * instead and pays no allocation per entry.
  */
 export declare const eachEntry: <V, R, A>(entries: ReadonlyArray<readonly [string, V]>, item: (k: string, v: V) => CommonResult<R, ValidationError>, init: A, accumulate: (acc: A, k: string, value: R) => A) => CommonResult<A, ValidationError>;
 /**
  * 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`
+ * Shared `or` handler: try each variant against the value and return the
+ * first `'ok'` verbatim, parameterized by the recursive function that 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.

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

@@ -1,40 +1,42 @@
 /**
- * Shared kernel for RTTI consumers (`validate`, `parse`).
+ * Shared kernel for RTTI consumers.
  *
- * 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:
+ * `parse` (`../parse/module.f.mjs`) is the schema-form consumer; the data form
+ * (`../data/module.f.mjs`) is the other, walking a `Data` instead of a thunk
+ * graph. They produce the same `Result<T, ValidationError>` outcome and differ
+ * in how they dispatch, so 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.
+ * - The `Validate<T>`/`Result<T>` signatures, which `parse` reuses
+ *   (`Parse<T> = Validate<T>`).
  * - `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.
+ *   calls the matching handler. `parse` composes its top-level function from
+ *   a visitor.
+ * - `eachEntry`: the container entry loop (array/record/tuple/struct). Callers
+ *   choose what (if anything) to accumulate, so a caller that only needs
+ *   pass/fail pays no allocation per entry.
  * - `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.
+ * Keeping the kernel here gives schema-driven consumers a stable shared base
+ * that does not depend on any one of them.
  *
  * @module
+ *
+ * @import { Primitive, Unknown } from '../ts/types.ts'
+ * @import { Const, Info0, Primitive0, Tag1, Tuple, Type } from '../types.ts'
+ * @import { Error, Result as CommonResult } from '../../result/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { Validate, Visitor, IsContainer, Container, ResultE, ValidateE, ValidationError } from './types.ts'
  */
-/** @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 { assert } from '../../../asserts/module.f.mjs'
 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>} */
@@ -78,15 +80,15 @@ export const constPrimitiveValidate =
 /** @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))
+        ? (commonIsArray(c) ? v.tuple(c) : v.struct(c))
+        : v.constPrimitive(c)
 
-/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+/** `IsContainer` guard for arrays. */
 /** @type {IsContainer<ReadonlyArray<Unknown>>} */
 export const isArray =
     value => commonIsArray(value)
 
-/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+/** `IsContainer` guard for records/structs. */
 /** @type {IsContainer<StringMap<Unknown>>} */
 export const isObject =
     value => commonIsObject(value)
@@ -97,13 +99,11 @@ export const isObject =
  * 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.
+ * Used by `parse`'s container builders (array/record/tuple/struct), which
+ * need the rebuilt `[key, value]` pairs, so they fold them into a `List` (see
+ * the call site) and convert to an array once at the end. A caller whose
+ * whole question is "did every entry succeed?" passes `undefined`/`acc => acc`
+ * instead and pays no allocation per entry.
  */
 export const eachEntry =
     /**
@@ -131,9 +131,9 @@ export const eachEntry =
 /**
  * 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`
+ * Shared `or` handler: try each variant against the value and return the
+ * first `'ok'` verbatim, parameterized by the recursive function that 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.
@@ -171,13 +171,19 @@ export const visit =
         if (typeof rtti === 'function') {
             const [tag, ...value] = rtti()
             switch (tag) {
-                case 'const': return visitConst(v)(/** @type {Const} */ (value[0]))
+                case 'const': {
+                    const [c] = value
+                    // `Type` is `Const | Thunk`, and a `Thunk` is a function, so
+                    // this is exactly the check that defines `Const`.
+                    assert(typeof c !== 'function', c)
+                    return visitConst(v)(c)
+                }
                 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 v.primitive0(tag)
         }
         return visitConst(v)(rtti)
     }

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

@@ -1,3 +1,7 @@
+/**
+ * @import { Result } from '../../result/types.ts'
+ * @import { ValidationError } from './types.ts'
+ */
 export type _Entries = ReadonlyArray<readonly [string, number]>;
 export declare const proof: {
     empty: () => void;

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

@@ -1,7 +1,10 @@
+/**
+ * @import { Result } from '../../result/types.ts'
+ * @import { ValidationError } from './types.ts'
+ */
+
 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 */
@@ -16,12 +19,12 @@ const collect = (acc, k, v) => [...acc, [k, v]]
 
 export const proof = {
     empty: () => {
-        const r = eachEntry(/** @type {_Entries} */ ([]), item, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([], item, [], collect)
         assert(r[0] === 'ok')
         assertEq(r[1].length, 0)
     },
     allOk: () => {
-        const r = eachEntry([['a', 1], ['b', 2]], item, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([['a', 1], ['b', 2]], item, [], collect)
         assert(r[0] === 'ok')
         assertEq(r[1].length, 2)
         assertEq(r[1][0][0], 'a')
@@ -36,7 +39,7 @@ export const proof = {
         assertEq(r[1], undefined)
     },
     firstErrorWins: () => {
-        const r = eachEntry([['a', -1], ['b', -2]], item, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([['a', -1], ['b', -2]], item, [], collect)
         assert(r[0] === 'error')
         assertEq(r[1].message, 'negative at a')
     },
@@ -47,7 +50,7 @@ export const proof = {
             calls++
             return item(k, v)
         }
-        const r = eachEntry([['a', -1], ['b', -2], ['c', -3]], counting, /** @type {_Entries} */ ([]), collect)
+        const r = eachEntry([['a', -1], ['b', -2], ['c', -3]], counting, [], collect)
         assert(r[0] === 'error')
         assertEq(calls, 1)
     },
@@ -55,7 +58,7 @@ export const proof = {
         /** @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)
+        const r = eachEntry([['outer', -1]], nested, [], collect)
         assert(r[0] === 'error')
         assertEq(r[1].path.length, 2)
         assertEq(r[1].path[0], 'outer')

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

@@ -0,0 +1,134 @@
+/**
+ * The serializable RTTI data form and the {@link toData} conversion from the
+ * thunk form.
+ *
+ * A schema denotes a set of values. The data form partitions that set into
+ * six disjoint kinds — unit values (`null`, `undefined`, `false`, `true`),
+ * numbers, strings, bigints, arrays and objects — so that all schema algebra
+ * (union normalization, coverage collapse, {@link equal}, {@link subset},
+ * canonical ordering via {@link cmp}) reduces to kind-wise set operations.
+ * {@link toData} is the single bridge from the thunk form; {@link validate}
+ * is the data-driven counterpart of `../validate`. The form serializes as
+ * DJS — plain JSON when no `bigint` literals are involved. See `./README.md`
+ * for the design rationale and serialization notes, and `./types.ts` for the
+ * type-level API.
+ *
+ * @module
+ *
+ * @import { Const, ConstObject, Type } from '../types.ts'
+ * @import { Primitive, Unknown } from '../ts/types.ts'
+ * @import { ResultE } from '../common/types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { ArraySet, Data, KindSet, Node, ObjectSet, RuleSet, UnionSet } from './types.ts'
+ */
+import type { Const, Type } from '../types.ts';
+import type { Primitive, Unknown } from '../ts/types.ts';
+import type { ResultE } from '../common/types.ts';
+import type { StringMap } from '../../object/types.ts';
+import type { Data, Node, RuleSet, UnionSet } from './types.ts';
+/**
+ * The unit kind's enumeration: bit `1 << i` of a {@link UnionSet}'s `unit`
+ * bitset stands for `unitList[i]`.
+ */
+export declare const unitList: readonly ['null', 'undefined', 'false', 'true'];
+/**
+ * The `unit` bit of one unit value.
+ *
+ * @type {(v: null | undefined | boolean) => number}
+ */
+export declare const unitBit: (v: null | undefined | boolean) => number;
+/**
+ * The data form of the empty set — rtti `never`.
+ *
+ * @type {UnionSet}
+ */
+export declare const never: UnionSet;
+/**
+ * The data form of the set of all values — rtti `unknown`.
+ *
+ * @type {UnionSet}
+ */
+export declare const unknown: UnionSet;
+/**
+ * The union with the given unit bits removed — set subtraction restricted to
+ * the unit kind. Dropping `undefined` from an optional property's value set is
+ * the motivating case.
+ *
+ * The other five kinds are carried through untouched rather than copied field
+ * by field. That is not only shorter: a caller that enumerates `UnionSet`'s
+ * members to rebuild the node silently **drops** any kind added to the type
+ * later, whereas spreading cannot. Removing every unit bit removes the `unit`
+ * key entirely, since an empty kind is an absent property here, never a zero.
+ *
+ * @type {(bits: number) => (n: UnionSet) => UnionSet}
+ */
+export declare const withoutUnits: (bits: number) => (n: UnionSet) => UnionSet;
+/**
+ * Total order over the data form: negative, zero or positive, with zero
+ * exactly on structural identity. {@link toData} output is canonical, so two
+ * conversions of equivalent thunk schemas compare equal — this is what makes
+ * the data form comparable and sortable.
+ *
+ * @type {(a: Data) => (b: Data) => number}
+ */
+export declare const cmp: (a: Data) => (b: Data) => number;
+/**
+ * Structural equality of canonical forms: `equal(toData(a))(toData(b))`
+ * holds exactly when `a` and `b` normalize to the same data — e.g.
+ * `or(a, b)` and `or(b, a)` are equal. Recursive definitions compare by
+ * their rule names, which are derived from the defining functions' names.
+ *
+ * @type {(a: Data) => (b: Data) => boolean}
+ */
+export declare const equal: (a: Data) => (b: Data) => boolean;
+export type _Ctx = readonly [RuleSet, RuleSet];
+export type _Assumed = StringMap<StringMap<true>>;
+export type _Keyed = readonly [Node, string | undefined];
+/**
+ * Sound subset test: `true` means every value of `a` is a value of `b`.
+ * Kind-wise on unions, pattern-wise on arrays/objects, coinductive on
+ * reference cycles. Incomplete in the known-hard corners of semantic
+ * subtyping (see `./README.md`): it may answer `false` for an inclusion
+ * that only holds by distributing a union across positions, or one whose
+ * left side is a non-syntactic empty set — never `true` for a non-inclusion.
+ *
+ * @type {(a: Data) => (b: Data) => boolean}
+ */
+export declare const subset: (a: Data) => (b: Data) => boolean;
+export type _NodeMap = (n: Node) => Node;
+export type _Thunk = Exclude<Type, Const>;
+export type _Key = Exclude<Type, Primitive>;
+export type _State = {
+    readonly converting: readonly _Thunk[];
+    readonly names: readonly (readonly [_Thunk, string])[];
+    readonly done: readonly (readonly [_Key, UnionSet])[];
+    readonly deferred: readonly (readonly [_Thunk, _Thunk])[];
+};
+/**
+ * Converts a thunk-form schema into its canonical data form.
+ *
+ * Runs once per consumer need; schemas that are built but never consumed pay
+ * nothing. The output is normalized — unions are flattened and merged
+ * kind-wise, literals are sorted and deduplicated, subsumed array/object
+ * patterns are dropped, rules are pruned to the reachable set and sorted,
+ * and a union equal to a rule's body reads back as a reference — so schema
+ * identity is a property of this form: `toData(or(a, b))` and
+ * `toData(or(b, a))` are structurally identical even though the two thunks
+ * are distinct, and `or` is idempotent on recursive schemas.
+ *
+ * Only recursive definitions become named rules (named after their defining
+ * functions), everything else is inlined; a schema with no reference cycles
+ * converts to `[{}, unionSet]`.
+ *
+ * @type {(t: Type) => Data}
+ */
+export declare const toData: (t: Type) => Data;
+/**
+ * Data-driven validation — the counterpart of `../validate` that consumes a
+ * {@link Data} produced by {@link toData} instead of walking the thunk
+ * graph. Returns the original value on success, or the first
+ * `{ path, message }` error.
+ *
+ * @type {(data: Data) => (value: Unknown) => ResultE}
+ */
+export declare const validate: (data: Data) => (value: Unknown) => ResultE;