functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,79 @@
+/**
+ * @import { Nominal, _SymbolKeyBranded, _SymbolIntersectionBranded } from "./types.ts"
+ */
+
+import { asBase, asNominal } from "./module.f.mjs"
+import { assert } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    pre: () => {
+        /** @typedef {Nominal<'utf8', 'v0', bigint>} _Str */
+        /** @type {_Str} */
+        const strA = asNominal(0b1_11000010_10100010_11000010_10100011n) // "¢£"
+        /** @type {_Str} */
+        const strB = asNominal(0b1_11000010_10100010_11000010_10100100n) // "¢¤"
+        assert(strA !== strB, [strA, strB])
+        // // TypeScript compilation error.
+        // const x1 = strA > strB
+
+        //
+        {
+            /**
+             * @template {object} [T=object]
+             * @typedef {T & { __noCompare__: never }} _ForbiddenCompare
+             */
+            /** @typedef {_ForbiddenCompare<{ value: number }>} _IntersectionSafeId */
+            const a = /** @type {_IntersectionSafeId} */ ({ value: 1 })
+            const b = /** @type {_IntersectionSafeId} */ ({ value: 2 })
+
+            // No Compile-time error
+            if (a < b) { }
+        }
+
+        {
+            /** @typedef {{ _brand: 'NoCompare' }} _StringKeyBranded */
+            /** @type {_StringKeyBranded} */
+            const x = { _brand: 'NoCompare' }
+            // No Error
+            if (x < x) { }
+        }
+        {
+            const a = /** @type {_SymbolKeyBranded} */ ({})
+            const b = /** @type {_SymbolKeyBranded} */ ({})
+
+            // No Error
+            a < b
+        }
+        {
+
+            const a = /** @type {_SymbolIntersectionBranded} */ (/** @type {any} */ (undefined))
+            const b = /** @type {_SymbolIntersectionBranded} */ (/** @type {any} */ (undefined))
+
+            // a < b; // TS2469: Operator '<' cannot be applied to type 'symbol'.
+        }
+    },
+    nominal: () => {
+        /** @typedef {Nominal<'UserId', '1', number>} _UserId */
+        /** @typedef {Nominal<'UserId', '2', number>} _UserId2 */
+        /** @type {_UserId} */
+        const userIdA = asNominal(123)
+        /** @type {_UserId} */
+        const userIdB = asNominal(456)
+        assert(userIdA !== userIdB, [userIdA, userIdB])
+        /** @type {(_: _UserId) => number} */
+        const to = asBase
+        /** @type {(_: _UserId2) => number} */
+        const to2 = asBase
+        /** @type {_UserId2} */
+        const userId2A = asNominal(123)
+        /** @type {_UserId2} */
+        const userId2B = asNominal(456)
+        assert(userId2A !== userId2B, [userId2A, userId2B])
+        // assert(userIdA !== userId2A, [userIdA, userId2A]) // compilation error
+        /** @type {number} */
+        const n1 = to(userIdA)
+        /** @type {number} */
+        const n2 = to2(userId2A)
+        // const x = to(userId2A) // compilation error
+    }
+}

package/fjs/types/nominal/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Types for nominal typing (branded TypeScript types).
+ *
+ * @module
+ */
+/**
+ * Nominal type.
+ *
+ * It doesn't allow `===` between different nominal types.
+ * It doesn't allow `<`, `>`, `<=`, `>=` comparisons at all.
+ */
+export type Nominal<N extends string, R extends string, B> = symbol & {
+    [k in N]: readonly [R, B];
+};
+declare const noCompareBrand: unique symbol;
+declare const brand: unique symbol;
+/** A unique-symbol-keyed brand. TypeScript still permits `<` between two of these. */
+export type _SymbolKeyBranded = {
+    [noCompareBrand]: void;
+};
+/** A `symbol` intersection brand. `<` on this is TS2469, so the proof only comments it. */
+export type _SymbolIntersectionBranded = symbol & {
+    [brand]: 'SafeId';
+};
+export {};

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

