functionalscript 0.43.1 → 0.44.0

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

@@ -0,0 +1,136 @@
+/**
+ * Prime field arithmetic over `bigint`: `prime_field(p)` builds a `PrimeField`
+ * with negation, addition, subtraction, multiplication, division via modular
+ * inverse, and exponentiation; `sqrt` returns a square-root function when
+ * `p % 4 === 3`.
+ *
+ * @module
+ */
+
+/** @import { Reduce, Unary } from '../bigint/types.ts' */
+import { repeat } from '../../common/monoid/module.f.mjs'
+import { assertNotNullish } from '../../asserts/module.f.mjs'
+/** @import { PrimeField } from './types.ts' */
+
+/**
+ * Creates a prime field with the specified prime modulus and associated operations.
+ *
+ * @param {bigint} p A prime number to define the field.
+ * @returns {PrimeField} The prime field object.
+ */
+export const prime_field = p => {
+    /** @type {Reduce} */
+    const sub = a => b => {
+        const r = a - b
+        return r < 0 ? r + p : r
+    }
+    /** @type {Reduce} */
+    const mul = a => b => a * b % p
+    /** @type {Unary} */
+    const reciprocal = a => {
+        if (a === 0n) { throw '1/0' }
+        let a1 = a
+        let a0 = p
+        let f0 = 0n
+        let f1 = 1n
+        while (a1 !== 1n) {
+            const q = a0 / a1
+            const a2 = a0 % a1
+            a0 = a1
+            a1 = a2
+            const f2 = sub(f0)(mul(f1)(q))
+            f0 = f1
+            f1 = f2
+        }
+        return f1
+    }
+    const middle = p >> 1n
+    /** @type {Unary} */
+    const pow2 = a => mul(a)(a)
+    /** @type {Reduce} */
+    const pow = repeat({ identity: 1n, operation: mul })
+    /** @type {Reduce} */
+    const add = a => b => {
+        const r = a + b
+        return r < p ? r : r - p
+    }
+    /** @type {Unary} */
+    const reduce = x => {
+        const r = x % p
+        return r < 0n ? add(p)(r) : r
+    }
+    const max = p - 1n
+    // Euler's exponent is `(p - 1) / 2`; use `max`, not `p`, so `p === 2n`
+    // gives exponent `0n` instead of `1n`.
+    // 0 is a square mod p; Euler's criterion needs a separate case because 0^e = 0.
+    const powHalf = pow(max >> 1n)
+    /** @type {(x: bigint) => boolean} */
+    const quadRes = x => {
+        const v = reduce(x)
+        return v === 0n || powHalf(v) === 1n
+    }
+    return {
+        p,
+        middle,
+        max,
+        neg: a => a === 0n ? 0n : p - a,
+        sub,
+        add,
+        abs: a => middle < a ? p - a : a,
+        mul,
+        reciprocal,
+        div: a => b => mul(a)(reciprocal(b)),
+        pow,
+        pow2,
+        pow3: a => mul(a)(pow2(a)),
+        reduce,
+        quadRes,
+    }
+}
+
+/**
+ * Computes the square root of a number in a prime field.
+ *
+ * @throws If the prime modulus `p` does not satisfy `p % 4 == 3`.
+ *
+ * @param {PrimeField} field
+ * @returns {(a: bigint) => bigint | null}
+ *
+ * @example
+ *
+ * ```js
+ * const field = prime_field(7n);
+ * const root = sqrt(field)(4n);
+ * if (root !== 2n) { throw root }
+ * ```
+ */
+export const sqrt = ({ p, pow, pow2 }) => {
+    if ((p & 3n) !== 3n) { throw 'sqrt' }
+    const sqrt_k = (p + 1n) >> 2n
+    const psk = pow(sqrt_k)
+    return a => {
+        const result = psk(a)
+        return pow2(result) === a ? result : null
+    }
+}
+
+/**
+ * Modular square root mod `p` (`p ≡ 3 (mod 4)`); uses {@link PrimeField.neg} when `x` is not a residue.
+ *
+ * @param {PrimeField} field
+ * @returns {Unary}
+ */
+export const modSqrt = field => {
+    const { neg, reduce } = field
+    const sqrt_p = sqrt(field)
+    return x => {
+        const v = reduce(x)
+        const r = sqrt_p(v)
+        // For a prime `p ≡ 3 (mod 4)`, `−1` is a non-residue, so exactly one of
+        // `±v` is a quadratic residue: if `v` has no root, `neg(v)` must — hence
+        // `s` is non-null. `sqrt` already enforces `p ≡ 3 (mod 4)`, but primality
+        // is never checked, so the only way to reach `s === null` is a *composite*
+        // modulus (where the residue argument breaks).
+        return r !== null ? r : assertNotNullish(sqrt_p(neg(v)), 'modSqrt')
+    }
+}

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

