functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,365 @@
+/**
+ * @import { Unknown } from '../../media/json/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'
+import { addition, strictEqual, reduceToScan } from '../function/operator/module.f.mjs'
+import { assert, assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
+
+/** @type {(sequence: List<Unknown>) => string} */
+const str = sequence => stringify(sort)(toArray(sequence))
+
+const stringifyTest = () => {
+    const s = str([1, 2, 3])
+    assertEq(s, '[1,2,3]')
+}
+
+const cycleTest = [
+    () => {
+        const x = str(toArray(take(10)(cycle([1, 2, 3]))))
+        assertEq(x, '[1,2,3,1,2,3,1,2,3,1]')
+    },
+    () => {
+        const x = str(toArray(cycle([])))
+        assertEq(x, '[]')
+    },
+]
+
+const countdownTest = () => {
+    const result = str(countdown(10))
+    assertEq(result, '[9,8,7,6,5,4,3,2,1,0]')
+}
+
+const flatTest = () => {
+    const result = str(flat([[1, 2, 3], [4, 5], [6], [], [7, 8, 9]]))
+    assertEq(result, '[1,2,3,4,5,6,7,8,9]')
+}
+
+const concatTest = () => {
+    const result = concat([1])([2])
+    const x = assertNotNullish(next(result))
+    assertEq(x.first, 1, x)
+}
+
+const flatMapTest = () => {
+    const result = str(flatMap((/** @type {number} */ x) => [x, x * 2, x * 3])([0, 1, 2, 3]))
+    assertEq(result, '[0,0,0,1,2,3,2,4,6,3,6,9]')
+}
+
+const takeTest = [
+    () => {
+        const result = str(take(3)([1, 2, 3, 4, 5, 6, 7, 8, 9]))
+        assertEq(result, '[1,2,3]')
+    },
+    () => {
+        const result = str(take(20)([1, 2, 3, 4, 5, 6, 7, 8, 9]))
+        assertEq(result, '[1,2,3,4,5,6,7,8,9]')
+    },
+    () => {
+        const result = str(take(0)([1, 2, 3, 4, 5, 6, 7, 8, 9]))
+        assertEq(result, '[]')
+    }
+]
+
+const findTest = [
+    () => {
+        const result = find(null)((/** @type {number} */ x) => x % 2 === 0)([1, 3, 5, 7])
+        assertEq(result, null)
+    },
+    () => {
+        const result = find(null)((/** @type {number} */ x) => x % 2 === 0)([1, 2, 3, 4])
+        assertEq(result, 2)
+    }
+]
+
+const takeWhileTest = [
+    () => {
+        const result = str(takeWhile((/** @type {number} */ x) => x < 10)([1, 2, 3, 4, 5, 10, 11]))
+        assertEq(result, '[1,2,3,4,5]')
+    },
+    () => {
+        const result = str(takeWhile((/** @type {number} */ x) => x < 6)([1, 2, 3, 4, 5, 6, 7, 8, 9]))
+        assertEq(result, '[1,2,3,4,5]')
+    }
+]
+
+const dropWhileTest = () => {
+    const result = str(dropWhile((/** @type {number} */ x) => x < 10)([1, 2, 3, 4, 5, 10, 11]))
+    assertEq(result, '[10,11]')
+}
+
+const dropTest = [
+    () => {
+        const result = str(drop(3)([1, 2, 3, 4, 5, 10, 11]))
+        assertEq(result, '[4,5,10,11]')
+    },
+    () => {
+        const result = str(drop(0)([1, 2, 3, 4, 5, 10, 11]))
+        assertEq(result, '[1,2,3,4,5,10,11]')
+    },
+    () => {
+        const result = str(drop(10)([1, 2, 3, 4, 5, 10, 11]))
+        assertEq(result, '[]')
+    }
+]
+
+const additionTests = [
+    () => {
+        const op = reduceToScan(addition)
+        const result = str(scan(op)([2, 3, 4, 5]))
+        assertEq(result, '[2,5,9,14]')
+    },
+    () => {
+        const result = reduce(addition)(null)([2, 3, 4, 5])
+        assertEq(result, 14)
+    },
+    () => {
+        const result = reduce(addition)(null)([])
+        assertEq(result, null)
+    }
+]
+
+const entriesTest = [
+    () => {
+        const result = str(entries([]))
+        assertEq(result, '[]')
+    },
+    () => {
+        const result = str(entries(['hello', 'world']))
+        assertEq(result, '[[0,"hello"],[1,"world"]]')
+    }
+]
+
+const sumUpTo = (/** @type {number} */ limit) => ({
+    init: 0,
+    update: (/** @type {number} */ i, /** @type {number} */ state) => {
+        const next = state + i
+        return next > limit ? null : next
+    },
+    end: (/** @type {number} */ state) => state * 10,
+})
+
+const tryFoldTest = /** @type {const} */ ([
+    () => {
+        const result = tryFold(sumUpTo(100))([1, 2, 3])
+        assertEq(result, 60)
+    },
+    () => {
+        const result = tryFold(sumUpTo(4))([1, 2, 3])
+        assertEq(result, null)
+    },
+    () => {
+        const result = tryFold(sumUpTo(100))([])
+        assertEq(result, 0)
+    },
+])
+
+const reverseTest = [
+    () => {
+        const result = str(reverse([]))
+        assertEq(result, '[]')
+    },
+    () => {
+        const result = str(reverse([1, 2, 3, 4, 5]))
+        assertEq(result, '[5,4,3,2,1]')
+    }
+]
+
+const zipTest = [
+    () => {
+        const result = str(zip([0, 1, 2])(['a', 'b', 'c', 'd']))
+        assertEq(result, '[[0,"a"],[1,"b"],[2,"c"]]')
+    },
+    () => {
+        const result = str(zip([0, 1, 2])(['a', 'b']))
+        assertEq(result, '[[0,"a"],[1,"b"]]')
+    }
+]
+
+const logic = () => {
+    const map5 = map((/** @type {number} */ x) => x > 5)
+
+    return [
+        () => {
+            const result = some(map5([0, 1, 7]))
+            assert(result, result)
+        },
+        () => {
+            const result = some(map5([0, 1, 4]))
+            assert(!(result), result)
+        },
+        () => {
+            const result = some(map5([]))
+            assert(!(result), result)
+        },
+        () => {
+            const result = every(map5([0, 1, 7]))
+            assert(!(result), result)
+        },
+        () => {
+            const result = every(map5([6, 11, 7]))
+            assert(result, result)
+        },
+        () => {
+            const result = every(map5([]))
+            assert(result, result)
+        }
+    ]
+}
+
+// stress tests
+
+const stress = () => ({
+    toArray: () => {
+        // 200_000_000 is too much
+        const n = 100_000_000
+        const result = toArray(countdown(n))
+        assertEq(result.length, n)
+        const len = length(filter((/** @type {number} */ x) => x > n)(result))
+        assertEq(len, 0)
+    },
+    first: () => {
+        // 100_000_000 is too much
+        const n = 50_000_000
+        const result = toArray(countdown(n))
+        assertEq(result.length, n)
+        const f = first(null)(result)
+        assertEq(f, n - 1)
+    },
+    concatBack: () => {
+        /** @type {List<number>} */
+        let sequence = []
+        // 20_000_000 is too much
+        // 10_000_000 is too much for Deno 1
+        for (let i = 0; i < 5_000_000; ++i) {
+            sequence = concat(sequence)([i])
+        }
+        const r = toArray(sequence)
+    },
+    flatToArray: () => {
+        /** @type {List<number>} */
+        let sequence = []
+        // 4_000_000 is too much
+        for (let i = 0; i < 2_000_000; ++i) {
+            sequence = flat([sequence, [i]])
+        }
+        const r = toArray(sequence)
+    },
+    flatNext: () => {
+        /** @type {List<number>} */
+        let sequence = []
+        // 4_000_000 is too much
+        for (let i = 0; i < 2_000_000; ++i) {
+            sequence = flat([sequence, [i]])
+        }
+        const a = next(sequence)
+    },
+    concatFront: () => {
+        /** @type {List<number>} */
+        let sequence = []
+        // 20_000_000 is too much
+        for (let i = 0; i < 10_000_000; ++i) {
+            sequence = concat([i])(sequence)
+        }
+        const a = next(sequence)
+    },
+    flatFront: () => {
+        /** @type {List<number>} */
+        let sequence = []
+        // 10_000_000 is too much
+        for (let i = 0; i < 5_000_000; ++i) {
+            sequence = flat([[i], sequence])
+        }
+        const a = next(sequence)
+    },
+    filterMap: () => {
+        // 100_000_000 is too much
+        const n = 50_000_000
+        const result = toArray(countdown(n))
+        assertEq(result.length, n)
+        const len = length(filterMap(() => null)(result))
+        assertEq(len, 0)
+    },
+    dropWhile: () => {
+        // 50_000_000 is too much
+        const n = 20_000_000
+        const result = toArray(countdown(n))
+        assertEq(result.length, n)
+        const len = length(dropWhile(() => true)(result))
+        assertEq(len, 0)
+    },
+    reverse: () => {
+        // 10_000_000 is too much
+        const n = 5_000_000
+        const result = toArray(reverse(countdown(n)))
+        assertEq(result.length, n)
+    }
+
+})
+
+export const proof = {
+    stringifyTest,
+    cycle: cycleTest,
+    countdown: countdownTest,
+    flat: flatTest,
+    concat: concatTest,
+    flatMap: flatMapTest,
+    take: takeTest,
+    find: findTest,
+    takeWhile: takeWhileTest,
+    dropWhile: dropWhileTest,
+    drop: dropTest,
+    additionTests,
+    entries: entriesTest,
+    tryFold: tryFoldTest,
+    reverse: reverseTest,
+    zip: zipTest,
+    logic,
+    strictEqual: [
+        () => {
+            const result = equal(strictEqual)([1])([2, 3])
+            assert(!(result), result)
+        },
+        () => {
+            const result = equal(strictEqual)([1, 3])([1])
+            assert(!(result), result)
+        },
+        () => {
+            const result = equal(strictEqual)([15, 78])([15, 78])
+            assert(result, result)
+        },
+        () => {
+            const result = equal(strictEqual)([])([])
+            assert(result, result)
+        }
+    ],
+    isEmpty: [
+        () => {
+            const result = isEmpty(() => [])
+            assertEq(result, true)
+        },
+        () => {
+            const result = isEmpty(() => [2])
+            assertEq(result, false)
+        }
+    ],
+    length: () => {
+        assertEq(length([1, 2, 3]), 3)
+        assertEq(length(null), 0)
+        assertEq(length(flat([[1, 3], null, () => [3], concat([12])([4, 89])])), 6)
+    },
+    filterMap: [
+        () => {
+            const result = str(filterMap((/** @type {number} */ x) => x % 2 === 0 ? x * 10 : null)([1, 2, 3, 4, 5]))
+            assertEq(result, '[20,40]')
+        },
+        () => {
+            const result = str(filterMap((/** @type {number} */ x) => x > 3 ? x : null)([1, 2, 3]))
+            assertEq(result, '[]')
+        },
+    ],
+    // stress
+}