@@ -0,0 +1,44 @@
+/**
+ * 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';
+/**
+ * @type {<T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>}
+ */
+export declare const map: <T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>;
+/**
+ * @type {<T, R>(f: (_: T) => R) => (none: () => R) => (_: Nullable<T>) => Nullable<R>}
+ */
+export declare const match: <T, R>(f: (_: T) => R) => (none: () => R) => (_: Nullable<T>) => Nullable<R>;
+/**
+ * @type {<T>(value: Nullable<T>) => Option<T>}
+ */
+export declare const toOption: <T>(value: Nullable<T>) => Option<T>;
+/**
+ * Normalizes a possibly-`undefined` value into the codebase's `null` convention.
+ *
+ * The boundary rule between JavaScript hosts (which return `undefined` from
+ * property/index lookups) and FunctionalScript (which uses `null` for absence).
+ *
+ * @type {<T>(value: T | undefined) => Nullable<T>}
+ */
+export declare const fromUndefined: <T>(value: T | undefined) => Nullable<T>;
+/**
+ * Extracts the value from a `Nullable`, asserting that it is not `null`.
+ *
+ * @type {<T>(value: Nullable<T>) => T}
+ */
+export declare const unwrap: <T>(value: Nullable<T>) => T;
+/**
+ * Lifts a function that signals failure with `null` into one that asserts
+ * success instead, unwrapping the result.
+ *
+ * @type {<I, T>(f: (i: I) => Nullable<T>) => (_: I) => T}
+ */
+export declare const mapUnwrap: <I, T>(f: (i: I) => Nullable<T>) => (_: I) => T;

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

@@ -0,0 +1,55 @@
+/**
+ * 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'
+
+/**
+ * @type {<T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>}
+ */
+export const map = f => value => value === null ? null : f(value)
+
+/**
+ * @type {<T, R>(f: (_: T) => R) => (none: () => R) => (_: Nullable<T>) => Nullable<R>}
+ */
+export const match = f => none => value => value === null ? none() : f(value)
+
+/**
+ * @type {<T>(value: Nullable<T>) => Option<T>}
+ */
+export const toOption = value => value === null ? [] : [value]
+
+/**
+ * Normalizes a possibly-`undefined` value into the codebase's `null` convention.
+ *
+ * The boundary rule between JavaScript hosts (which return `undefined` from
+ * property/index lookups) and FunctionalScript (which uses `null` for absence).
+ *
+ * @type {<T>(value: T | undefined) => Nullable<T>}
+ */
+export const fromUndefined = value => value === undefined ? null : value
+
+/**
+ * Extracts the value from a `Nullable`, asserting that it is not `null`.
+ *
+ * @type {<T>(value: Nullable<T>) => T}
+ */
+export const unwrap = value => {
+    assert(value !== null)
+    return value
+}
+
+/**
+ * Lifts a function that signals failure with `null` into one that asserts
+ * success instead, unwrapping the result.
+ *
+ * @type {<I, T>(f: (i: I) => Nullable<T>) => (_: I) => T}
+ */
+export const mapUnwrap = f =>
+    fn(f).map(unwrap).result

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

@@ -0,0 +1,34 @@
+import { fromUndefined, map, match, toOption } from './module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = [
+    () => {
+        /** @type {(v: number) => number} */
+        const sq = v => v * v
+        const optionSq = map(sq)
+        const sq3 = optionSq(3)
+        assertEq(sq3, 9)
+        const sqNull = optionSq(null)
+        assertEq(sqNull, null)
+    },
+    () => {
+        const opt1 = toOption(5)
+        assert(!(opt1.length !== 1 || opt1[0] !== 5), opt1)
+        const opt2 = toOption(null)
+        assertEq(opt2.length, 0, opt2)
+    },
+    () => {
+        /** @type {(v: number) => number} */
+        const twice = v => v * 2
+        const double = match(twice)(() => -1)
+        assertEq(double(3), 6)
+        assertEq(double(null), -1)
+    },
+    () => {
+        assertEq(fromUndefined(undefined), null, 0)
+        assertEq(fromUndefined(5), 5, 1)
+        assertEq(fromUndefined(0), 0, 2)
+        assertEq(fromUndefined(null), null, 3)
+        assertEq(fromUndefined(''), '', 4)
+    },
+]