@@ -0,0 +1,131 @@
+import { modSqrt, prime_field, sqrt } from './module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    throw: {
+        reciprocal_zero: () => prime_field(7n).reciprocal(0n),
+        sqrt_bad_prime: () => sqrt(prime_field(5n)),
+    },
+    prime_field_test: () => {
+        const p = 0xffffffff_ffffffff_ffffffff_ffffffff_ffffffff_ffffffff_fffffffe_fffffc2fn;
+        const f = prime_field(p)
+        const sqrt_f = sqrt(f)
+        return {
+            neg: () => {
+                assertEq(f.neg(0n), 0n)
+                assertEq(f.neg(1n), p - 1n)
+            },
+            sub: () => {
+                assertEq(f.sub(10n)(4n), 6n)
+                assertEq(f.sub(11n)(14n), p - 3n)
+            },
+            add: () => {
+                assertEq(f.add(13n)(24n), 37n)
+                assertEq(f.add(77n)(f.neg(12n)), 65n)
+            },
+            mul: () => {
+                assertEq(f.mul(100n)(0n), 0n)
+                assertEq(f.mul(101n)(205n), 20_705n)
+                assertEq(f.mul(304n)(f.neg(1n)), f.neg(304n))
+                assertEq(f.mul(f.neg(507n))(609n), f.neg(308_763n))
+                assertEq(f.mul(f.neg(713n))(f.neg(825n)), 588_225n)
+            },
+            reciprocal: () => {
+                let i = 1n
+                while (i < 10_000n) {
+                    assertEq(f.mul(f.reciprocal(i))(i), 1n)
+                    ++i
+                }
+            },
+            pow: () => {
+                /** @type {(a: bigint) => void} */
+                const test = a => {
+                    assertEq(f.pow(0n)(a), 1n)
+                    assertEq(f.pow(1n)(a), a)
+                    // https://en.wikipedia.org/wiki/Fermat%27s_little_theorem
+                    // a^(p-1) % p = 1
+                    assertEq(f.abs(f.pow(f.middle)(a)), 1n)
+                    assertEq(f.pow(f.sub(f.max)(1n))(a), f.reciprocal(a))
+                    assertEq(f.pow(f.max)(a), 1n)
+                }
+                // 0
+                assertEq(f.pow(0n)(0n), 1n)
+                assertEq(f.pow(f.max)(0n), 0n)
+                // 1
+                test(1n)
+                // 2
+                test(2n)
+                assertEq(f.pow(2n)(2n), 4n)
+                assertEq(f.pow(3n)(2n), 8n)
+                assertEq(f.pow(128n)(2n), 1n << 128n)
+                // 3
+                test(3n)
+                assertEq(f.pow(2n)(3n), 9n)
+                assertEq(f.pow(3n)(3n), 27n)
+                assertEq(f.pow(100n)(3n), 3n ** 100n)
+                assertEq(f.pow(110n)(3n), 3n ** 110n)
+                assertEq(f.pow(120n)(3n), 3n ** 120n)
+                assertEq(f.pow(121n)(3n), 3n ** 121n)
+                //
+                test(f.middle)
+                test(f.max - 1n)
+                test(f.max)
+            },
+            sqrtExample: () => {
+                const field = prime_field(7n);
+                assertEq(sqrt(field)(4n), 2n)
+            },
+            sqrt: () => {
+                /** @type {(a: bigint) => void} */
+                const test = a => {
+                    const a2 = f.mul(a)(a)
+                    const s = sqrt_f(a2)
+                    assert(s === null || f.abs(s) === f.abs(a), 'sqrt')
+                }
+                let i = 1n
+                while (i < 1000n) {
+                    test(i)
+                    ++i;
+                }
+                test(f.middle);
+                test(f.max);
+            },
+            reduce: () => {
+                assertEq(f.reduce(13n), 13n)
+                assertEq(f.reduce(-1n), p - 1n)
+            },
+            quadRes: () => {
+                assert(f.quadRes(0n), 0n)
+                assert(f.quadRes(1n), 1n)
+                assert(f.quadRes(p), p)
+                assert(!f.quadRes(3n), 3n)
+                const f2 = prime_field(2n)
+                assert(f2.quadRes(0n), '0 mod 2')
+                assert(f2.quadRes(1n), '1 mod 2')
+            },
+            modSqrt: () => {
+                const root = modSqrt(f)
+                assertEq(root(4n), 2n)
+                assertEq(f.pow2(root(2n)), 2n)
+            },
+            div: () => {
+                assertEq(f.div(6n)(2n), 3n)
+                assertEq(f.div(0n)(5n), 0n)
+                assertEq(f.div(1n)(1n), 1n)
+            },
+            pow3: () => {
+                assertEq(f.pow3(0n), 0n)
+                assertEq(f.pow3(1n), 1n)
+                assertEq(f.pow3(2n), 8n)
+                assertEq(f.pow3(3n), 27n)
+                assertEq(f.pow3(10n), 1000n)
+            },
+            abs: () => {
+                assertEq(f.abs(0n), 0n)
+                assertEq(f.abs(1n), 1n)
+                assertEq(f.abs(f.neg(1n)), 1n)
+                assertEq(f.abs(f.middle), f.middle)
+            },
+        }
+    }
+}