package/fjs/types/list/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for the immutable list data structure.
+ *
+ * @module
+ */
+import type { Nullable } from '../nullable/types.ts';
+export type List<T> = NotLazy<T> | Thunk<T>;
+export type NotLazy<T> = Result<T> | Concat<T> | readonly T[];
+export type Empty = null;
+export type Result<T> = Empty | NonEmpty<T>;
+export type Thunk<T> = () => List<T>;
+/**
+ * See also https://en.wikipedia.org/wiki/Cons#Lists
+ */
+export type NonEmpty<T> = {
+    readonly first: T;
+    readonly tail: List<T>;
+};
+export type Concat<T> = {
+    readonly head: List<T>;
+    readonly tail: List<T>;
+};
+/**
+ * A fold that can bail out early, packaged as plain data.
+ *
+ * `init` is the starting state, `update` advances the state by one item and
+ * returns `null` to abort the whole fold, and `end` finalizes the surviving
+ * state into a result. Keeping the three parts together lets `tryFold` drive
+ * any short-circuiting accumulation without knowing its domain.
+ */
+export type Accumulator<I, T, R> = {
+    readonly init: T;
+    readonly update: (i: I, state: T) => Nullable<T>;
+    readonly end: (state: T) => R;
+};
+export type Entry<T> = readonly [number, T];

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

