functionalscript 0.44.0 → 0.45.0

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

@@ -34,6 +34,12 @@
  * //
  * if (get(16) !== 0) { throw 'error' }
  * ```
+ *
+ * @import { TailReduce, ReduceOp } from '../sorted_list/types.ts'
+ * @import { Nullable } from '../nullable/types.ts'
+ * @import { Equal } from '../function/operator/types.ts'
+ * @import { Range } from '../range/types.ts'
+ * @import { Entry, Properties, RangeMapArray, RangeMapOp, RangeMerge, } from './types.ts'
  */
 import type { Nullable } from '../nullable/types.ts';
 import type { Range } from '../range/types.ts';

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

@@ -34,21 +34,18 @@
  * //
  * if (get(16) !== 0) { throw 'error' }
  * ```
+ *
+ * @import { TailReduce, ReduceOp } from '../sorted_list/types.ts'
+ * @import { Nullable } from '../nullable/types.ts'
+ * @import { Equal } from '../function/operator/types.ts'
+ * @import { Range } from '../range/types.ts'
+ * @import { Entry, Properties, RangeMapArray, RangeMapOp, RangeMerge, } from './types.ts'
  */
 
 import { genericMerge } from '../sorted_list/module.f.mjs'
-/** @import { TailReduce, ReduceOp } from '../sorted_list/types.ts' */
 import { next } from '../list/module.f.mjs'
-/** @import { Nullable } from '../nullable/types.ts' */
 import { cmp } from '../number/module.f.mjs'
 import { bsearch } from '../function/compare/module.f.mjs'
-/** @import { Equal } from '../function/operator/types.ts' */
-/** @import { Range } from '../range/types.ts' */
-/**
- * @import {
- *  Entry, Properties, RangeMapArray, RangeMapOp, RangeMerge,
- * } from './types.ts'
- */
 
 /** @template T @typedef {Nullable<Entry<T>>} _RangeState */
 

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

@@ -1,4 +1,8 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ * @import { RangeMapArray, Properties, RangeMap } from './types.ts'
+ * @import { SortedSet } from '../sorted_set/types.ts'
+ */
 export declare const proof: {
     example: () => void;
     merge: (() => void)[];

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

@@ -1,11 +1,13 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ * @import { RangeMapArray, Properties, RangeMap } from './types.ts'
+ * @import { SortedSet } from '../sorted_set/types.ts'
+ */
 
-/** @import { RangeMapArray, Properties, RangeMap } from './types.ts' */
 import { get, merge, fromRange, rangeMap } from './module.f.mjs'
 import { stringify } from '../../media/json/module.f.mjs'
 import { sort } from '../object/module.f.mjs'
 import { union } from '../sorted_set/module.f.mjs'
-/** @import { SortedSet } from '../sorted_set/types.ts' */
 import { equal, toArray } from '../list/module.f.mjs'
 import { strictEqual } from '../function/operator/module.f.mjs'
 import { cmp } from '../string/module.f.mjs'

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

@@ -1,3 +1,8 @@
+/**
+ * A set of numeric ranges, represented as a `range_map` of `boolean`.
+ *
+ * @module
+ */
 /**
  * Constructs a range set containing a single numeric range.
  */

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

@@ -3,6 +3,7 @@
  *
  * @module
  */
+
 import { rangeMap } from '../range_map/module.f.mjs'
 
 const map = rangeMap({

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

@@ -1 +1,4 @@
+/**
+ * @import { Range } from '../range/types.ts'
+ */
 export declare const proof: () => void;

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

@@ -1,7 +1,10 @@
+/**
+ * @import { Range } from '../range/types.ts'
+ */
+
 import { assert } from '../../asserts/module.f.mjs'
 import { toArray } from '../list/module.f.mjs'
 import { fromRange, merge, get } from './module.f.mjs'
-/** @import { Range } from '../range/types.ts' */
 
 /** @type {(a: string) => number} */
 const c = a => a.charCodeAt(0)

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

@@ -1,3 +1,11 @@
+/**
+ * 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 type { Result } from './types.ts';
 /** @type {<T>(f: () => T) => Result<T, unknown>} */
 export declare const tryCatch: <T>(f: () => T) => Result<T, unknown>;

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 `fjs/effects`' `okStep` — which is the same combinator for a step
+ * 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 AGENTS.md §6.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 `fjs/effects`' `okStep` — which is the same combinator for a step
+ * 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 AGENTS.md §6.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,43 @@
+/**
+ * Shared kernel for RTTI consumers (`validate`, `parse`).
+ *
+ * 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:
+ *
+ * - 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.
+ * - `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.
+ * - `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 schema-driven consumers (e.g. the data form in
+ * `../data/module.f.mjs`) a stable shared base.
+ *
+ * @module
+ *
+ * @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 { 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>;

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

@@ -22,19 +22,21 @@
  *   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.
+ * `validate` and gives schema-driven consumers (e.g. the data form in
+ * `../data/module.f.mjs`) a stable shared base.
  *
  * @module
+ *
+ * @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 { 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 { 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>} */

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 */

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

@@ -0,0 +1,120 @@
+/**
+ * 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;
+/**
+ * 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;