functionalscript 0.45.0 → 0.46.1

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

@@ -172,8 +172,6 @@ const op = norm => op => ap => bp => {
 
 /**
  * @typedef {{
- *  readonly front: (len: bigint) => (v: Vec) => bigint
- *  readonly removeFront: (len: bigint) => (v: Vec) => Vec
  *  readonly norm: _NormOp
  *  readonly uintCmp: (a: bigint) => (b: bigint) => Sign
  *  readonly unpackSplit: (len: bigint) => (u: Unpacked) => readonly[bigint, bigint]
@@ -183,6 +181,15 @@ const op = norm => op => ap => bp => {
 
 const unpackEmpty = /** @type {const} */{ length: 0n, uint: 0n }
 
+/**
+ * The element-to-`Unpacked` maps the two {@link mappedListToVec} instances
+ * differ by. Neither depends on a bit order, so both are bound once here
+ * (`fjs/AGENTS.md` §3.3).
+ *
+ * @type {(_: number) => Unpacked}
+ */
+const u8ToUnpacked = b => ({ length: 8n, uint: BigInt(b) })
+
 /**
  * Concatenation as a monoid over `Nullable<Unpacked>`, where `null` means "the
  * concatenation is longer than `maxLength`" and is an **absorbing** element:
@@ -198,7 +205,7 @@ const unpackEmpty = /** @type {const} */{ length: 0n, uint: 0n }
  * result because the result is what must not be built: `maxLength` is the
  * smallest `bigint` size supported across FunctionalScript's runtimes. The two
  * lengths are exact and additive — this is the length, not an estimate of it
- * (AGENTS.md §5.6).
+ * (`DESIGN.md` §6).
  *
  * Being absorbing is also what keeps the fold's walk bounded: `foldAbsorbing`
  * stops at the first merge that overflows instead of reading the rest of a list
@@ -241,8 +248,26 @@ const tryUnpackConcat = unpackConcat => ({
 const unpackListToVec = unpackConcat =>
     compose(foldAbsorbing(tryUnpackConcat(unpackConcat)))(nullableMap(pack))
 
+/**
+ * Concatenates a list of `I` values into one vector, mapping each element to
+ * its `Unpacked` form first; `null` when the result would exceed `maxLength`.
+ *
+ * The concatenation counterpart of {@link mappedChunkList}. Everything about
+ * the operation is fixed except how one element becomes `Unpacked`, so each
+ * element type supplies just that map. The `bo` parameter is structural rather
+ * than a whole `BitOrder` because `bo`'s own body applies this before the
+ * record exists.
+ *
+ * @type {<I>(g: (i: I) => Unpacked) => (bo: { readonly unpackConcat: _UnpackConcat }) => (list: List<I>) => Nullable<Vec>}
+ */
+const mappedListToVec = g => ({ unpackConcat }) => {
+    const f = unpackListToVec(unpackConcat)
+    const mg = map(g)
+    return list => f(mg(list))
+}
+
 /** @type {(base: _Base) => BitOrder} */
-const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }) => {
+const bo = ({ norm, uintCmp, unpackSplit, unpackConcatUint }) => {
     /** @param {bigint} len */
     const unpackPopFront = len => {
         const m = mask(len)
@@ -253,6 +278,19 @@ const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }
             return /** @type {const} */([uint & m, { length: v.length - len, uint: rest }])
         }
     }
+    // `front` and `removeFront` are the two projections of `unpackPopFront`,
+    // so each bit order supplies only `unpackSplit` and both fall out of it.
+    // `pack` re-masks, so `removeFront` can hand on the unmasked rest.
+    /** @type {(len: bigint) => (v: Vec) => bigint} */
+    const front = len => {
+        const f = unpackPopFront(len)
+        return v => f(unpack(v))[0]
+    }
+    /** @type {(len: bigint) => (v: Vec) => Vec} */
+    const removeFront = len => {
+        const f = unpackPopFront(len)
+        return v => pack(f(unpack(v))[1])
+    }
     /** @type {_UnpackConcat} */
     const unpackConcat = a => b => ({
         length: a.length + b.length,
@@ -272,9 +310,7 @@ const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }
         const bu = unpack(b)
         return pack(unpackConcat(au)(bu))
     }
-    const unpackedListToVec = unpackListToVec(unpackConcat)
-    /** @param {List<Vec>} list */
-    const tryListToVec = list => unpackedListToVec(map(unpack)(list))
+    const tryListToVec = mappedListToVec(unpack)({ unpackConcat })
     return {
         front,
         removeFront,
@@ -298,7 +334,8 @@ const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }
         unpackConcat,
         startsWith: prefix => {
             const { length: n, uint: u } = unpack(prefix)
-            return v => length(v) < n ? false : popFront(n)(v)[0] === u
+            const f = front(n)
+            return v => length(v) < n ? false : f(v) === u
         }
     }
 }