@@ -0,0 +1,13 @@
+/**
+ * Persistent map operations built on ordered collections.
+ *
+ * @module
+ */
+/**
+ * @type {<K, V>(map: ReadonlyMap<K, V>, k: K, v: V) => ReadonlyMap<K, V>}
+ */
+export declare const mapSet: <K, V>(map: ReadonlyMap<K, V>, k: K, v: V) => ReadonlyMap<K, V>;
+/**
+ * @type {<K, V>(map: ReadonlyMap<K, V>, k: K) => ReadonlyMap<K, V>}
+ */
+export declare const mapDelete: <K, V>(map: ReadonlyMap<K, V>, k: K) => ReadonlyMap<K, V>;

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

@@ -0,0 +1,42 @@
+/**
+ * Persistent map operations built on ordered collections.
+ *
+ * @module
+ */
+
+/**
+ * @template T
+ * @param {Iterable<T>} x
+ * @param {Iterable<T>} y
+ * @returns {Iterable<T>}
+ */
+const concat = (x, y) => ({
+    *[Symbol.iterator]() {
+        yield* x
+        yield* y
+    }
+})
+
+/**
+ * @template T
+ * @param {Iterable<T>} i
+ * @param {(x: T) => boolean} p
+ * @returns {Iterable<T>}
+ */
+const filter = (i, p) => ({
+    *[Symbol.iterator]() {
+        for (const x of i) {
+            if (p(x)) { yield x }
+        }
+    }
+})
+
+/**
+ * @type {<K, V>(map: ReadonlyMap<K, V>, k: K, v: V) => ReadonlyMap<K, V>}
+ */
+export const mapSet = (map, k, v) => new Map(concat(map, [[k, v]]))
+
+/**
+ * @type {<K, V>(map: ReadonlyMap<K, V>, k: K) => ReadonlyMap<K, V>}
+ */
+export const mapDelete = (map, k) => new Map(filter(map, ([xk]) => xk !== k))

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