package/fjs/types/prime_field/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Types for prime field arithmetic over `bigint`.
+ *
+ * @module
+ */
+import type { Reduce, Unary } from '../bigint/types.ts';
+/**
+ * A type representing a prime field and its associated operations.
+ *
+ * @property reduce
+ *
+ * Reduces an arbitrary `bigint` into `[0, p)`.
+ *
+ * @property quadRes
+ *
+ * `true` when `x` is a square modulo `p`, including `0`.
+ *
+ * Nonzero values are tested with Euler's criterion:
+ * `x^((p - 1) / 2) === 1 (mod p)`.
+ * For `p === 2n`, both field elements are squares.
+ */
+export type PrimeField = {
+    readonly p: bigint;
+    readonly middle: bigint;
+    readonly max: bigint;
+    readonly neg: Unary;
+    readonly sub: Reduce;
+    readonly add: Reduce;
+    readonly abs: Unary;
+    readonly mul: Reduce;
+    readonly reciprocal: Unary;
+    readonly div: Reduce;
+    readonly pow: Reduce;
+    readonly pow2: Unary;
+    readonly pow3: Unary;
+    readonly reduce: Unary;
+    readonly quadRes: (x: bigint) => boolean;
+};

package/fjs/types/prime_field/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for prime field arithmetic over `bigint`.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,11 @@
+/**
+ * Range and interval utilities for numeric boundaries.
+ *
+ * @module
+ */
+import type { Range } from './types.ts';
+/** @import { Range } from './types.ts' */
+/** @type {(...range: Range) => (i: number) => boolean} */
+export declare const contains: (...range: Range) => (i: number) => boolean;
+/** @type {(i: number) => Range} */
+export declare const one: (i: number) => Range;

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

