functionalscript 0.43.1 → 0.44.0

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

@@ -0,0 +1,443 @@
+import {
+    sum,
+    abs,
+    serialize,
+    log2,
+    bitLength,
+    mask,
+    combination,
+    factorial,
+    xor,
+    multiple,
+    product,
+    divUp,
+    roundUp,
+    divUp8,
+    roundUp8
+} from './module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { min } from '../function/compare/module.f.mjs'
+
+/** @type {(v: bigint) => bigint} */
+const oldLog2 = v => {
+    if (v <= 0n) { return -1n }
+    let result = 0n
+    let i = 1n
+    while (true) {
+        const n = v >> i
+        if (n === 0n) {
+            // overshot
+            break
+        }
+        v = n
+        result += i
+        i <<= 1n // multiple by two
+    }
+    // We know that `v` is not 0 so it doesn't make sense to check `n` when `i` is 0.
+    // Because of this, We check if `i` is greater than 1 before we divide it by 2.
+    while (i !== 1n) {
+        i >>= 1n
+        const n = v >> i
+        if (n !== 0n) {
+            result += i
+            v = n
+        }
+    }
+    return result
+}
+
+/** @type {(v: bigint) => bigint} */
+const strBinLog2 = v => BigInt(v.toString(2).length) - 1n
+
+/** @type {(v: bigint) => bigint} */
+const strHexLog2 = v => {
+    const len = (BigInt(v.toString(16).length) - 1n) << 2n
+    return len + 31n - BigInt(Math.clz32(Number(v >> len)))
+}
+
+/** @type {(v: bigint) => bigint} */
+const str32Log2 = v => {
+    const len = (BigInt(v.toString(32).length) - 1n) * 5n
+    return len + 31n - BigInt(Math.clz32(Number(v >> len)))
+}
+
+/** @type {(v: bigint) => bigint} */
+export const clz32Log2 = v => {
+    if (v <= 0n) { return -1n }
+    let result = 31n
+    let i = 32n
+    while (true) {
+        const n = v >> i
+        if (n === 0n) {
+            // overshot
+            break
+        }
+        v = n
+        result += i
+        i <<= 1n
+    }
+    // We know that `v` is not 0 so it doesn't make sense to check `n` when `i` is 0.
+    // Because of this, We check if `i` is greater than 32 before we divide it by 2.
+    while (i !== 32n) {
+        i >>= 1n
+        const n = v >> i
+        if (n !== 0n) {
+            result += i
+            v = n
+        }
+    }
+    return result - BigInt(Math.clz32(Number(v)))
+}
+
+/** @type {(v: bigint) => bigint} */
+const m1023log2 = v => {
+    if (v <= 0n) { return -1n }
+
+    //
+    // 1. Fast Doubling.
+    //
+
+    let result = -1n
+    // `bigints` higher than 2**1023 may lead to `Inf` during conversion to `number`.
+    // For example: `Number((1n << 1024n) - (1n << 970n)) === Inf`.
+    let i = 1023n
+    while (true) {
+        const n = v >> i
+        if (n === 0n) {
+            // overshot
+            break
+        }
+        v = n
+        result += i
+        i <<= 1n
+    }
+
+    //
+    // 2. Binary Search.
+    //
+
+    // We know that `v` is not 0 so it doesn't make sense to check `n` when `i` is 0.
+    // Because of this, We check if `i` is greater than 1023 before we divide it by 2.
+    while (i !== 1023n) {
+        i >>= 1n
+        const n = v >> i
+        if (n !== 0n) {
+            result += i
+            v = n
+        }
+    }
+
+    //
+    // 3. Remainder Phase.
+    //
+
+    // We know that `v` is less than `1n << 1023` so we can calculate a remainder using
+    // `Math.log2`.
+    const rem = BigInt(Math.log2(Number(v)) | 0)
+    // (v >> rem) is either `0` or `1`, and it's used as a correction for
+    // Math.log2 rounding.
+    return result + rem + (v >> rem)
+}
+
+/** @typedef {(f: (_: bigint) => bigint) => () => void} _Benchmark */
+
+/** @type {_Benchmark} */
+const benchmark = f => () => {
+    let e = 1_048_575n
+    let c = 1n << e
+    for (let i = 0n; i < 1_100; ++i) {
+        {
+            const x = f(c)
+            assertEq(x, e)
+        }
+        {
+            const x = f(c - 1n)
+            assertEq(x, e - 1n, [e, x])
+        }
+        c >>= 1n
+        --e
+    }
+}
+
+
+/** @type {_Benchmark} */
+const benchmarkSmall = f => () => {
+    let e = 2_000n
+    let c = 1n << e
+    do {
+        {
+            const x = f(c)
+            assertEq(x, e, [e, x])
+        }
+        for (let j = 1n; j < min(c >> 1n)(1000n); ++j) {
+            const x = f(c - j)
+            assertEq(x, e - 1n, [j, e, x])
+        }
+        c >>= 1n
+        --e
+    } while (c !== 0n)
+}
+
+export const proof = {
+    example: () => {
+        const total = sum([1n, 2n, 3n]) // 6n
+        assertEq(total, 6n)
+
+        const absoluteValue = abs(-42n) // 42n
+        assertEq(absoluteValue, 42n)
+
+        const logValue = log2(8n) // 3n
+        assertEq(logValue, 3n)
+
+        const bitCount = bitLength(255n) // 8n
+        assertEq(bitCount, 8n)
+
+        const bitmask = mask(5n) // 31n
+        assertEq(bitmask, 31n, benchmark)
+
+        const m = min(3n)(13n) // 3n
+        assertEq(m, 3n)
+
+        const c = combination(3n, 2n, 1n) // 60n
+        assertEq(c, 60n)
+    },
+    benchmark: () => {
+        const list = {
+            // strBinLog2,
+            // strHexLog2,
+            str32Log2,
+            // oldLog2,
+            // clz32Log2,
+            // m1023log2,
+            log2,
+        }
+        const transform = (/** @type {_Benchmark} */ b) =>
+            Object.fromEntries(Object.entries(list).map(([k, f]) => [k, b(f)]))
+        return {
+            big: transform(benchmark),
+            small: transform(benchmarkSmall),
+        }
+    },
+    mask: () => {
+        const result = mask(3n) // 7n
+        assertEq(result, 7n)
+    },
+    sum: () => {
+        const result = sum([2n, 3n, 4n, 5n])
+        assertEq(result, 14n)
+    },
+    abs: [
+        () => {
+            const result = abs(10n)
+            assertEq(result, 10n)
+        },
+        () => {
+            const result = abs(-10n)
+            assertEq(result, 10n)
+        }
+    ],
+    serialize: [
+        () => {
+            const result = serialize(0n)
+            assertEq(result, '0n')
+        },
+        () => {
+            const result = serialize(123456789012345678901234567890n)
+            assertEq(result, '123456789012345678901234567890n')
+        },
+        () => {
+            const result = serialize(-55555n)
+            assertEq(result, '-55555n')
+        },
+    ],
+    log2: [
+        () => {
+            const result = log2(-3n)
+            assertEq(result, -1n)
+        },
+        () => {
+            const result = log2(0n)
+            assertEq(result, -1n)
+        },
+        () => {
+            const result = log2(1n)
+            assertEq(result, 0n)
+        },
+        () => {
+            const result = log2(2n)
+            assertEq(result, 1n)
+        },
+        () => {
+            const result = log2(3n)
+            assertEq(result, 1n)
+        },
+        () => {
+            const result = log2(4n)
+            assertEq(result, 2n)
+        },
+        () => {
+            const result = log2(7n)
+            assertEq(result, 2n)
+        },
+        () => {
+            const result = log2(8n)
+            assertEq(result, 3n)
+        },
+        () => {
+            const result = log2(15n)
+            assertEq(result, 3n)
+        },
+        () => {
+            const result = log2(16n)
+            assertEq(result, 4n)
+        },
+        () => {
+            // max for Bun (131_072 Bytes)
+            const v = 1_048_575n
+            const result = log2(1n << v)
+            assertEq(result, v)
+        },
+        () => {
+            const v = 0x18945n
+            const result = log2(v)
+            assertEq(result, 16n)
+        }
+    ],
+    toString2: () => {
+        // max for Bun (131_072 Bytes)
+        const v = 1_048_575n
+        const result = (1n << v).toString(2).length - 1
+        assertEq(result, 1_048_575)
+    },
+    minus: () => {
+        let i = 0n
+        while (i < 1_048_575n) {
+            const s = -i
+            assertEq(i, -s, [i, s])
+            i += 1n
+        }
+    },
+    not: () => {
+        let i = 0n
+        while (i < 1_048_575n) {
+            const s = ~i
+            assertEq(i, ~s, [i, s])
+            i += 1n
+        }
+    },
+    bitLen: {
+        0: () => {
+            const s = bitLength(0n)
+            assertEq(s, 0n)
+        },
+        m: () => {
+            let i = 0n
+            while (i < 10_000n) {
+                const s = bitLength(1n << i)
+                assertEq(s, i + 1n, [s, i])
+                i += 1n
+            }
+        },
+        big: () => {
+            const s = bitLength(1n << 1_000_000n)
+            assertEq(s, 1_000_001n)
+        },
+        neg: [
+            () => {
+                const s = bitLength(-1n)
+                assertEq(s, 1n)
+            },
+            () => {
+                const s = bitLength(-2n)
+                assertEq(s, 2n)
+            },
+            () => {
+                const s = bitLength(-3n)
+                assertEq(s, 2n)
+            },
+            () => {
+                const s = bitLength(-4n)
+                assertEq(s, 3n)
+            },
+        ]
+    },
+    factorial: () => {
+        {
+            const r = factorial(3n)
+            assertEq(r, 6n)
+        }
+        {
+            const r = factorial(5n)
+            assertEq(r, 120n)
+        }
+    },
+    combination: () => {
+        const r = combination(2n, 3n)
+        assert(r == 120n / (2n * 6n), r)
+    },
+    combination50x50: () => {
+        {
+            const r = combination(1n, 1n)
+            assertEq(r, 2n)
+        }
+        {
+            const r = combination(2n, 2n)
+            assertEq(r, 6n)
+        }
+        {
+            const r = combination(3n, 3n)
+            assertEq(r, 20n)
+        }
+        {
+            const r = combination(4n, 4n)
+            assertEq(r, 70n)
+        }
+    },
+    combination3: () => {
+        const r = combination(2n, 3n, 4n, 2n)
+        // 2! * 3! * 4! * 2! : 2! * 2! * 3!
+        // 2+3+4+2 = 5*6*7*8*9*10*11
+        // e = 5 * 6 * 7 * 8 * 9 * 10 * 11 / (2n * 2n * 6n) =
+        // e = 5     * 7 * 2 * 9 * 10 * 11 = 69300
+        assertEq(r, 69300n)
+    },
+    divUp: () => {
+        assertEq(divUp(8n)(0b1000n), 1n)
+        assertEq(divUp(8n)(0b1111n), 2n)
+    },
+    roundUp: () => {
+        assertEq(roundUp(8n)(0b1000n), 0b1000n)
+        assertEq(roundUp(8n)(0b1111n), 0b10000n)
+        assertEq(roundUp(8n)(3n), 8n)
+    },
+    divUp8: () => {
+        assertEq(divUp8(0n), 0n)
+        assertEq(divUp8(1n), 1n)
+        assertEq(divUp8(0b1000n), 1n)
+        assertEq(divUp8(8n), 1n)
+        assertEq(divUp8(9n), 2n)
+        assertEq(divUp8(0b1111n), 2n)
+    },
+    roundUp8: () => {
+        assertEq(roundUp8(0n), 0n)
+        assertEq(roundUp8(1n), 8n)
+        assertEq(roundUp8(3n), 8n)
+        assertEq(roundUp8(0b1000n), 0b1000n)
+        assertEq(roundUp8(8n), 8n)
+        assertEq(roundUp8(9n), 16n)
+        assertEq(roundUp8(0b1111n), 0b10000n)
+    },
+    xor: () => {
+        assertEq(xor(5n)(3n), 6n)
+        assertEq(xor(0n)(15n), 15n)
+        assertEq(xor(0xFFn)(0xF0n), 0x0Fn)
+    },
+    multiple: () => {
+        assertEq(multiple(3n)(4n), 12n)
+        assertEq(multiple(0n)(100n), 0n)
+    },
+    product: () => {
+        assertEq(product([1n, 2n, 3n, 4n]), 24n)
+        assertEq(product([5n, 6n]), 30n)
+    },
+}

