functionalscript 0.44.0 → 0.46.0

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

@@ -1,5 +1,8 @@
+/**
+ * @import { TNode } from '../types/types.ts'
+ */
+
 import { set as setSet } from './module.f.mjs'
-/** @import { TNode } from '../types/types.ts' */
 import { cmp } from '../../string/module.f.mjs'
 import { stringify } from '../../../media/json/module.f.mjs'
 import { sort } from '../../object/module.f.mjs'
@@ -421,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/btree/types/module.f.d.mts

@@ -3,8 +3,9 @@
  * themselves live in `./types.ts`.
  *
  * @module
+ *
+ * @import { Branch1, Branch3, Branch5, TNode } from './types.ts'
  */
-/** @import { Branch1, Branch3, Branch5, TNode } from './types.ts' */
 import type { Branch1, Branch3, Branch5, TNode } from './types.ts';
 /**
  * Demotes a single-child branch root to its only child.

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

@@ -3,8 +3,9 @@
  * themselves live in `./types.ts`.
  *
  * @module
+ *
+ * @import { Branch1, Branch3, Branch5, TNode } from './types.ts'
  */
-/** @import { Branch1, Branch3, Branch5, TNode } from './types.ts' */
 
 /**
  * Demotes a single-child branch root to its only child.

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

@@ -1,8 +1,15 @@
+/**
+ * Compact byte-set operations and predicates. See `./types.ts` for the
+ * `ByteSet` type.
+ *
+ * @module
+ *
+ * @import { RangeMap } from '../range_map/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;
-/** @import { ByteSet } from './types.ts' */
 /** @typedef {number} _Byte */
 /** @type {(n: _Byte) => (s: ByteSet) => boolean} */
 export declare const has: (n: _Byte) => (s: ByteSet) => boolean;
@@ -22,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

@@ -3,12 +3,13 @@
  * `ByteSet` type.
  *
  * @module
+ *
+ * @import { RangeMap } from '../range_map/types.ts'
+ * @import { ByteSet } from './types.ts'
  */
+
 import { compose } from '../function/module.f.mjs'
-/** @import { RangeMap } from '../range_map/types.ts' */
-/** @import { SortedSet } from '../sorted_set/types.ts' */
 import { reverse, countdown, flat, map } from '../list/module.f.mjs'
-/** @import { ByteSet } from './types.ts' */
 
 /** @typedef {number} _Byte */
 
@@ -55,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.d.mts