package/fjs/types/nullable/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Types for nullable (`null`) value handling.
+ *
+ * @module
+ */
+export type Nullable<T> = T | null;

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

@@ -0,0 +1,27 @@
+/**
+ * Numeric list reductions (`sum`, `min`, `max`), comparison via `cmp`, and
+ * `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';
+/** @type {(input: List<number>) => number} */
+export declare const sum: (input: List<number>) => number;
+/** @type {(input: List<number>) => number | null} */
+export declare const min: (input: List<number>) => number | null;
+/** @type {(input: List<number>) => number | null} */
+export declare const max: (input: List<number>) => number | null;
+/** @type {(a: number) => (b: number) => Sign} */
+export declare const cmp: (a: number) => (b: number) => Sign;
+export type _MaskOffset = readonly [number, number];
+/**
+ * Count a number of ones in 32 bit number
+ *
+ * @type {(n: number) => number}
+ */
+export declare const countOnes: (n: number) => number;

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

@@ -0,0 +1,56 @@
+/**
+ * Numeric list reductions (`sum`, `min`, `max`), comparison via `cmp`, and
+ * `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 { addition } from '../function/operator/module.f.mjs'
+import { cmp as uCmp, min as uMin, max as uMax } from '../function/compare/module.f.mjs'
+import { fold } from '../../common/monoid/module.f.mjs'
+
+/** @type {(input: List<number>) => number} */
+export const sum = fold({ identity: 0, operation: addition })
+
+/** @type {Reduce<number>} */
+const minReduce = uMin
+
+/** @type {(input: List<number>) => number | null} */
+export const min = reduce(minReduce)(null)
+
+/** @type {Reduce<number>} */
+const maxReduce = uMax
+
+/** @type {(input: List<number>) => number | null} */
+export const max = reduce(maxReduce)(null)
+
+/** @type {(a: number) => (b: number) => Sign} */
+export const cmp = uCmp
+
+/** @typedef {readonly [number, number]} _MaskOffset */
+
+/** @type {readonly _MaskOffset[]} */
+const mo = [
+    [0x5555_5555, 1],
+    [0x3333_3333, 2],
+    [0x0F0F_0F0F, 4],
+    [0x00FF_00FF, 8],
+    [0x0000_FFFF, 16],
+]
+
+/**
+ * Count a number of ones in 32 bit number
+ *
+ * @type {(n: number) => number}
+ */
+export const countOnes = n => {
+    for (const [mask, offset] of mo) {
+        n = (n & mask) + ((n >> offset) & mask)
+    }
+    return n
+}

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