package/fjs/types/bigint/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Operator types specialized to `bigint`.
+ *
+ * @module
+ */
+import type { Unary as OpUnary, Reduce as OpReduce } from '../function/operator/types.ts';
+/**
+ * Type representing a unary operation on `bigint`.
+ */
+export type Unary = OpUnary<bigint, bigint>;
+/**
+ * Type representing a reduction operation on `bigint` values.
+ */
+export type Reduce = OpReduce<bigint>;

package/fjs/types/bigint/types.js

@@ -0,0 +1,6 @@
+/**
+ * Operator types specialized to `bigint`.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,199 @@
+/**
+ * Bit vectors that normalize the most-significant bit using signed `bigint` values.
+ *
+ * A value whose top bit is already set remains positive, while other values are
+ * negated after toggling the leading bit so the stop bit is always `1`. The sign bit
+ * therefore acts as the stop bit that encodes the logical length of the vector.
+ *
+ * MSb is most-significant bit first.
+ *
+ * ```
+ * - byte: 0x53 = 0b0101_0011
+ * -                0123_4567
+ * ```
+ *
+ * LSb is least-significant bit first.
+ *
+ * ```
+ * - byte: 0x53 = 0b0101_0011
+ * -                7654_3210
+ * ```
+ *
+ * @module
+ */
+import { maxLength } from '../bigint/module.f.mjs';
+import type { Fold } from '../function/operator/types.ts';
+import type { Accumulator, List, Thunk } from '../list/types.ts';
+import type { Sign } from '../function/compare/types.ts';
+import type { Nullable } from '../nullable/types.ts';
+import type { BitOrder, Unpacked, Vec, _NormOp } from './types.ts';
+/** @import { Nullable } from '../nullable/types.ts' */
+/**
+ * @import {
+ *  BitOrder, PopFront, Reduce, Unpacked, Vec,
+ *  _NormOp, _UnpackConcat,
+ * } from './types.ts'
+ */
+/**
+ * Maximum length of a bit vector in bits (1_048_576 = 0x10_0000).
+ * This limit is enforced by Bun's `bigint` size constraint, the minimal limit
+ * across all runtime environments supported by FunctionalScript.
+ */
+export { maxLength };
+export declare const maxLengthBytes: bigint;
+/**
+ * An empty vector of bits.
+ *
+ * @type {Vec}
+ */
+export declare const empty: Vec;
+/**
+ * Calculates the length of the given vector of bits.
+ *
+ * @type {(v: Vec) => bigint}
+ */
+export declare const length: (v: Vec) => bigint;
+/**
+ * Creates a vector of bits of the given `len` and the provided unsigned integer.
+ *
+ * @example
+ *
+ * ```js
+ * const vec4 = vec(4n)
+ * const v0 = vec4(5n)     // -0xDn = -0b1101
+ * const v1 = vec4(0x5FEn) //  0xEn =  0b1110
+ * ```
+ *
+ * @type {(len: bigint) => (ui: bigint) => Vec}
+ */
+export declare const vec: (len: bigint) => (ui: bigint) => Vec;
+/**
+ * Creates an 8-bit vector from an unsigned integer.
+ */
+export declare const vec8: (ui: bigint) => Vec;
+/**
+ * Builds a vector from a bigint whose most-significant set bit is a sentinel
+ * marking the start of the data.
+ *
+ * The sentinel does double duty: it fixes the length (`bitLength - 1`) and is
+ * stripped from the result. This lets a plain hex literal carry leading zero
+ * bits that would otherwise be lost — write `0x1` ahead of the data and the
+ * `1` both delimits and disappears.
+ *
+ * @example
+ *
+ * ```js
+ * uint(fromSentinel(0x1_89_50n))   // 0x8950n
+ * length(fromSentinel(0x1_89_50n)) // 16n — the two data bytes, sentinel gone
+ * fromSentinel(0x1_00_05n)         // a 16-bit vector holding 0x0005
+ * ```
+ *
+ * @type {(raw: bigint) => Vec}
+ */
+export declare const fromSentinel: (raw: bigint) => Vec;
+/**
+ * Returns the unsigned integer representation of the vector by clearing the stop bit.
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0x5n) // -0x85n
+ * const result = uint(vector); // result is 0x5n
+ * ```
+ *
+ * @type {(v: Vec) => bigint}
+ */
+export declare const uint: (v: Vec) => bigint;
+/**
+ * Extracts the logical length and unsigned integer from the vector.
+ *
+ * @type {(v: Vec) => Unpacked}
+ */
+export declare const unpack: (v: Vec) => Unpacked;
+/**
+ * Packs an unpacked representation back into a vector.
+ *
+ * @type {({ length, uint }: Unpacked) => Vec}
+ */
+export declare const pack: ({ length, uint }: Unpacked) => Vec;
+/** @type {({ uint }: Unpacked) => bigint} */
+export declare const unpackedUint: ({ uint }: Unpacked) => bigint;
+export type _Base = {
+    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];
+    readonly unpackConcatUint: (a: Unpacked) => (b: Unpacked) => bigint;
+};
+export type _ListToVecState = {
+    readonly len: bigint;
+    readonly stack: readonly Unpacked[];
+};
+export type _ListToVecOp = Accumulator<Unpacked, _ListToVecState, Vec>;
+/**
+ * Implements operations for handling vectors in a least-significant-bit (LSb) first order.
+ *
+ * https://en.wikipedia.org/wiki/Bit_numbering#LSb_0_bit_numbering
+ *
+ * Usually associated with Little-Endian (LE) byte order.
+ */
+export declare const lsb: BitOrder;
+/**
+ * Implements operations for handling vectors in a most-significant-bit (MSb) first order.
+ *
+ * https://en.wikipedia.org/wiki/Bit_numbering#MSb_0_bit_numbering
+ *
+ * Usually associated with Big-Endian (BE) byte order.
+ */
+export declare const msb: BitOrder;
+/**
+ * Converts a list of unsigned 8-bit integers to a bit vector using the provided
+ * bit order, like `u8ListToVec`, but returns `null` instead of throwing when the
+ * result would exceed `maxLength`.
+ *
+ * @type {(_: BitOrder) => (list: List<number>) => Nullable<Vec>}
+ */
+export declare const tryU8ListToVec: (_: BitOrder) => (list: List<number>) => Nullable<Vec>;
+/**
+ * Converts a list of unsigned 8-bit integers to a bit vector using the provided bit order.
+ *
+ * @param {BitOrder} bo The bit order for the conversion
+ * @param list The list of unsigned 8-bit integers to be converted.
+ * @returns The resulting vector based on the provided bit order.
+ */
+export declare const u8ListToVec: (bo: BitOrder) => (_: List<number>) => Vec;
+/**
+ * Chunks an unpacked vector into fixed-size pieces of `n` bits using the provided bit order,
+ * returning each chunk as an unsigned integer.
+ * The last chunk may be smaller than `n` bits if the vector length is not a multiple of `n`.
+ *
+ * @type {(bo: BitOrder) => (n: bigint) => (u: Unpacked) => Thunk<bigint>}
+ */
+export declare const uintChunkList: (bo: BitOrder) => (n: bigint) => (u: Unpacked) => Thunk<bigint>;
+/**
+ * Chunks a bit vector into fixed-size pieces of `n` bits using the provided bit order.
+ * The last chunk may be smaller than `n` bits if the vector length is not a multiple of `n`.
+ *
+ * @type {(bo: BitOrder) => (n: bigint) => (v: Vec) => Thunk<Vec>}
+ */
+export declare const chunkList: (bo: BitOrder) => (n: bigint) => (v: Vec) => Thunk<Vec>;
+/**
+ * Converts a bit vector to a list of unsigned 8-bit integers based on the provided bit order.
+ *
+ * @type {(bo: BitOrder) => (v: Vec) => Thunk<number>}
+ */
+export declare const u8List: (bo: BitOrder) => (v: Vec) => Thunk<number>;
+/**
+ * Repeats a vector to create a padded block of the desired length.
+ *
+ * @type {Fold<bigint, Vec>}
+ */
+export declare const repeat: Fold<bigint, Vec>;
+export declare const isVec: <T>(
+/**
+ * @template T
+ * @param {Vec | T} v
+ * @return {v is Vec}
+ */
+v: Vec | T) => v is Vec;