@@ -0,0 +1,25 @@
+import { mapSet, mapDelete } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    set: () => {
+        const map = mapSet(new Map(), 'a', 'b')
+        assertEq(map.get('a'), 'b', 'error')
+        assertEq(map.size, 1, 'error')
+    },
+    delete: () => {
+        const map = mapDelete(mapSet(new Map(), 'a', 'b'), 'a')
+        assertEq(map.get('a'), undefined, 'error')
+        assertEq(map.size, 0, 'error')
+    },
+    deleteOneOfMany: () => {
+        /** @type {ReadonlyMap<string, number>} */
+        const empty = new Map()
+        const m0 = mapSet(empty, 'a', 1)
+        const m1 = mapSet(m0, 'b', 2)
+        const result = mapDelete(m1, 'a')
+        assertEq(result.get('b'), 2)
+        assertEq(result.get('a'), undefined)
+        assertEq(result.size, 1)
+    },
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Nibble-set operations for compact 4-bit membership tracking.
+ *
+ * A set of nibbles (values `0..15`) stored as a 16-bit mask in a plain
+ * `number`. It implements the same bitmask-as-set algebra as
+ * {@link ../byte_set/module.f.mjs | `byte_set`}, which tracks all 256 byte
+ * values in a `bigint`.
+ *
+ * **Prefer `byte_set`.** Its 256-value universe covers the common cases and
+ * it is the set type used across the codebase. Use `nibble_set` only when
+ * the set has to be serialized into JSON: a `NibbleSet` is a `number`, which
+ * round-trips through `JSON.stringify`/`JSON.parse` as-is, while a
+ * `ByteSet` is a `bigint`, which `JSON.stringify` cannot serialize.
+ *
+ * @module
+ *
+ * @import { Nibble, NibbleSet } from './types.ts'
+ */
+import type { Nibble, NibbleSet } from './types.ts';
+export declare const empty = 0;
+export declare const universe = 65535;
+/** @type {(n: Nibble) => (s: NibbleSet) => boolean} */
+export declare const has: (n: Nibble) => (s: NibbleSet) => boolean;
+/** @type {(n: Nibble) => (s: NibbleSet) => NibbleSet} */
+export declare const set: (n: Nibble) => (s: NibbleSet) => NibbleSet;
+/** @type {(n: NibbleSet) => NibbleSet} */
+export declare const complement: (n: NibbleSet) => NibbleSet;
+/** @type {(n: Nibble) => (s: NibbleSet) => NibbleSet} */
+export declare const unset: (n: Nibble) => (s: NibbleSet) => NibbleSet;
+/** @type {(r: readonly [number, number]) => (s: NibbleSet) => NibbleSet} */
+export declare const setRange: (r: readonly [number, number]) => (s: NibbleSet) => NibbleSet;

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