@@ -0,0 +1,13 @@
+/**
+ * Range and interval utilities for numeric boundaries.
+ *
+ * @module
+ */
+
+/** @import { Range } from './types.ts' */
+
+/** @type {(...range: Range) => (i: number) => boolean} */
+export const contains = (b, e) => i => b <= i && i <= e
+
+/** @type {(i: number) => Range} */
+export const one = a => [a, a]

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

@@ -0,0 +1,10 @@
+import { contains } from './module.f.mjs'
+import { assert } from '../../asserts/module.f.mjs'
+
+export const proof = () => {
+    assert(contains(0, 5)(1), 1)
+    assert(contains(0, 5)(0), 0)
+    assert(contains(0, 5)(5), 5)
+    assert(!(contains(0, 5)(-1)), -1)
+    assert(!(contains(0, 5)(6)), 6)
+}

package/fjs/types/range/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Range and interval types for numeric boundaries.
+ *
+ * @module
+ */
+export type Range = readonly [number, number];

package/fjs/types/range/types.js

@@ -0,0 +1,6 @@
+/**
+ * Range and interval types for numeric boundaries.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,72 @@
+/**
+ * Utility functions and types for managing and merging range maps.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * const rmOps = rangeMap({
+ *     union: a => b => a | b,
+ *     equal: a => b => a === b,
+ *     def: 0,
+ * })
+ *
+ * // Create range maps
+ * const range1 = rmOps.fromRange(2)([0, 10])
+ * const range2 = rmOps.fromRange(5)([5, 15])
+ *
+ * // Merge range maps
+ * const merged = toArray(rmOps.merge(range1)(range2))
+ *
+ * // Retrieve values from the merged range map
+ * const get = rmOps.get(merged)
+ * //
+ * if (get(-1) !== 0) { throw 'error' }
+ * //
+ * if (get(0) !== 2) { throw 'error' }
+ * if (get(2) !== 2) { throw 'error' }
+ * // overlapped: 2 | 5 = 7
+ * if (get(7) !== 7) { throw 'error' }
+ * //
+ * if (get(12) !== 5) { throw 'error' }
+ * if (get(15) !== 5) { throw 'error' }
+ * //
+ * if (get(16) !== 0) { throw 'error' }
+ * ```
+ */
+import type { Nullable } from '../nullable/types.ts';
+import type { Range } from '../range/types.ts';
+import type { Entry, Properties, RangeMapArray, RangeMapOp, RangeMerge } from './types.ts';
+export type _RangeState<T> = Nullable<Entry<T>>;
+export declare const merge: <T>(
+/**
+ * @template T
+ * @param {Properties<T>} op
+ * @returns {RangeMerge<T>}
+ */
+op: Properties<T>) => RangeMerge<T>;
+export declare const get: <T>(
+/**
+ * @template T
+ * @param {T} def
+ */
+def: T) => (
+/** @param {RangeMapArray<T>} rm */
+rm: RangeMapArray<T>) => (value: number) => T;
+export declare const fromRange: <T>(
+/**
+ * @template T
+ * @param {T} def
+ */
+def: T) => (
+/** @param {T} v */
+v: T) => ([a, b]: Range) => RangeMapArray<T>;
+/**
+ * Creates a set of operations for managing range maps using the specified properties.
+ *
+ * @template T
+ * @param {Properties<T>} op The properties defining union and equality operations and the default value.
+ * @returns {RangeMapOp<T>} An object containing operations for merging, retrieving, and constructing range maps.
+ */
+export declare const rangeMap: <T>(op: Properties<T>) => RangeMapOp<T>;

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