@@ -0,0 +1,204 @@
+import { sum, min, max, cmp, countOnes } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    sum: () => {
+        const result = sum([2, 3, 4, 5])
+        assertEq(result, 14)
+    },
+    min: {
+        empty: () => {
+            const result = min([])
+            assertEq(result, null)
+        },
+        multi: () => {
+            const result = min([1, 2, 12, -4, 8])
+            assertEq(result, -4)
+        }
+    },
+    max: () => {
+        const result = max([1, 2, 12, -4, 8])
+        assertEq(result, 12)
+    },
+    cmp: () => {
+        const result = cmp(4)(5)
+        assertEq(result, -1)
+    },
+    standard: () => {
+        /** @type {(a: bigint) => (b: bigint) => void} */
+        const check = a => b => {
+            assertEq(BigInt(Number(a)), b, [a, b])
+        }
+
+        /** @type {(v: bigint) => void} */
+        const eq = v => check(v)(v)
+
+        // 53, 0x35 bits.
+        //        3                   2                   1                   0
+        //   4_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210
+        eq(0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n)
+        eq(0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001n)
+        eq(0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010n)
+        eq(0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0011n)
+        eq(0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0100n)
+        //
+        eq(0b1_1101_0010_0110_1110_1000_0010_1000_1101_0000_0001_0011_0100_1000n)
+        eq(0b1_0101_0110_0110_0101_0110_0011_1100_0110_0110_0100_1100_1111_0001n)
+        eq(0b1_1011_0011_0010_1010_1110_1101_1000_1111_0010_0100_1100_0010_1010n)
+        eq(0b1_1010_0101_0010_0001_1000_1100_1010_1110_0110_0011_0001_0010_0011n)
+        eq(0b1_0011_0001_0101_1101_1000_1111_0111_1100_0011_1100_0000_1010_1100n)
+        //
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111n)
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110n)
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1101n)
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1100n)
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1011n)
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1010n)
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1001n)
+        eq(0b1_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1000n)
+
+        // 54, 0x35+1 bits.
+        //           3                   2                   1                   0
+        //      4_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210_1
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0n)
+        check
+            (0b01_1101_0111_0110_0101_1001_1101_0101_0010_1101_1011_0110_0111_1011_0n)
+            (0b01_1101_0111_0110_0101_1001_1101_0101_0010_1101_1011_0110_0111_1011_0n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_0n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_0n)
+        // round down
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_1n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0n)
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_1n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_0n)
+        check
+            (0b01_0100_1101_0100_1111_1101_1010_0110_1100_1111_1010_1000_1111_0010_1n)
+            (0b01_0100_1101_0100_1111_1101_1010_0110_1100_1111_1010_1000_1111_0010_0n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_1n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_0n)
+        // round up
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_1n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_0n)
+        check
+            (0b01_1011_1101_1010_0011_1010_1111_0111_1101_0001_1110_1111_1001_1011_1n)
+            (0b01_1011_1101_1010_0011_1010_1111_0111_1101_0001_1110_1111_1001_1100_0n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1n)
+            (0b10_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0n)
+
+        // 55, 0x35+2 bits.
+        //           3                   2                   1                   0
+        //      4_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210_12
+        // 0_xx: down, down, up
+        // 0_00
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_00n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_00n)
+        check
+            (0b01_1011_1000_1010_1100_0110_1010_1010_0110_1100_0010_1010_1111_0000_00n)
+            (0b01_1011_1000_1010_1100_0110_1010_1010_0110_1100_0010_1010_1111_0000_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_00n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_00n)
+        // 0_01 round down
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_01n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_00n)
+        check
+            (0b01_1111_1101_1010_1111_0011_1100_0011_1010_1001_1100_1010_1110_1000_01n)
+            (0b01_1111_1101_1010_1111_0011_1100_0011_1010_1001_1100_1010_1110_1000_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_01n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_00n)
+        // 0_10 round down
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_10n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_00n)
+        check
+            (0b01_0010_0011_1101_1100_0011_0001_1000_1101_0011_0011_0011_1111_0110_10n)
+            (0b01_0010_0011_1101_1100_0011_0001_1000_1101_0011_0011_0011_1111_0110_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_10n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_00n)
+        // 0_11 round up
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_11n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_00n)
+        check
+            (0b01_0010_0111_0000_1101_1011_0111_0010_0100_1101_1100_0010_0111_0000_11n)
+            (0b01_0010_0111_0000_1101_1011_0111_0010_0100_1101_1100_0010_0111_0001_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_11n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_00n)
+        // 1_xx: down, up, up
+        // 1_00
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_00n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_00n)
+        check
+            (0b01_1000_0001_1111_0001_1011_1101_0000_1001_1111_0011_0011_0111_0101_00n)
+            (0b01_1000_0001_1111_0001_1011_1101_0000_1001_1111_0011_0011_0111_0101_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1110_11n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_00n)
+        // 1_01 round down
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_01n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_00n)
+        check
+            (0b01_0100_1000_1100_1010_0010_1111_1011_0111_1011_1010_1011_0100_0001_01n)
+            (0b01_0100_1000_1100_1010_0010_1111_1011_0111_1011_1010_1011_0100_0001_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_01n)
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_00n)
+        // 1_10 round up
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_10n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_00n)
+        check
+            (0b01_1111_1011_1100_1010_1111_0010_1010_1111_1101_0110_0101_1001_0011_10n)
+            (0b01_1111_1011_1100_1010_1111_0010_1010_1111_1101_0110_0101_1001_0100_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_10n)
+            (0b10_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_00n)
+        // 1_11 round up
+        check
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_11n)
+            (0b01_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_00n)
+        check
+            (0b01_1111_0001_1001_1000_1110_0011_1011_0011_0100_0111_0010_0000_0101_11n)
+            (0b01_1111_0001_1001_1000_1110_0011_1011_0011_0100_0111_0010_0000_0110_00n)
+        check
+            (0b01_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_11n)
+            (0b10_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_00n)
+
+        // 57, 0x35+4 bits.
+        //           3                   2                   1                   0
+        //      4_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210_FEDC_BA98_7654_3210_1234
+        check
+            (0b01_0111_0001_0111_1101_1011_0100_1111_1110_0010_1111_0010_0010_1111_1110n)
+            (0b01_0111_0001_0111_1101_1011_0100_1111_1110_0010_1111_0010_0011_0000_0000n)
+        check
+            (0b01_1111_1010_1111_0011_0101_0111_1001_1111_1001_1101_0111_0000_0001_0100n)
+            (0b01_1111_1010_1111_0011_0101_0111_1001_1111_1001_1101_0111_0000_0001_0000n)
+    },
+    countOnes: [
+        () => {
+            //                    1121 2231 = 5 + 8 = 13
+            const r = countOnes(0x1234_5678)
+            assertEq(r, 13)
+        },
+        () => {
+            //                    2232 3340 = 9 + 10 = 19
+            const r = countOnes(0x9ABC_DEF0)
+            assertEq(r, 19)
+        }
+    ]
+}

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