@@ -0,0 +1,43 @@
+/**
+ * Nibble-set operations for compact 4-bit membership tracking.
+ *
+ * A set of nibbles (values `0..15`) stored as a 16-bit mask in a plain
+ * `number`. It implements the same bitmask-as-set algebra as
+ * {@link ../byte_set/module.f.mjs | `byte_set`}, which tracks all 256 byte
+ * values in a `bigint`.
+ *
+ * **Prefer `byte_set`.** Its 256-value universe covers the common cases and
+ * it is the set type used across the codebase. Use `nibble_set` only when
+ * the set has to be serialized into JSON: a `NibbleSet` is a `number`, which
+ * round-trips through `JSON.stringify`/`JSON.parse` as-is, while a
+ * `ByteSet` is a `bigint`, which `JSON.stringify` cannot serialize.
+ *
+ * @module
+ *
+ * @import { Nibble, NibbleSet } from './types.ts'
+ */
+
+export const empty = 0
+
+export const universe = 0xFFFF
+
+/** @type {(n: Nibble) => NibbleSet} */
+const one = n => 1 << n
+
+/** @type {(n: Nibble) => (s: NibbleSet) => boolean} */
+export const has = n => s => ((s >> n) & 1) === 1
+
+/** @type {(n: Nibble) => (s: NibbleSet) => NibbleSet} */
+export const set = n => s => s | one(n)
+
+/** @type {(n: NibbleSet) => NibbleSet} */
+export const complement = s => universe ^ s
+
+/** @type {(n: Nibble) => (s: NibbleSet) => NibbleSet} */
+export const unset = n => s => s & complement(one(n))
+
+/** @type {(r: readonly [number, number]) => NibbleSet} */
+const range = ([a, b]) => one(b - a + 1) - 1 << a
+
+/** @type {(r: readonly [number, number]) => (s: NibbleSet) => NibbleSet} */
+export const setRange = r => s => s | range(r)

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

@@ -0,0 +1,59 @@
+import { every, map, countdown } from '../list/module.f.mjs'
+import { empty, has, set, setRange, unset, universe, complement } from './module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    has: () => {
+        assert(!(has(0)(empty)), empty)
+        assert(!(has(1)(empty)), empty)
+        assert(!(has(15)(empty)), empty)
+    },
+    set: [
+        () => {
+            const s = set(0)(empty)
+            if(s !== 1) { throw s }
+            if(!has(0)(s)) { throw s }
+            assert(!(has(1)(s)), s)
+            assert(!(has(15)(s)), s)
+        },
+        () => {
+            const s = set(15)(empty)
+            assertEq(s, 0x8000)
+            assert(!(has(0)(s)), s)
+            assert(!(has(1)(s)), s)
+            assert(has(15)(s), s)
+        }
+    ],
+    unset: () => [
+        () => {
+            const a = set(0)(empty)
+            const result = unset(0)(a)
+            assertEq(result, 0)
+        },
+        () => {
+            const a = set(15)(empty)
+            const result = unset(15)(a)
+            assertEq(result, 0)
+        }
+    ],
+    setRange: () => {
+        const result = setRange([2, 5])(empty)
+        assertEq(result, 60)
+    },
+    universe: () => {
+        /** @type {(v: number) => boolean} */
+        const hasInUniverse = v => has(v)(universe)
+        const x = every(map(hasInUniverse)(countdown(16)))
+        assert(x, x)
+    },
+    compliment: {
+        empty: () => {
+            const r = complement(empty)
+            assertEq(r, universe)
+        },
+        universe: () => {
+            const r = complement(universe)
+            assertEq(r, empty)
+        },
+    }
+}

package/fjs/types/nibble_set/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Types for compact 4-bit membership tracking.
+ *
+ * @module
+ */
+/** A set of nibbles as a 16-bit mask. JSON-serializable. */
+export type NibbleSet = number;
+/** A 4-bit value, `0..15`. */
+export type Nibble = number;

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

@@ -0,0 +1,10 @@
+/**
+ * Nominal typing helpers for branded TypeScript types.
+ *
+ * @module
+ *
+ * @import { Nominal } from './types.ts'
+ */
+import type { 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

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

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

@@ -0,0 +1,7 @@
+/**
+ * @import { Nominal, _SymbolKeyBranded, _SymbolIntersectionBranded } from "./types.ts"
+ */
+export declare const proof: {
+    pre: () => void;
+    nominal: () => void;
+};