@@ -1,4 +1,6 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ */
 export declare const proof: {
     has: (() => void)[];
     setRange: () => void;

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

@@ -1,4 +1,6 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ */
 
 import { has, empty, set, setRange, unset, universe, complement, toRangeMap } from './module.f.mjs'
 import { every, countdown, map, toArray } from '../list/module.f.mjs'
@@ -63,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.d.mts

@@ -2,9 +2,10 @@
  * Comparison function types and helpers.
  *
  * @module
+ *
+ * @import { Index, Tuple } from '../../array/types.ts'
+ * @import { Cmp1, Cmp2, Compare, Sign } from './types.ts'
  */
-/** @import { Index, Tuple } from '../../array/types.ts' */
-/** @import { Cmp1, Cmp2, Compare, Sign } from './types.ts' */
 import type { Index, Tuple } from '../../array/types.ts';
 import type { Cmp1, Cmp2, Compare, Sign } from './types.ts';
 /** @type {<T>(cmp: Compare<T>) => (value: T) => Index<3>} */

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

@@ -2,18 +2,26 @@
  * Comparison function types and helpers.
  *
  * @module
+ *
+ * @import { Index, Tuple } from '../../array/types.ts'
+ * @import { Cmp1, Cmp2, Compare, Sign } from './types.ts'
  */
-/** @import { Index, Tuple } from '../../array/types.ts' */
-/** @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/function/module.f.d.mts

@@ -1,4 +1,11 @@
-/** @import { Func, Fn } from './types.ts' */
+/**
+ * Function combinators: composition, identity, argument flipping, and the
+ * chainable `Fn` wrapper.
+ *
+ * @module
+ *
+ * @import { Func, Fn } from './types.ts'
+ */
 import type { Func, Fn } from './types.ts';
 /**
  * A postfix compose function.

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

@@ -1,4 +1,11 @@
-/** @import { Func, Fn } from './types.ts' */
+/**
+ * Function combinators: composition, identity, argument flipping, and the
+ * chainable `Fn` wrapper.
+ *
+ * @module
+ *
+ * @import { Func, Fn } from './types.ts'
+ */
 
 /**
  * A postfix compose function.

package/fjs/types/function/operator/module.f.d.mts

@@ -2,9 +2,10 @@
  * Common higher-order operator type aliases.
  *
  * @module
+ *
+ * @import { Fold, Reduce, Scan, StateScan, Unary } from './types.ts'
  */
 import type { Fold, Reduce, Scan, StateScan, Unary } from './types.ts';
-/** @import { Fold, Reduce, Scan, StateScan, Unary } from './types.ts' */
 /** @type {(separator: string) => Reduce<string>} */
 export declare const join: (separator: string) => Reduce<string>;
 /** @type {Reduce<string>} */

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

@@ -2,10 +2,10 @@
  * Common higher-order operator type aliases.
  *
  * @module
+ *
+ * @import { Fold, Reduce, Scan, StateScan, Unary } from './types.ts'
  */
 
-/** @import { Fold, Reduce, Scan, StateScan, Unary } from './types.ts' */
-
 /** @type {(separator: string) => Reduce<string>} */
 export const join = separator => value => prior =>
     `${prior}${separator}${value}`

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

@@ -1,8 +1,15 @@
+/**
+ * Immutable list data structure utilities and combinators.
+ *
+ * @module
+ *
+ * @import { Nullable } from '../nullable/types.ts'
+ * @import {Scan, StateScan, Fold, Reduce, Equal} from '../function/operator/types.ts'
+ * @import { Accumulator, Concat, Entry, List, NonEmpty, NotLazy, Result, Thunk } from './types.ts'
+ */
 import type { Nullable } from '../nullable/types.ts';
 import type { Scan, StateScan, Fold, Reduce, Equal } from '../function/operator/types.ts';
 import type { Accumulator, Entry, List, Result, Thunk } from './types.ts';
-/** @import {Scan, StateScan, Fold, Reduce, Equal} from '../function/operator/types.ts' */
-/** @import { Accumulator, Concat, Entry, List, NonEmpty, NotLazy, Result, Thunk } from './types.ts' */
 export declare const fromArrayLike: <T>(
 /**
  * @template T
@@ -70,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

@@ -2,9 +2,13 @@
  * Immutable list data structure utilities and combinators.
  *
  * @module
+ *
+ * @import { Nullable } from '../nullable/types.ts'
+ * @import {Scan, StateScan, Fold, Reduce, Equal} from '../function/operator/types.ts'
+ * @import { Accumulator, Concat, Entry, List, NonEmpty, NotLazy, Result, Thunk } from './types.ts'
  */
+
 import { identity, fn, compose } from '../function/module.f.mjs'
-/** @import { Nullable } from '../nullable/types.ts' */
 import {
     addition,
     logicalNot,
@@ -13,8 +17,6 @@ import {
     foldToScan,
     reduceToScan,
 } from '../function/operator/module.f.mjs'
-/** @import {Scan, StateScan, Fold, Reduce, Equal} from '../function/operator/types.ts' */
-/** @import { Accumulator, Concat, Entry, List, NonEmpty, NotLazy, Result, Thunk } from './types.ts' */
 
 export const fromArrayLike =
     /**
@@ -236,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/list/proof.f.d.mts

@@ -1,4 +1,7 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ * @import { List } from './types.ts'
+ */
 declare const stringifyTest: () => void;
 declare const countdownTest: () => void;
 declare const flatTest: () => void;

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

@@ -1,6 +1,8 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ * @import { List } from './types.ts'
+ */
 
-/** @import { List } from './types.ts' */
 import { length, concat, countdown, cycle, drop, dropWhile, entries, every, filter, find, flat, flatMap, map, next, reduce, reverse, scan, some, take, takeWhile, toArray, zip, first, filterMap, isEmpty, equal, tryFold } from './module.f.mjs'
 import { stringify } from '../../media/json/module.f.mjs'
 import { sort } from '../object/module.f.mjs'

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

@@ -13,9 +13,10 @@
  * `ByteSet` is a `bigint`, which `JSON.stringify` cannot serialize.
  *
  * @module
+ *
+ * @import { Nibble, NibbleSet } from './types.ts'
  */
 import type { Nibble, NibbleSet } from './types.ts';
-/** @import { Nibble, NibbleSet } from './types.ts' */
 export declare const empty = 0;
 export declare const universe = 65535;
 /** @type {(n: Nibble) => (s: NibbleSet) => boolean} */

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

@@ -13,10 +13,10 @@
  * `ByteSet` is a `bigint`, which `JSON.stringify` cannot serialize.
  *
  * @module
+ *
+ * @import { Nibble, NibbleSet } from './types.ts'
  */
 
-/** @import { Nibble, NibbleSet } from './types.ts' */
-
 export const empty = 0
 
 export const universe = 0xFFFF

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

@@ -2,8 +2,9 @@
  * Nominal typing helpers for branded TypeScript types.
  *
  * @module
+ *
+ * @import { Nominal } from './types.ts'
  */
 import type { Nominal } from './types.ts';
-/** @import { Nominal } from './types.ts' */
 export declare const asNominal: <N extends string, R extends string, B>(b: B) => Nominal<N, R, B>;
 export declare const asBase: <T extends string, R extends string, B>(n: Nominal<T, R, B>) => B;

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

@@ -2,10 +2,11 @@
  * Nominal typing helpers for branded TypeScript types.
  *
  * @module
+ *
+ * @import { Nominal } from './types.ts'
  */
 
 import { identity } from "../function/module.f.mjs"
-/** @import { Nominal } from './types.ts' */
 
 export const asNominal =
     /** @type {<N extends string, R extends string, B>(b: B) => Nominal<N, R, B>} */

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

@@ -1,15 +1,35 @@
+/**
+ * Utilities for nullable (`null`/`undefined`) value handling.
+ *
+ * @module
+ *
+ * @import { Option } from '../option/types.ts'
+ * @import { Nullable } from './types.ts'
+ */
 import type { Option } from '../option/types.ts';
 import type { Nullable } from './types.ts';
-/** @import { Option } from '../option/types.ts' */
-/** @import { 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

@@ -2,21 +2,40 @@
  * Utilities for nullable (`null`/`undefined`) value handling.
  *
  * @module
+ *
+ * @import { Option } from '../option/types.ts'
+ * @import { Nullable } from './types.ts'
  */
+
 import { assert } from '../../asserts/module.f.mjs'
 import { fn } from '../function/module.f.mjs'
-/** @import { Option } from '../option/types.ts' */
-/** @import { 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 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/number/module.f.d.mts

@@ -3,6 +3,10 @@
  * `countOnes` for 32-bit population count using SWAR.
  *
  * @module
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
+ * @import { Sign } from '../function/compare/types.ts'
  */
 import type { List } from '../list/types.ts';
 import type { Sign } from '../function/compare/types.ts';

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

@@ -3,14 +3,15 @@
  * `countOnes` for 32-bit population count using SWAR.
  *
  * @module
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
+ * @import { Sign } from '../function/compare/types.ts'
  */
 
 import { reduce } from '../list/module.f.mjs'
-/** @import { List } from '../list/types.ts' */
 import { addition } from '../function/operator/module.f.mjs'
-/** @import { Reduce } from '../function/operator/types.ts' */
 import { cmp as uCmp, min as uMin, max as uMax } from '../function/compare/module.f.mjs'
-/** @import { Sign } from '../function/compare/types.ts' */
 import { fold } from '../../common/monoid/module.f.mjs'
 
 /** @type {(input: List<number>) => number} */

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

@@ -1,15 +1,27 @@
 /**
- * Plain-object helpers: safe property lookup via `at`, and conversions
- * between entries and `OrderedMap`. See `./types.ts` for the
+ * Plain-object helpers: safe property lookup via `at`, structural comparison
+ * via `structurallySame`, and conversions between entries and `OrderedMap`.
+ * See `./types.ts` for the
  * `OptionalMap`/`RequiredMap`/`StringMap`/`Entry`/`OneKey`/`SingleProperty`/
  * `NotUnion` type-level API.
  *
  * @module
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { Nullable } from '../nullable/types.ts'
+ * @import { OrderedMap } from '../ordered_map/types.ts'
+ * @import { StringMap, Entry } from './types.ts'
  */
 import type { List } from '../list/types.ts';
 import type { Nullable } from '../nullable/types.ts';
 import type { OrderedMap } from '../ordered_map/types.ts';
 import type { StringMap, Entry } from './types.ts';
+/**
+ * `structurallySame` is implemented in a dependency-free leaf so `fjs/asserts`
+ * can use it without the cycle `asserts -> object -> nullable -> asserts`; see
+ * `./structurally_same/README.md`. This module is its public home.
+ */
+export { structurallySame } from './structurally_same/module.f.mjs';
 /** @type {(name: string) => <T>(object: StringMap<T>) => Nullable<Exclude<T, undefined>>} */
 export declare const at: (name: string) => <T>(object: StringMap<T>) => Nullable<Exclude<T, undefined>>;
 /** @type {<T>(e: List<Entry<T>>) => List<Entry<T>>} */
@@ -29,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>[];