@@ -0,0 +1,45 @@
+/**
+ * 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>>} */
+export declare const sort: <T>(e: List<Entry<T>>) => List<Entry<T>>;
+/** @type {<T>(e: List<Entry<T>>) => StringMap<T>} */
+export declare const fromEntries: <T>(e: List<Entry<T>>) => StringMap<T>;
+/** @type {<T>(m: OrderedMap<T>) => StringMap<T>} */
+export declare const fromMap: <T>(m: OrderedMap<T>) => StringMap<T>;
+/**
+ * @param {unknown} value
+ * @returns {value is { readonly [k in string]: unknown }}
+ */
+export declare const isObject: (value: unknown) => value is { readonly [k in string]: unknown; };
+/**
+ * Returns only the defined (non-undefined) values of a partial record.
+ *
+ * @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>])[];

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

@@ -0,0 +1,67 @@
+/**
+ * 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 { isArray } from '../array/module.f.mjs'
+import { iterable } from '../list/module.f.mjs'
+import { fromUndefined } from '../nullable/module.f.mjs'
+import { entries as mapEntries, fromEntries as mapFromEntries } from '../ordered_map/module.f.mjs'
+
+/**
+ * `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'
+
+const { getOwnPropertyDescriptor, fromEntries: objectFromEntries } = Object
+
+/** @type {(name: string) => <T>(object: StringMap<T>) => Nullable<Exclude<T, undefined>>} */
+export const at = name => object => {
+    const d = getOwnPropertyDescriptor(object, name)
+    return d === undefined ? null : fromUndefined(d.value)
+}
+
+/** @type {<T>(e: List<Entry<T>>) => List<Entry<T>>} */
+export const sort = e => mapEntries(mapFromEntries(e))
+
+/** @type {<T>(e: List<Entry<T>>) => StringMap<T>} */
+export const fromEntries = e => objectFromEntries(iterable(e))
+
+/** @type {<T>(m: OrderedMap<T>) => StringMap<T>} */
+export const fromMap = m => fromEntries(mapEntries(m))
+
+/**
+ * @param {unknown} value
+ * @returns {value is { readonly [k in string]: unknown }}
+ */
+export const isObject =
+    value =>
+    typeof value === 'object' && !isArray(value) && value !== null
+
+const { values, entries } = Object
+
+/**
+ * Returns only the defined (non-undefined) values of a partial record.
+ *
+ * @type {<T>(map: StringMap<Exclude<T, undefined>>) => readonly Exclude<T, undefined>[]}
+ */
+export const definedValues =
+    map =>
+    values(map).filter(v => v !== undefined)
+
+/** @type {<T>(cmd: StringMap<Exclude<T, undefined>>) => readonly (readonly [string, Exclude<T, undefined>])[]} */
+export const definedEntries =
+    cmd =>
+    entries(cmd).flatMap(([a, b]) => b === undefined ? [] : [[a, b]])