@@ -315,14 +352,6 @@ const lsbUnpackConcatUint =
  * Usually associated with Little-Endian (LE) byte order.
  */
 export const lsb = bo({
-    front: len => {
-        const m = mask(len)
-        return v => uint(v) & m
-    },
-    removeFront: len => v => {
-        const { length, uint } = unpack(v)
-        return vec(length - len)(uint >> len)
-    },
     norm: ({ uint: a }) => ({ uint: b }) => () =>
         ({ a, b }),
     uintCmp: a => b => {
@@ -341,17 +370,6 @@ export const lsb = bo({
  * Usually associated with Big-Endian (BE) byte order.
  */
 export const msb = bo({
-    front: len => {
-        const m = mask(len)
-        return v => {
-            const { length, uint } = unpack(v)
-            return (uint >> (length - len)) & m
-        }
-    },
-    removeFront: len => v => {
-        const { length, uint } = unpack(v)
-        return vec(length - len)(uint)
-    },
     norm: ({ length: al, uint: a }) => ({ length: bl, uint: b }) => len =>
         ({ a: a << (len - al), b: b << (len - bl) }),
     uintCmp: cmp,
@@ -366,11 +384,7 @@ export const msb = bo({
  *
  * @type {(_: BitOrder) => (list: List<number>) => Nullable<Vec>}
  */
-export const tryU8ListToVec = ({ unpackConcat }) => {
-    const unpackedListToVec = unpackListToVec(unpackConcat)
-    return list => unpackedListToVec(
-        map(/** @type {(_: number) => Unpacked} */b => ({ length: 8n, uint: BigInt(b) }))(list))
-}
+export const tryU8ListToVec = mappedListToVec(u8ToUnpacked)
 
 /**
  * Converts a list of unsigned 8-bit integers to a bit vector using the provided bit order.

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

@@ -193,9 +193,9 @@ export const proof = {
     },
     removeBack: () => {
         const v = vec(17n)(0x12345n)
-        assertEq(v, unsafeVec(0x12345n), (/** @type {bigint} */ (asBase(v))).toString(16))
+        assertEq(v, unsafeVec(0x12345n), (asBase(v)).toString(16))
         const r = lsb.removeFront(9n)(v)
-        assertEq(r, unsafeVec(0x91n), (/** @type {bigint} */ (asBase(r))).toString(16))
+        assertEq(r, unsafeVec(0x91n), (asBase(r)).toString(16))
     },
     uint: [
         // 0

package/fjs/types/btree/remove/module.f.mjs

@@ -130,7 +130,7 @@ export const nodeRemove = c => node => {
         const { first, tail } = find(c)(node)
         /** @type {(n: TNode<T>) => (f: (v: T) => PathItem<T>) => _RemovePath<T>} */
         const branch = n => f => {
-            const [v, p] = path(/** @type {Path<T>} */(null))(n)
+            const [v, p] = path(null)(n)
             return { first: p.first, tail: concat(p.tail)({ first: f(v), tail }) }
         }
         const [i, n] = first

package/fjs/types/btree/set/module.f.mjs

@@ -11,6 +11,7 @@
 import { collapseRoot } from '../types/module.f.mjs'
 import { find } from '../find/module.f.mjs'
 import { fold } from '../../list/module.f.mjs'
+import { assert } from '../../../asserts/module.f.mjs'
 
 /**
  * @template T
@@ -80,30 +81,27 @@ const nodeSet = c => g => node => {
                 // insert
                 const value = g(null)
                 // TODO: remove after TSGO fix the regression.
-                // const _xl: 1|2 = x.length
-                switch (x.length) {
+                const xL = x.length
+                // See https://github.com/microsoft/typescript-go/issues/4613
+                assert(xL === 1 || xL === 2)
+                switch (xL) {
                     case 1: { return [[x[0], value]] }
                     case 2: { return [[x[0]], value, [x[1]]] }
                 }
-                // TODO: remove after TSGO fix the regression.
-                // See https://github.com/microsoft/typescript-go/issues/4613
-                throw 'unreachable'
             }
             case 3: {
                 // replace
                 // TODO: remove after TSGO fix the regression.
-                // const _xl: 2|5 = x.length
-                switch (x.length) {
+                const xL = x.length
+                // See https://github.com/microsoft/typescript-go/issues/4613
+                assert(xL === 2 || xL === 5)
+                switch (xL) {
                     case 2: { return [[x[0], g(x[1])]] }
                     case 5: { return [[x[0], x[1], x[2], g(x[3]), x[4]]] }
                 }
-                // TODO: remove after TSGO fix the regression.
-                throw 'unreachable'
             }
             case 4: {
                 // insert
-                // TODO: remove after TSGO fix the regression.
-                // const _xl: 2 = x.length
                 const [v0, v1] = x
                 return [[v0], v1, [g(null)]]
             }

package/fjs/types/btree/set/proof.f.mjs

@@ -424,6 +424,18 @@ const test = [
             jsonStr(replacedSecond),
             '[[["1"],"100",["121","144"]],"16",[["169"],"25",["36"]],"4-updated",[["49"],"64",["81","9"]]]',
         )
+    },
+
+    // Replacing the first value of a two-value leaf exercises the
+    // `x.length === 2` arm of the `i === 1` "replace" case, which the
+    // fixtures above never reach — their two-value-leaf replaces all land on
+    // the second value.
+    () => {
+        /** @type {TNode<string>} */
+        const _map = set(['1'])('2')
+        assertEq(jsonStr(_map), '["1","2"]')
+        const replaced = replace(_map)('1')(() => '1-updated')
+        assertEq(jsonStr(replaced), '["1-updated","2"]')
     }
 ]
 

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

@@ -5,11 +5,9 @@
  * @module
  *
  * @import { RangeMap } from '../range_map/types.ts'
- * @import { SortedSet } from '../sorted_set/types.ts'
  * @import { ByteSet } from './types.ts'
  */
 import type { RangeMap } from '../range_map/types.ts';
-import type { SortedSet } from '../sorted_set/types.ts';
 import type { ByteSet } from './types.ts';
 export type _Byte = number;
 /** @typedef {number} _Byte */
@@ -31,5 +29,14 @@ export declare const set: (_: number) => (b: ByteSet) => ByteSet;
 export declare const setRange: (_: readonly [number, number]) => (b: ByteSet) => ByteSet;
 /** @type {(n: _Byte) => (s: ByteSet) => ByteSet} */
 export declare const unset: (n: _Byte) => (s: ByteSet) => ByteSet;
-/** @type {(n: ByteSet) => (s: string) => RangeMap<SortedSet<string>>} */
-export declare const toRangeMap: (n: ByteSet) => (s: string) => RangeMap<SortedSet<string>>;
+/**
+ * Re-expresses the set as a range map: one entry per membership boundary,
+ * carrying whether the range up to that byte is in the set.
+ *
+ * The payload is the set's own answer — `boolean` — and nothing more. A caller
+ * that needs ranges labelled with something else maps over the result; that
+ * labelling belongs to the caller, not to a byte set.
+ *
+ * @type {(n: ByteSet) => RangeMap<boolean>}
+ */
+export declare const toRangeMap: (n: ByteSet) => RangeMap<boolean>;

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

@@ -5,7 +5,6 @@
  * @module
  *
  * @import { RangeMap } from '../range_map/types.ts'
- * @import { SortedSet } from '../sorted_set/types.ts'
  * @import { ByteSet } from './types.ts'
  */
 
@@ -57,12 +56,21 @@ export const unset = n => s => difference(s)(one(n))
 
 const counter = reverse(countdown(256))
 
-/** @type {(n: ByteSet) => (s: string) => (i: number) => RangeMap<SortedSet<string>>} */
-const toRangeMapOp = n => s => i => {
+/** @type {(n: ByteSet) => (i: number) => RangeMap<boolean>} */
+const toRangeMapOp = n => i => {
     const current = has(i + 1)(n)
     const prev = has(i)(n)
-    return current === prev ? null : [[prev ? [s] : [], i]]
+    return current === prev ? null : [[prev, i]]
 }
 
-/** @type {(n: ByteSet) => (s: string) => RangeMap<SortedSet<string>>} */
-export const toRangeMap = n => s => flat(map(toRangeMapOp(n)(s))(counter))
+/**
+ * Re-expresses the set as a range map: one entry per membership boundary,
+ * carrying whether the range up to that byte is in the set.
+ *
+ * The payload is the set's own answer — `boolean` — and nothing more. A caller
+ * that needs ranges labelled with something else maps over the result; that
+ * labelling belongs to the caller, not to a byte set.
+ *
+ * @type {(n: ByteSet) => RangeMap<boolean>}
+ */
+export const toRangeMap = n => flat(map(toRangeMapOp(n))(counter))

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

@@ -65,22 +65,22 @@ export const proof = {
     },
     toRangeMap: [
         () => {
-            const result = stringify(toArray(toRangeMap(empty)('a')))
+            const result = stringify(toArray(toRangeMap(empty)))
             assertEq(result, '[]')
         },
         () => {
             const s = set(0)(empty)
-            const result = stringify(toArray(toRangeMap(s)('a')))
-            assertEq(result, '[[["a"],0]]')
+            const result = stringify(toArray(toRangeMap(s)))
+            assertEq(result, '[[true,0]]')
         },
         () => {
             const s = setRange([1, 2])(empty)
-            const result = stringify(toArray(toRangeMap(s)('a')))
-            assertEq(result, '[[[],0],[["a"],2]]')
+            const result = stringify(toArray(toRangeMap(s)))
+            assertEq(result, '[[false,0],[true,2]]')
         },
         () => {
-            const result = stringify(toArray(toRangeMap(universe)('a')))
-            assertEq(result, '[[["a"],255]]')
+            const result = stringify(toArray(toRangeMap(universe)))
+            assertEq(result, '[[true,255]]')
         },
     ]
 }

package/fjs/types/function/compare/module.f.mjs

@@ -7,14 +7,21 @@
  * @import { Cmp1, Cmp2, Compare, Sign } from './types.ts'
  */
 
+import { assert } from '../../../asserts/module.f.mjs'
+
 /** @type {<T>(cmp: Compare<T>) => (value: T) => Index<3>} */
-export const index3
-    = cmp => value => /** @type {Index<3>} */(cmp(value) + 1)
+export const index3 = cmp => value => {
+    const i = cmp(value) + 1
+    assert(i === 0 || i === 1 || i === 2, i)
+    return i
+}
 
 /** @type {<T>(cmp: Compare<T>) => (v2: Tuple<2, T>) => Index<5>} */
 export const index5 = cmp => ([v0, v1]) => {
     const _0 = cmp(v0)
-    return /** @type {Index<5>} */(_0 <= 0 ? _0 + 1 : cmp(v1) + 3)
+    const i = _0 <= 0 ? _0 + 1 : cmp(v1) + 3
+    assert(i === 0 || i === 1 || i === 2 || i === 3 || i === 4, i)
+    return i
 }
 
 /** @type {<A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => Sign} */

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

@@ -77,7 +77,7 @@ export declare const reduce: <T>(op: Reduce<T>) => <D>(def: D) => (input: List<T
  * Folds `input` with an {@link Accumulator}, short-circuiting to `null` the
  * moment `update` rejects an item; otherwise finalizes with `end`. This is the
  * list-level `try*` sibling of {@link fold} for accumulations that can fail
- * partway through (see the `try*`/`Nullable` convention in `AGENTS.md`).
+ * partway through (see the `try*`/`Nullable` convention in `DESIGN.md` §6).
  *
  * @type {<I, T, R>({ init, update, end }: Accumulator<I, T, R>) => (input: List<I>) => Nullable<R>}
  */

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

@@ -238,7 +238,7 @@ export const reduce = op => def => compose(scan(reduceToScan(op)))(last(def))
  * Folds `input` with an {@link Accumulator}, short-circuiting to `null` the
  * moment `update` rejects an item; otherwise finalizes with `end`. This is the
  * list-level `try*` sibling of {@link fold} for accumulations that can fail
- * partway through (see the `try*`/`Nullable` convention in `AGENTS.md`).
+ * partway through (see the `try*`/`Nullable` convention in `DESIGN.md` §6).
  *
  * @type {<I, T, R>({ init, update, end }: Accumulator<I, T, R>) => (input: List<I>) => Nullable<R>}
  */

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

@@ -9,13 +9,27 @@
 import type { Option } from '../option/types.ts';
 import type { Nullable } from './types.ts';
 /**
- * @type {<T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>}
+ * Folds a `Nullable<T>` into a single value: `f` for a present value, `none`
+ * for `null`.
+ *
+ * The two branches carry independent result types, and `R2` lives on its own
+ * curry step on purpose. With `T`, `R1` and `R2` all on the outer generic they
+ * are instantiated together at `match(f)` — before `none` exists — so `R2` has
+ * nothing to infer from and collapses to `unknown`. Inferring it at the second
+ * call instead is what lets {@link map} be derived below.
+ *
+ * @type {<T, R1>(f: (_: T) => R1) => <R2>(none: () => R2) => (_: Nullable<T>) => R1 | R2}
  */
-export declare const map: <T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>;
+export declare const match: <T, R1>(f: (_: T) => R1) => <R2>(none: () => R2) => (_: Nullable<T>) => R1 | R2;
 /**
- * @type {<T, R>(f: (_: T) => R) => (none: () => R) => (_: Nullable<T>) => Nullable<R>}
+ * Projects the present value of a `Nullable<T>`, passing `null` through.
+ *
+ * `map` is `match` with the absent branch fixed to `null`, so the
+ * `value === null` guard is written once, in `match`.
+ *
+ * @type {<T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>}
  */
-export declare const match: <T, R>(f: (_: T) => R) => (none: () => R) => (_: Nullable<T>) => Nullable<R>;
+export declare const map: <T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>;
 /**
  * @type {<T>(value: Nullable<T>) => Option<T>}
  */

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

@@ -11,14 +11,31 @@ import { assert } from '../../asserts/module.f.mjs'
 import { fn } from '../function/module.f.mjs'
 
 /**
- * @type {<T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>}
+ * Folds a `Nullable<T>` into a single value: `f` for a present value, `none`
+ * for `null`.
+ *
+ * The two branches carry independent result types, and `R2` lives on its own
+ * curry step on purpose. With `T`, `R1` and `R2` all on the outer generic they
+ * are instantiated together at `match(f)` — before `none` exists — so `R2` has
+ * nothing to infer from and collapses to `unknown`. Inferring it at the second
+ * call instead is what lets {@link map} be derived below.
+ *
+ * @type {<T, R1>(f: (_: T) => R1) => <R2>(none: () => R2) => (_: Nullable<T>) => R1 | R2}
  */
-export const map = f => value => value === null ? null : f(value)
+export const match = f => none => value => value === null ? none() : f(value)
+
+/** The absent branch `map` fixes `match`'s `none` to. */
+const noneIsNull = () => null
 
 /**
- * @type {<T, R>(f: (_: T) => R) => (none: () => R) => (_: Nullable<T>) => Nullable<R>}
+ * Projects the present value of a `Nullable<T>`, passing `null` through.
+ *
+ * `map` is `match` with the absent branch fixed to `null`, so the
+ * `value === null` guard is written once, in `match`.
+ *
+ * @type {<T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>}
  */
-export const match = f => none => value => value === null ? none() : f(value)
+export const map = f => match(f)(noneIsNull)
 
 /**
  * @type {<T>(value: Nullable<T>) => Option<T>}

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

@@ -1 +1,5 @@
+/**
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ */
 export declare const proof: (() => void)[];

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

@@ -1,3 +1,8 @@
+/**
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ */
+
 import { fromUndefined, map, match, toOption } from './module.f.mjs'
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 
@@ -24,6 +29,16 @@ export const proof = [
         assertEq(double(3), 6)
         assertEq(double(null), -1)
     },
+    () => {
+        // The two branches carry independent result types: `describe` is
+        // `(_: Nullable<number>) => number | string`, not one unified `R`.
+        /** @type {(v: number) => number} */
+        const twice = v => v * 2
+        const describe = match(twice)(() => 'none')
+        /** @typedef {Assert<Equal<ReturnType<typeof describe>, number | string>>} _Branches */
+        assertEq(describe(3), 6)
+        assertEq(describe(null), 'none')
+    },
     () => {
         assertEq(fromUndefined(undefined), null, 0)
         assertEq(fromUndefined(5), 5, 1)

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

@@ -41,5 +41,15 @@ export declare const isObject: (value: unknown) => value is { readonly [k in str
  * @type {<T>(map: StringMap<Exclude<T, undefined>>) => readonly Exclude<T, undefined>[]}
  */
 export declare const definedValues: <T>(map: StringMap<Exclude<T, undefined>>) => readonly Exclude<T, undefined>[];
-/** @type {<T>(cmd: StringMap<Exclude<T, undefined>>) => readonly (readonly [string, Exclude<T, undefined>])[]} */
-export declare const definedEntries: <T>(cmd: StringMap<Exclude<T, undefined>>) => readonly (readonly [string, Exclude<T, undefined>])[];
+/**
+ * Returns only the defined (non-undefined) entries of a partial record.
+ *
+ * `T` is the record's own value type, which `StringMap` already makes
+ * optional. Writing the parameter as `StringMap<Exclude<T, undefined>>`
+ * instead would leave `T` in a non-inference position, so a record whose value
+ * type is itself generic — the leaf-parameterized JSON tree, say — could not
+ * be passed at all.
+ *
+ * @type {<T>(cmd: StringMap<T>) => readonly Entry<T>[]}
+ */
+export declare const definedEntries: <T>(cmd: StringMap<T>) => readonly Entry<T>[];

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

@@ -61,7 +61,17 @@ export const definedValues =
     map =>
     values(map).filter(v => v !== undefined)
 
-/** @type {<T>(cmd: StringMap<Exclude<T, undefined>>) => readonly (readonly [string, Exclude<T, undefined>])[]} */
+/**
+ * Returns only the defined (non-undefined) entries of a partial record.
+ *
+ * `T` is the record's own value type, which `StringMap` already makes
+ * optional. Writing the parameter as `StringMap<Exclude<T, undefined>>`
+ * instead would leave `T` in a non-inference position, so a record whose value
+ * type is itself generic — the leaf-parameterized JSON tree, say — could not
+ * be passed at all.
+ *
+ * @type {<T>(cmd: StringMap<T>) => readonly Entry<T>[]}
+ */
 export const definedEntries =
     cmd =>
     entries(cmd).flatMap(([a, b]) => b === undefined ? [] : [[a, b]])

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

@@ -6,6 +6,8 @@
  * @import { Candidate, Create, PatriciaTrie } from './types.ts'
  */
 
+import { splitLast } from '../array/module.f.mjs'
+
 /**
  * Creates a Patricia trie whose node merging is delegated to `create`.
  *
@@ -14,24 +16,37 @@
 export const patriciaTrie = create => ({
     push: (c, [storage, stack]) => {
         const [u] = c
-        while (stack.length >= 2) {
-            const [rLeaf, rHash] = stack[stack.length - 1]
-            const [lLeaf, lHash] = stack[stack.length - 2]
+        // Carry propagation: merge the top two candidates for as long as they
+        // are more tightly coupled to each other than the right one is to the
+        // incoming leaf. Genuinely sequential — each merge decides whether the
+        // next one happens — so the loop stays, but the stack is read by
+        // splitting rather than by index arithmetic. Either split answering
+        // `null` means fewer than two candidates are left, which is where the
+        // old `stack.length >= 2` guard stopped.
+        while (true) {
+            const top = splitLast(stack)
+            if (top === null) { break }
+            const [belowR, [rLeaf, rHash]] = top
+            const below = splitLast(belowR)
+            if (below === null) { break }
+            const [rest, [lLeaf, lHash]] = below
             if ((lLeaf ^ rLeaf) >= (rLeaf ^ u)) { break }
             const [h, newS] = create(lHash, rHash, storage)
             storage = newS
-            stack = [...stack.slice(0, -2), [rLeaf, h]]
+            stack = [...rest, [rLeaf, h]]
         }
         return [storage, [...stack, c]]
     },
+    // Drain the right spine into a root: a right fold whose seed is the last
+    // candidate's identity. `splitLast` supplies both halves at once, so the
+    // empty stack is the `null` branch rather than a separate length guard.
     end: ([storage, stack]) => {
-        if (stack.length === 0) { return [undefined, storage] }
-        let h = stack[stack.length - 1][1]
-        for (let i = stack.length - 2; i >= 0; i--) {
-            const lHash = stack[i][1];
-            [h, storage] = create(lHash, h, storage)
-        }
-        return [h, storage]
+        const split = splitLast(stack)
+        if (split === null) { return [undefined, storage] }
+        const [rest, [, lastHash]] = split
+        return rest.reduceRight(
+            ([h, s], [, lHash]) => create(lHash, h, s),
+            /** @type {readonly [typeof lastHash, typeof storage]} */([lastHash, storage]))
     }
 })
 

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

@@ -64,8 +64,8 @@ export declare const mapOk: <T, R>(f: (value: T) => R) => <E>(r: Result<T, 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.
+ * 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`)
@@ -80,7 +80,7 @@ export declare const mapOk: <T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) =
  *
  * 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
+ * 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.
  *

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

@@ -72,8 +72,8 @@ 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.
+ * 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`)
@@ -88,7 +88,7 @@ export const mapOk = f => r => r[0] === 'ok' ? ok(f(r[1])) : r
  *
  * 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
+ * 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.
  *