@@ -0,0 +1,130 @@
+/**
+ * Utility functions and types for managing and merging range maps.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * const rmOps = rangeMap({
+ *     union: a => b => a | b,
+ *     equal: a => b => a === b,
+ *     def: 0,
+ * })
+ *
+ * // Create range maps
+ * const range1 = rmOps.fromRange(2)([0, 10])
+ * const range2 = rmOps.fromRange(5)([5, 15])
+ *
+ * // Merge range maps
+ * const merged = toArray(rmOps.merge(range1)(range2))
+ *
+ * // Retrieve values from the merged range map
+ * const get = rmOps.get(merged)
+ * //
+ * if (get(-1) !== 0) { throw 'error' }
+ * //
+ * if (get(0) !== 2) { throw 'error' }
+ * if (get(2) !== 2) { throw 'error' }
+ * // overlapped: 2 | 5 = 7
+ * if (get(7) !== 7) { throw 'error' }
+ * //
+ * if (get(12) !== 5) { throw 'error' }
+ * if (get(15) !== 5) { throw 'error' }
+ * //
+ * if (get(16) !== 0) { throw 'error' }
+ * ```
+ */
+
+import { genericMerge } from '../sorted_list/module.f.mjs'
+/** @import { TailReduce, ReduceOp } from '../sorted_list/types.ts' */
+import { next } from '../list/module.f.mjs'
+/** @import { Nullable } from '../nullable/types.ts' */
+import { cmp } from '../number/module.f.mjs'
+import { bsearch } from '../function/compare/module.f.mjs'
+/** @import { Equal } from '../function/operator/types.ts' */
+/** @import { Range } from '../range/types.ts' */
+/**
+ * @import {
+ *  Entry, Properties, RangeMapArray, RangeMapOp, RangeMerge,
+ * } from './types.ts'
+ */
+
+/** @template T @typedef {Nullable<Entry<T>>} _RangeState */
+
+const reduceOp =
+    /**
+     * @template T
+     * @param {Properties<T>} p
+     * @returns {ReduceOp<Entry<T>, _RangeState<T>>}
+     */
+    ({ union, equal }) => state => ([aItem, aMax]) => ([bItem, bMax]) => {
+        const sign = cmp(aMax)(bMax)
+        const min = sign === 1 ? bMax : aMax
+        const u = union(aItem)(bItem)
+        const newState = state !== null && equal(state[0])(u) ? null : state
+        return [newState, sign, [u, min]]
+    }
+
+const tailReduce =
+    /**
+     * @template T
+     * @param {Equal<T>} equal
+     * @returns {TailReduce<Entry<T>, _RangeState<T>>}
+     */
+    equal => state => tail => {
+        if (state === null) { return tail }
+        const tailResult = next(tail)
+        if (tailResult === null) { return [state] }
+        if (equal(state[0])(tailResult.first[0])) { return tailResult }
+        return { first: state, tail: tailResult }
+    }
+
+export const merge =
+    /**
+     * @template T
+     * @param {Properties<T>} op
+     * @returns {RangeMerge<T>}
+     */
+    op => genericMerge({ reduceOp: reduceOp(op), tailReduce: tailReduce(op.equal) })(null)
+
+export const get =
+    /**
+     * @template T
+     * @param {T} def
+     */
+    def =>
+        /** @param {RangeMapArray<T>} rm */
+        rm => {
+            const length = rm.length
+            const search = bsearch(length)
+            /** @param {number} value */
+            return value => {
+                const pos = search(mid => value <= rm[mid][1] ? -1 : 1)
+                return pos < length ? rm[pos][0] : def
+            }
+        }
+
+export const fromRange =
+    /**
+     * @template T
+     * @param {T} def
+     */
+    def =>
+        /** @param {T} v */
+        v =>
+            /** @param {Range} r */
+            ([a, b]) => /** @type {RangeMapArray<T>} */([[def, a - 1], [v, b]])
+
+/**
+ * Creates a set of operations for managing range maps using the specified properties.
+ *
+ * @template T
+ * @param {Properties<T>} op The properties defining union and equality operations and the default value.
+ * @returns {RangeMapOp<T>} An object containing operations for merging, retrieving, and constructing range maps.
+ */
+export const rangeMap = op => ({
+    merge: merge(op),
+    get: get(op.def),
+    fromRange: fromRange(op.def),
+})

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

@@ -0,0 +1,7 @@
+/** @import { Unknown } from '../../media/json/types.ts' */
+export declare const proof: {
+    example: () => void;
+    merge: (() => void)[];
+    get: () => (() => void)[];
+    fromRange: () => (() => void)[];
+};