functionalscript 0.46.0 → 0.47.0

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

@@ -25,7 +25,7 @@
 import { assert, assertNotNullish } from '../../../asserts/module.f.mjs'
 import { at, definedEntries, definedValues } from '../../object/module.f.mjs'
 import { ok } from '../../result/module.f.mjs'
-import { eachEntry, isArray, verror } from '../common/module.f.mjs'
+import { eachEntry, isArray, undeclaredMembers, verror } from '../common/module.f.mjs'
 
 /**
  * The unit kind's enumeration: bit `1 << i` of a {@link UnionSet}'s `unit`
@@ -286,33 +286,76 @@ const isNever = n => typeof n !== 'string' && cmpUnion(n, never) === 0
 /** @type {(n: Node) => boolean} */
 const isTop = n => typeof n !== 'string' && cmpUnion(n, unknown) === 0
 
+/**
+ * The prefix with its redundant tail removed: a last position stating exactly
+ * the `rest` says nothing the `rest` does not already say, *provided* the
+ * `rest` admits `undefined`.
+ *
+ * Every array carrying a value at that position is read against the same set
+ * either way, so the two spellings can only differ on the arrays with nothing
+ * there — one that ends before it, and one holding a hole at it. Both read
+ * `undefined`, which the `rest` alone imposes nothing on, so dropping the
+ * position widens the set unless the `rest` admits `undefined` too. That is
+ * why `{ prefix: [number], rest: number }` keeps its position and stays "one
+ * or more numbers": `[]` and `[ , 1]` belong to `{ prefix: [], rest: number }`
+ * and not to it.
+ *
+ * This is what keeps one set to one spelling: the open tuples `[]` and
+ * `[unknown]` are both every array and have to produce one `Node`.
+ *
+ * A referenced `rest` is left alone — reading its unit bits would need the
+ * rule set, and the form already declines to see through a reference (see
+ * `./README.md`).
+ *
+ * @type {(prefix: readonly Node[], rest: Node) => readonly Node[]}
+ */
+const trimPrefix = (prefix, rest) =>
+    typeof rest === 'string' || ((rest.unit ?? 0) & unitBit(undefined)) === 0
+        ? prefix
+        : prefix.slice(0, prefix.findLastIndex(n => cmpNode(n, rest) !== 0) + 1)
+
 /**
  * Canonical array-kind singleton. A syntactically empty position makes the
- * whole pattern empty; an empty `rest` is the same set as no `rest`; an
- * unconstrained `rest` with no prefix is every array.
+ * whole pattern empty (a position past the array's end reads as `undefined`,
+ * which the empty set excludes, so no length escapes it); an empty `rest`
+ * admits nothing past the prefix, which is what no `rest` already says; a
+ * prefix restating its `rest` is {@link trimPrefix}'d away; an unconstrained
+ * `rest` with nothing left before it is every array.
+ *
+ * Every array set is stated with a `rest` — `never` for a bare tuple,
+ * `unknown` for an `open` one, the element set for a uniform array — so this
+ * takes one rather than an optional one; the absent `rest` is what it
+ * normalizes an empty one *to*.
  *
- * @type {(prefix: readonly Node[], rest: Node | undefined) => UnionSet}
+ * @type {(prefix: readonly Node[], rest: Node) => UnionSet}
  */
 const arraySet = (prefix, rest) => {
     if (prefix.some(isNever)) { return never }
-    const r = rest !== undefined && isNever(rest) ? undefined : rest
-    return prefix.length === 0 && r !== undefined && isTop(r)
-        ? { array: true }
-        : { array: [r === undefined ? { prefix } : { prefix, rest: r }] }
+    if (isNever(rest)) { return { array: [{ prefix }] } }
+    const p = trimPrefix(prefix, rest)
+    return p.length === 0 && isTop(rest) ? { array: true } : { array: [{ prefix: p, rest }] }
 }
 
 /**
- * Canonical object-kind singleton. An unconstrained key is dropped (reading
- * it yields some value regardless); a syntactically empty key set makes the
- * whole pattern empty; an unconstrained `rest` is the same set as no `rest`;
- * with nothing left, the pattern is every object.
+ * Canonical object-kind singleton. An unconstrained `rest` is the same set as
+ * no `rest`; an unconstrained key is then dropped too; a syntactically empty
+ * key set makes the whole pattern empty; with nothing left, the pattern is
+ * every object.
+ *
+ * A key is dropped only once the `rest` is gone, and that order is the whole
+ * rule: an undeclared key may be absent, or must belong to `rest`, which
+ * leaves it unconstrained exactly when there is no `rest` — so with one
+ * present a key saying "anything" says strictly more than leaving it out.
+ * A bare struct's empty `rest` is where the two part company —
+ * `{ props: { a: unknown }, rest: never }` admits `{ a: 1 }` and
+ * `{ props: {}, rest: never }` admits only `{}`.
  *
  * @type {(props: readonly (readonly [string, Node])[], rest: Node | undefined) => UnionSet}
  */
 const objectSet = (props, rest) => {
-    const constrained = props.filter(([, v]) => !isTop(v))
-    if (constrained.some(([, v]) => isNever(v))) { return never }
     const r = rest !== undefined && isTop(rest) ? undefined : rest
+    const constrained = r === undefined ? props.filter(([, v]) => !isTop(v)) : props
+    if (constrained.some(([, v]) => isNever(v))) { return never }
     if (constrained.length === 0 && r === undefined) { return { object: true } }
     /** @type {StringMap<Node>} */
     const sorted = Object.fromEntries(constrained.toSorted(([ak], [bk]) => cmpString(ak, bk)))
@@ -367,12 +410,22 @@ const kindSubset = le => (a, b) => {
     return a.every(x => b.some(y => le(x, y)))
 }
 
-/** @type {(ctx: _Ctx) => (assumed: _Assumed) => (p: ArraySet, q: ArraySet) => boolean} */
+/**
+ * Only the *longest* array each side admits is tested here — `pn` without a
+ * `rest`, unbounded with one. The shortest needs no test of its own: a
+ * position `q` insists on (one whose set excludes `undefined`) is a position
+ * `p` insists on too as soon as the pointwise check below passes, since
+ * otherwise `undefined` would be a member of `p.prefix[i]` and not of
+ * `q.prefix[i]`. Sound, and incomplete in the way `subset` is elsewhere: a
+ * `p` shorter than `q` is answered `false` even when every position past its
+ * end is one `q` admits as absent.
+ *
+ * @type {(ctx: _Ctx) => (assumed: _Assumed) => (p: ArraySet, q: ArraySet) => boolean}
+ */
 const arraySetSubset = ctx => assumed => (p, q) => {
     const le = nodeSubset(ctx)(assumed)
     const pn = p.prefix.length
     const qn = q.prefix.length
-    // `p` admits lengths `{pn}` or `[pn, ∞)`; they must fit `q`'s admitted lengths
     const lengthOk = q.rest !== undefined
         ? qn <= pn
         : p.rest === undefined && qn === pn
@@ -387,38 +440,65 @@ const arraySetSubset = ctx => assumed => (p, q) => {
 const keyed = n => [n, typeof n === 'string' ? `r:${n}` : undefined]
 
 /**
- * The set of values *read* at key `k` from objects of the pattern: the
- * declared set, else — since the key may also be absent, reading
- * `undefined` — the `rest` set plus `undefined`, else anything. A read-set
- * synthesized from a referenced rest keeps that rule's identity (`u:`), so
- * the coinductive memo closes cycles through it.
+ * The set of values the pattern admits at key `k` when the key is **present**:
+ * the declared set, else the `rest`, else anything.
+ *
+ * Presence is the whole point of splitting this from {@link objectMayOmit}. An
+ * absent key and a key present holding `undefined` are not the same object, and
+ * the two sides of a pattern read them differently: a *declared* key constrains
+ * the value read at it, so absence reads `undefined` and passes when the set
+ * holds it, whereas an *undeclared* key is checked as an entry, so a present
+ * `undefined` must belong to `rest` itself (see {@link objectSetValidate}).
+ * Folding the two into one "read set" of `rest ∪ undefined` made
+ * `{ a: option(number) }` a subset of `record(number)`, which admits
+ * `{ a: undefined }` on the left and rejects it on the right.
  *
- * @type {(rules: RuleSet) => (pattern: ObjectSet) => (k: string) => _Keyed}
+ * @type {(pattern: ObjectSet) => (k: string) => _Keyed}
  */
-const objectReadSet = rules => pattern => k => {
+const objectPresentSet = pattern => k => {
     const n = at(k)(pattern.props)
     if (n !== null) { return keyed(n) }
     const { rest } = pattern
-    return rest === undefined
-        ? [unknown, 't']
-        : [
-            merge(resolve(rules)(rest), { unit: unitBit(undefined) }),
-            typeof rest === 'string' ? `u:${rest}` : undefined,
-        ]
+    return rest === undefined ? [unknown, 't'] : keyed(rest)
+}
+
+/**
+ * Whether the pattern admits an object carrying no `k` at all: an undeclared
+ * key may always be missing, and a declared one exactly when its set holds
+ * `undefined`, since an absent property reads as `undefined`.
+ *
+ * This is the half of the old read-set that the `∪ undefined` stood for, now
+ * asked as its own question — a local unit-bit test, so it needs no memo.
+ *
+ * @type {(rules: RuleSet) => (pattern: ObjectSet) => (k: string) => boolean}
+ */
+const objectMayOmit = rules => pattern => k => {
+    const n = at(k)(pattern.props)
+    return n === null || ((resolve(rules)(n).unit ?? 0) & unitBit(undefined)) !== 0
 }
 
 /** @type {(list: readonly string[]) => readonly string[]} */
 const dedup = list => list.filter((n, i) => list.indexOf(n) === i)
 
-/** @type {(ctx: _Ctx) => (assumed: _Assumed) => (p: ObjectSet, q: ObjectSet) => boolean} */
+/**
+ * Every key either side declares is checked twice — what `p` may hold there
+ * must be something `q` holds there, and `p` may leave it out only where `q`
+ * lets it. Neither question implies the other: the first alone lets `p` admit
+ * an object `q` rejects for a *missing* key, the second alone for a *present*
+ * one.
+ *
+ * @type {(ctx: _Ctx) => (assumed: _Assumed) => (p: ObjectSet, q: ObjectSet) => boolean}
+ */
 const objectSetSubset = ctx => assumed => (p, q) => {
     const le = keyedSubset(ctx)(assumed)
     const keys = dedup([
         ...definedEntries(p.props).map(([k]) => k),
         ...definedEntries(q.props).map(([k]) => k),
     ])
-    return keys.every(k => le(objectReadSet(ctx[0])(p)(k), objectReadSet(ctx[1])(q)(k)))
-        // values at the keys declared by neither side
+    return keys.every(k =>
+            le(objectPresentSet(p)(k), objectPresentSet(q)(k))
+            && (!objectMayOmit(ctx[0])(p)(k) || objectMayOmit(ctx[1])(q)(k)))
+        // values at the keys declared by neither side, which both may omit
         && (q.rest === undefined || nodeSubset(ctx)(assumed)(p.rest ?? unknown, q.rest))
 }
 
@@ -459,6 +539,23 @@ const nodeSubset = ctx => assumed => (a, b) =>
 export const subset = ([aRules, aNode]) => ([bRules, bNode]) =>
     nodeSubset([aRules, bRules])({})(aNode, bNode)
 
+/**
+ * Whether `a` and `b` denote the same set: {@link subset} both ways.
+ *
+ * Weaker as a test than {@link equal} and stronger as an answer. `equal`
+ * compares canonical *structure*, so it reports two α-equivalent recursive
+ * definitions — the same shape under different rule names — as different;
+ * `subset` resolves references coinductively and sees through the renaming
+ * (see `./README.md`). It inherits `subset`'s incompleteness in exchange: an
+ * equality that holds only by distributing a union, or through a non-syntactic
+ * empty set, is answered `false`. That direction is the safe one — a `false`
+ * here never merges two memberships — so a caller may treat a `true` as
+ * conclusive and a `false` as "not established".
+ *
+ * @type {(a: Data) => (b: Data) => boolean}
+ */
+export const equivalent = a => b => subset(a)(b) && subset(b)(a)
+
 // ── coverage collapse ────────────────────────────────────────────────────────
 
 /**
@@ -685,12 +782,24 @@ const primitiveUnion = p => {
 const containerMemo = (state, c) => {
     const done = assoc(state.done, c)
     if (done !== undefined) { return [state, done] }
-    const [state1, u] = containerUnion(state, c)
+    const [state1, u] = containerUnion(state, c, never)
     return [{ ...state1, done: [...state1.done, [c, u]] }, u]
 }
 
-/** @type {(state: _State, c: ConstObject) => readonly [_State, UnionSet]} */
-const containerUnion = (state, c) => {
+/**
+ * The union of a const container, with `rest` the set every member it does not
+ * declare belongs to.
+ *
+ * Used bare, both kinds are **closed** — the declared members and no others —
+ * so the default maps onto the `rest` that says so, `never` on either kind.
+ * `rest`/`open` is what supplies one of its own; `unknown` is the open form,
+ * which the two kinds spell differently in the canonical data (a tuple's
+ * `rest: unknown`, a struct's absent `rest`) and {@link arraySet} /
+ * {@link objectSet} normalize to.
+ *
+ * @type {(state: _State, c: ConstObject, rest: Node) => readonly [_State, UnionSet]}
+ */
+const containerUnion = (state, c, rest) => {
     let s = state
     if (c instanceof Array) {
         /** @type {readonly Node[]} */
@@ -700,7 +809,7 @@ const containerUnion = (state, c) => {
             s = s1
             prefix = [...prefix, n]
         }
-        return [s, arraySet(prefix, undefined)]
+        return [s, arraySet(prefix, rest)]
     }
     /** @type {readonly (readonly [string, Node])[]} */
     let props = []
@@ -709,7 +818,22 @@ const containerUnion = (state, c) => {
         s = s1
         props = [...props, [k, n]]
     }
-    return [s, objectSet(props, undefined)]
+    return [s, objectSet(props, rest)]
+}
+
+/**
+ * The union of a `rest` schema. The container is walked here rather than
+ * through {@link containerMemo}: that memo is keyed by the container's
+ * identity alone, and the same object with two different rests is two
+ * different sets. The enclosing thunk is memoized by {@link convertThunk}
+ * either way, so nothing is recomputed and a cycle through a `rest` still
+ * closes.
+ *
+ * @type {(state: _State, c: ConstObject, r: Type) => readonly [_State, UnionSet]}
+ */
+const restUnion = (state, c, r) => {
+    const [state1, restNode] = nodeOf(state)(r)
+    return containerUnion(state1, c, restNode)
 }
 
 /** @type {(state: _State, c: Const) => readonly [_State, UnionSet]} */
@@ -784,6 +908,11 @@ const thunkUnion = (state, t) => {
             const [state1, value] = nodeOf(state)(rest[0])
             return [state1, objectSet([], value)]
         }
+        case 'rest': {
+            const [c, r] = rest
+            assert(typeof c === 'object' && c !== null, c)
+            return restUnion(state, c, r)
+        }
         default: { return orUnion(state, t, rest) }
     }
 }
@@ -987,21 +1116,44 @@ const patternsValidate = (k, item, value) => {
     return verror('no match')
 }
 
-/** @type {(p: ArraySet, i: number) => Node} */
-const atIndex = (p, i) => i < p.prefix.length ? p.prefix[i] : assertNotNullish(p.rest)
-
-/** @type {(rules: RuleSet) => (p: ArraySet) => (value: readonly Unknown[]) => ResultE} */
+/**
+ * The declared positions are checked by reading the value at each — a
+ * position past the end reads as `undefined`, so a position is required
+ * exactly when its set excludes `undefined`, and no minimum length is tested
+ * for. What is left over is tested against `rest`, or, with no `rest`, must
+ * not be there at all. Same shape as {@link objectSetValidate}, one kind
+ * over.
+ *
+ * `undeclaredMembers` is what the schema-form readers walk too, so "what is
+ * left over" is one rule rather than two that happen to coincide — including
+ * an index the prototype supplies, which an own-entry filter here answered
+ * `ok` for while the rendered tail claimed the `rest`'s type over it.
+ *
+ * @type {(rules: RuleSet) => (p: ArraySet) => (value: readonly Unknown[]) => ResultE}
+ */
 const arraySetValidate = rules => p => value => {
     const pn = p.prefix.length
-    if (p.rest === undefined ? value.length !== pn : value.length < pn) {
-        return verror('unexpected value')
-    }
-    const r = eachEntry(
-        Object.entries(value),
-        (k, v) => nodeValidate(rules)(atIndex(p, Number(k)))(v),
+    const { rest } = p
+    const declared = eachEntry(
+        Object.entries(p.prefix),
+        (k, n) => nodeValidate(rules)(n)(value[Number(k)]),
         undefined,
         noAccumulate,
     )
+    if (declared[0] === 'error') { return declared }
+    const extra = undeclaredMembers(p.prefix.map((_, i) => String(i)), value)
+    if (rest === undefined) {
+        // Nothing past the prefix, by length as well as by entry: a hole past
+        // it is not an entry, but the array is still that long, and this is
+        // the set `Ts<>` renders as a tuple of exactly `pn` positions and JSON
+        // Schema as `items: false`. A *shorter* array is another matter — the
+        // declared loop above has already held every position it left unfilled
+        // to a set admitting `undefined`.
+        return extra.length === 0 && value.length <= pn
+            ? ok(value)
+            : verror('unexpected value')
+    }
+    const r = eachEntry(extra, (_k, v) => nodeValidate(rules)(rest)(v), undefined, noAccumulate)
     return r[0] === 'error' ? r : ok(value)
 }
 
@@ -1042,6 +1194,48 @@ const unionValidate = rules => u => value => {
 /** @type {(rules: RuleSet) => (n: Node) => (value: Unknown) => ResultE} */
 const nodeValidate = rules => n => unionValidate(rules)(resolve(rules)(n))
 
+/**
+ * Whether `r`, as the rest of the container `c`, admits nothing — so that
+ * `rest(c, r)` and the bare, closed `c` denote one set.
+ *
+ * This is what the schema-form readers bound an array's length by, and it is
+ * asked *here* on purpose: `arraySet` is where an empty rest normalizes away,
+ * so the readers agree with this form by asking it rather than by re-deriving
+ * the same rule and drifting. Stated as **making no difference to the
+ * canonical form** — the conversion of `rest(c, r)` denoting the same set as
+ * the conversion of `c` — and not as a judgement about `r` on its own, nor as
+ * a reading of whether the conversion kept a `rest` key. Five cases fix it
+ * between them, and only this equality satisfies all five:
+ *
+ * - `never`, `or()` and `[or()]` all convert `rest(c, r)` to `c`'s own
+ *   conversion, so all three are empty. Keying on the exported `never` alone
+ *   would pass a `never`-only proof with the other two spellings still
+ *   disagreeing.
+ * - `const r = () => ['rest', [r], never]` has no finite inhabitant, yet the
+ *   conversion keeps `rest: "r"`, so it is *not* empty here. A reader
+ *   recognizing that emptiness would start rejecting what this form accepts.
+ * - `const a = () => ['or', b]; const b = () => ['or', a]` rules out the
+ *   rest's *own* canonical data as the test: {@link toData} of `a` is `never`,
+ *   and the conversion still keeps `rest: "a"`.
+ * - `unknown` rules out "the conversion kept no `rest` key" as the test:
+ *   `toData(rest([], unknown))` is `{ array: true }` — the whole kind, with no
+ *   `rest` key — because a top rest collapses the pattern rather than being
+ *   dropped from it.
+ * - Two separately constructed copies of one recursive rule, one in `c` and
+ *   one in `r`, rule out {@link equal} as the comparison: converting the rest
+ *   reserves the name, so `c`'s rule is named `r0` where converting `c` alone
+ *   names it `r`, and `equal` compares recursive definitions by rule name.
+ *
+ * {@link equivalent} answers all five. It is incomplete, and in the direction
+ * that costs nothing here: an unrecognized empty rest leaves the length
+ * unbounded, which is what a *kept* `rest` key means in this form anyway, so
+ * the readers still agree with it.
+ *
+ * @type {(c: ConstObject, r: Type) => boolean}
+ */
+export const emptyRest = (c, r) =>
+    equivalent(toData(/** @type {Type} */ (() => ['rest', c, r])))(toData(c))
+
 /**
  * Data-driven validation — the counterpart of `../validate` that consumes a
  * {@link Data} produced by {@link toData} instead of walking the thunk

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

@@ -30,6 +30,11 @@ export type _Odd = () => readonly ['const', {
     readonly next: Or<readonly [_Even, undefined]>;
 }];
 export type _Rec = () => readonly ['array', _Rec];
+export type _ClosedNode = () => readonly ['const', readonly [typeof number, _ClosedChildren]];
+export type _ClosedChildren = () => readonly ['array', _ClosedNode];
+export type _NestedRest = () => readonly ['rest', {
+    readonly a: typeof number;
+}, _NestedRest];
 export declare const proof: {
     withoutUnits: (() => void)[];
     unitBits: () => void;
@@ -37,6 +42,8 @@ export declare const proof: {
         primitives: () => void;
         tag0: () => void;
         containers: () => void;
+        rest: () => void;
+        restRecursion: () => void;
         constSchemas: () => void;
         or: () => void;
         orCanonicalIdentity: () => void;
@@ -50,6 +57,7 @@ export declare const proof: {
     };
     cmp: {
         totalOrder: () => void;
+        rest: () => void;
         restOrder: () => void;
         rules: () => void;
     };
@@ -57,6 +65,8 @@ export declare const proof: {
         literals: () => void;
         arrays: () => void;
         arrayRest: () => void;
+        rest: () => void;
+        presenceIsNotAbsence: () => void;
         objects: () => void;
         recursion: () => void;
         mixedObjectRecursion: () => void;