functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,86 @@
+/**
+ * @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'
+import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
+import { sort } from '../object/module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+/** @type {(a: readonly Unknown[]) => string} */
+const stringify = jsonStringify(sort)
+
+export const proof = {
+    has: [
+        () => {
+            assert(!(has(0)(empty)), empty)
+            assert(!(has(1)(empty)), empty)
+            assert(!(has(33)(empty)), empty)
+        },
+        () => {
+            const s = set(0)(empty)
+            assertEq(s, 1n)
+            assert(has(0)(s), s)
+            assert(!(has(1)(s)), s)
+            assert(!(has(33)(s)), s)
+        },
+        () => {
+            const s = set(33)(empty)
+            assertEq(s, 8589934592n)
+            assert(!(has(0)(s)), s)
+            assert(!(has(1)(s)), s)
+            assert(has(33)(s), s)
+        }
+    ],
+    setRange: () => {
+        const result = setRange([2, 5])(empty)
+        assertEq(result, 60n)
+    },
+    unset: [
+        () => {
+            const a = set(0)(empty)
+            const result = unset(0)(a)
+            assertEq(result, 0n)
+        },
+        () => {
+            const a = set(255)(empty)
+            const result = unset(255)(a)
+            assertEq(result, 0n)
+        }
+    ],
+    universe: () => {
+        const x = every(map((/** @type {any} */ v) => has(v)(universe))(countdown(256)))
+        assert(x, x)
+    },
+    compliment: {
+        empty: () => {
+            const r = complement(empty)
+            assertEq(r, universe)
+        },
+        universe: () => {
+            const r = complement(universe)
+            assertEq(r, empty)
+        },
+    },
+    toRangeMap: [
+        () => {
+            const result = stringify(toArray(toRangeMap(empty)('a')))
+            assertEq(result, '[]')
+        },
+        () => {
+            const s = set(0)(empty)
+            const result = stringify(toArray(toRangeMap(s)('a')))
+            assertEq(result, '[[["a"],0]]')
+        },
+        () => {
+            const s = setRange([1, 2])(empty)
+            const result = stringify(toArray(toRangeMap(s)('a')))
+            assertEq(result, '[[[],0],[["a"],2]]')
+        },
+        () => {
+            const result = stringify(toArray(toRangeMap(universe)('a')))
+            assertEq(result, '[[["a"],255]]')
+        },
+    ]
+}

package/fjs/types/byte_set/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type-level API for the byte-set module.
+ *
+ * @module
+ */
+export type ByteSet = bigint;

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

@@ -0,0 +1,45 @@
+/**
+ * Comparison function types and helpers.
+ *
+ * @module
+ *
+ * @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>} */
+export declare const index3: <T>(cmp: Compare<T>) => (value: T) => Index<3>;
+/** @type {<T>(cmp: Compare<T>) => (v2: Tuple<2, T>) => Index<5>} */
+export declare const index5: <T>(cmp: Compare<T>) => (v2: Tuple<2, T>) => Index<5>;
+/** @type {<A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => Sign} */
+export declare const cmp: <A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => Sign;
+/**
+ * Returns the smaller of two comparable values. The `Cmp2<A, B>` constraint
+ * is the same one `cmp` uses: it rejects calls that mix incompatible primitive
+ * types (e.g. `min(1)("a")`) at compile time.
+ *
+ * @type {<A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => A | B}
+ */
+export declare const min: <A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => A | B;
+/**
+ * Returns the larger of two comparable values. The `Cmp2<A, B>` constraint
+ * is the same one `cmp` uses: it rejects calls that mix incompatible primitive
+ * types (e.g. `max(1)("a")`) at compile time.
+ *
+ * @type {<A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => A | B}
+ */
+export declare const max: <A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => A | B;
+/**
+ * Binary search over `[0, len)`. `probe(mid)` returns the sign of the search
+ * key relative to the element at `mid` (`-1` before, `0` at, `1` after). On a
+ * hit it returns the matching index; on a miss it returns the converged lower
+ * bound `b` (the insertion point), which may equal `len`.
+ *
+ * `probe` must be monotonic over `[0, len)`: scanning indices left to right its
+ * result is non-increasing — a run of `1`s, then `0`s, then `-1`s. A
+ * non-monotonic probe yields an undefined position.
+ *
+ * @type {(len: number) => (probe: (mid: number) => Sign) => number}
+ */
+export declare const bsearch: (len: number) => (probe: (mid: number) => Sign) => number;

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

@@ -0,0 +1,72 @@
+/**
+ * Comparison function types and helpers.
+ *
+ * @module
+ *
+ * @import { Index, Tuple } from '../../array/types.ts'
+ * @import { Cmp1, Cmp2, Compare, Sign } from './types.ts'
+ */
+
+/** @type {<T>(cmp: Compare<T>) => (value: T) => Index<3>} */
+export const index3
+    = cmp => value => /** @type {Index<3>} */(cmp(value) + 1)
+
+/** @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)
+}
+
+/** @type {<A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => Sign} */
+export const cmp = a => b =>
+    /** @type {any} */(a) < b ? -1 : /** @type {any} */(a) > b ? 1 : 0
+
+/**
+ * Returns the smaller of two comparable values. The `Cmp2<A, B>` constraint
+ * is the same one `cmp` uses: it rejects calls that mix incompatible primitive
+ * types (e.g. `min(1)("a")`) at compile time.
+ *
+ * @type {<A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => A | B}
+ */
+export const min = a => b => cmp(a)(b) < 0 ? a : b
+
+/**
+ * Returns the larger of two comparable values. The `Cmp2<A, B>` constraint
+ * is the same one `cmp` uses: it rejects calls that mix incompatible primitive
+ * types (e.g. `max(1)("a")`) at compile time.
+ *
+ * @type {<A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => A | B}
+ */
+export const max = a => b => cmp(a)(b) > 0 ? a : b
+
+/**
+ * Binary search over `[0, len)`. `probe(mid)` returns the sign of the search
+ * key relative to the element at `mid` (`-1` before, `0` at, `1` after). On a
+ * hit it returns the matching index; on a miss it returns the converged lower
+ * bound `b` (the insertion point), which may equal `len`.
+ *
+ * `probe` must be monotonic over `[0, len)`: scanning indices left to right its
+ * result is non-increasing — a run of `1`s, then `0`s, then `-1`s. A
+ * non-monotonic probe yields an undefined position.
+ *
+ * @type {(len: number) => (probe: (mid: number) => Sign) => number}
+ */
+export const bsearch = len => probe => {
+    let b = 0
+    let e = len - 1
+    while (true) {
+        if (e < b) { return b }
+        const mid = b + (e - b >> 1)
+        switch (probe(mid)) {
+            case -1: {
+                e = mid - 1
+                break
+            }
+            case 0: { return mid }
+            case 1: {
+                b = mid + 1
+                break
+            }
+        }
+    }
+}

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

@@ -0,0 +1,50 @@
+import { cmp, min, max } from './module.f.mjs'
+import { assertEq } from '../../../asserts/module.f.mjs'
+
+export const proof = () => {
+    {
+        const result = cmp(true)(false)
+        assertEq(result, 1)
+        const _ = true < false
+    }
+    {
+        const result = cmp(1)(2)
+        assertEq(result, -1)
+        const _ = 1 < 2
+    }
+    {
+        const result = cmp(2n)(-10n)
+        assertEq(result, 1)
+        const _ = 2n < -10n
+    }
+    {
+        const result = cmp("hello")("hello")
+        assertEq(result, 0)
+        const _ = "hello" < "hello"
+    }
+    {
+        // const result = cmp(true)("hello") // compilation error
+        /** @type {string | number} */
+        const a = "hello"
+        /** @type {string | number} */
+        const b = 5
+        // const _ = cmp(a)(b) // compilation error
+        const _ = cmp(a)("hello") // ??? TypeScript changes a type definition of `a`.
+        // const f = (a: string|number, b: string|number) => cmp(a)(b) // compilation error
+        // const f = (a: number, b: string|number) => cmp(a)(b) // compilation error
+    }
+    {
+        assertEq(min(3)(5), 3, 'min(3)(5)')
+        assertEq(min(7)(2), 2, 'min(7)(2)')
+        assertEq(min(3n)(13n), 3n, 'min(3n)(13n)')
+        assertEq(min("a")("b"), "a", 'min("a")("b")')
+        // const _ = min(1)("a") // compilation error
+    }
+    {
+        assertEq(max(3)(5), 5, 'max(3)(5)')
+        assertEq(max(7)(2), 7, 'max(7)(2)')
+        assertEq(max(3n)(13n), 13n, 'max(3n)(13n)')
+        assertEq(max("a")("b"), "b", 'max("a")("b")')
+        // const _ = max(1)("a") // compilation error
+    }
+}

package/fjs/types/function/compare/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Comparison function types.
+ *
+ * @module
+ */
+export type Sign = -1 | 0 | 1;
+export type Compare<T> = (_: T) => Sign;
+export type Cmp<T> = (a: T) => Compare<T>;
+export type Cmp1 = boolean | string | number | bigint;
+export type Cmp2<A, B> = [
+    A,
+    B
+] extends [boolean, boolean] ? boolean : [
+    A,
+    B
+] extends [string, string] ? string : [
+    A,
+    B
+] extends [number, number] ? number : [
+    A,
+    B
+] extends [bigint, bigint] ? bigint : never;

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

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ *
+ * @type {<I, X>(g: Func<I, X>) => <O>(f: Func<X, O>) => Func<I, O>}
+ */
+export declare const compose: <I, X>(g: Func<I, X>) => <O>(f: Func<X, O>) => Func<I, O>;
+/**
+ * A generic identity function.
+ *
+ * @type {<T>(value: T) => T}
+ */
+export declare const identity: <T>(value: T) => T;
+/**
+ * Flips the arguments of a curried function.
+ *
+ * @type {<A, B, C>(f: (a: A) => (b: B) => C) => (b: B) => (a: A) => C}
+ */
+export declare const flip: <A, B, C>(f: (a: A) => (b: B) => C) => (b: B) => (a: A) => C;
+/**
+ * Creates an `Fn` instance from a function, enabling chaining of transformations.
+ *
+ * @type {<I, O>(result: Func<I, O>) => Fn<I, O>}
+ */
+export declare const fn: <I, O>(result: Func<I, O>) => Fn<I, O>;

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

@@ -0,0 +1,39 @@
+/**
+ * Function combinators: composition, identity, argument flipping, and the
+ * chainable `Fn` wrapper.
+ *
+ * @module
+ *
+ * @import { Func, Fn } from './types.ts'
+ */
+
+/**
+ * A postfix compose function.
+ *
+ * @type {<I, X>(g: Func<I, X>) => <O>(f: Func<X, O>) => Func<I, O>}
+ */
+export const compose = g => f => x => f(g(x))
+
+/**
+ * A generic identity function.
+ *
+ * @type {<T>(value: T) => T}
+ */
+export const identity = value => value
+
+/**
+ * Flips the arguments of a curried function.
+ *
+ * @type {<A, B, C>(f: (a: A) => (b: B) => C) => (b: B) => (a: A) => C}
+ */
+export const flip = f => b => a => f(a)(b)
+
+/**
+ * Creates an `Fn` instance from a function, enabling chaining of transformations.
+ *
+ * @type {<I, O>(result: Func<I, O>) => Fn<I, O>}
+ */
+export const fn = result => ({
+    result,
+    map: g => fn(compose(result)(g))
+})

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

@@ -0,0 +1,38 @@
+/**
+ * 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';
+/** @type {(separator: string) => Reduce<string>} */
+export declare const join: (separator: string) => Reduce<string>;
+/** @type {Reduce<string>} */
+export declare const concat: Reduce<string>;
+/** @type {Unary<boolean, boolean>} */
+export declare const logicalNot: Unary<boolean, boolean>;
+/**
+ * See also `Object.is` which should be used for deep comparison instead of the `structEqual`.
+ * TODO: add `binaryEqual = a => b => Object.is(a, b)`.
+ *
+ * @type {<T>(a: T) => (b: T) => boolean}
+ */
+export declare const strictEqual: <T>(a: T) => (b: T) => boolean;
+/** @type {<I, S, O>(op: StateScan<I, S, O>) => (prior: S) => Scan<I, O>} */
+export declare const stateScanToScan: <I, S, O>(op: StateScan<I, S, O>) => (prior: S) => Scan<I, O>;
+/** @type {<I, O>(fold: Fold<I, O>) => (prior: O) => Scan<I, O>} */
+export declare const foldToScan: <I, O>(fold: Fold<I, O>) => (prior: O) => Scan<I, O>;
+/** @type {<T>(op: Reduce<T>) => Scan<T, T>} */
+export declare const reduceToScan: <T>(op: Reduce<T>) => Scan<T, T>;
+/**
+ * TODO: We should have one function for `number` | `bigint` and `string`.
+ *       We can use the same approach as we use for comparing items,
+ *       see `Cmp1` and `Cmp2` types.
+ *
+ * @type {Reduce<number>}
+ */
+export declare const addition: Reduce<number>;
+/** @type {Unary<number, number>} */
+export declare const increment: Unary<number, number>;
+export declare const counter: () => Unary<number, number>;

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

@@ -0,0 +1,55 @@
+/**
+ * Common higher-order operator type aliases.
+ *
+ * @module
+ *
+ * @import { Fold, Reduce, Scan, StateScan, Unary } from './types.ts'
+ */
+
+/** @type {(separator: string) => Reduce<string>} */
+export const join = separator => value => prior =>
+    `${prior}${separator}${value}`
+
+/** @type {Reduce<string>} */
+export const concat = i => acc => `${acc}${i}`
+
+/** @type {Unary<boolean, boolean>} */
+export const logicalNot = v => !v
+
+/**
+ * See also `Object.is` which should be used for deep comparison instead of the `structEqual`.
+ * TODO: add `binaryEqual = a => b => Object.is(a, b)`.
+ *
+ * @type {<T>(a: T) => (b: T) => boolean}
+ */
+export const strictEqual = a => b => a === b
+
+/** @type {<I, S, O>(op: StateScan<I, S, O>) => (prior: S) => Scan<I, O>} */
+export const stateScanToScan = op => prior => i => {
+    const [o, s] = op(i, prior)
+    return [o, stateScanToScan(op)(s)]
+}
+
+/** @type {<I, O>(fold: Fold<I, O>) => (prior: O) => Scan<I, O>} */
+export const foldToScan = fold => prior => i => {
+    const result = fold(i)(prior)
+    return [result, foldToScan(fold)(result)]
+}
+
+/** @type {<T>(op: Reduce<T>) => Scan<T, T>} */
+export const reduceToScan = op => init =>
+    [init, foldToScan(op)(init)]
+
+/**
+ * TODO: We should have one function for `number` | `bigint` and `string`.
+ *       We can use the same approach as we use for comparing items,
+ *       see `Cmp1` and `Cmp2` types.
+ *
+ * @type {Reduce<number>}
+ */
+export const addition = a => b => a + b
+
+/** @type {Unary<number, number>} */
+export const increment = addition(1)
+
+export const counter = () => increment

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

@@ -0,0 +1,76 @@
+import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import {
+    join,
+    concat,
+    logicalNot,
+    strictEqual,
+    addition,
+    increment,
+    counter,
+    stateScanToScan,
+    foldToScan,
+    reduceToScan,
+} from './module.f.mjs'
+
+const joinTest = () => {
+    const result = join(', ')('world')('hello')
+    assertEq(result, 'hello, world')
+}
+
+const concatTest = () => {
+    const result = concat('world')('hello')
+    assertEq(result, 'helloworld')
+}
+
+const logicalNotTest = () => {
+    assertEq(logicalNot(true), false, 'expected false')
+    assertEq(logicalNot(false), true, 'expected true')
+}
+
+const strictEqualTest = () => {
+    assert(strictEqual(1)(1), 'expected true')
+    assert(!(strictEqual(1)(2)), 'expected false')
+}
+
+const additionTest = () => {
+    const result = addition(3)(4)
+    assertEq(result, 7)
+}
+
+const incrementTest = () => {
+    assertEq(increment(4), 5, 'increment(4)')
+    assertEq(increment(0), 1, 'increment(0)')
+}
+
+const foldToScanTest = () => {
+    const scan = foldToScan(addition)(0)
+    const [v1, scan2] = scan(3)
+    assertEq(v1, 3)
+    const [v2] = scan2(4)
+    assertEq(v2, 7)
+}
+
+const reduceToScanTest = () => {
+    const scan = reduceToScan(addition)
+    const [v0, scan2] = scan(10)
+    assertEq(v0, 10)
+    const [v1] = scan2(5)
+    assertEq(v1, 15)
+}
+
+const counterTest = () => {
+    const fn = counter()
+    assertEq(fn(4), 5, 'counter() returned wrong function')
+}
+
+const stateScanToScanTest = () => {
+    const op = (/** @type {number} */ input, /** @type {number} */ state) =>
+        /** @type {const} */ ([input + state, input + state])
+    const scan = stateScanToScan(op)(0)
+    const [v1, scan2] = scan(3)
+    assertEq(v1, 3)
+    const [v2] = scan2(4)
+    assertEq(v2, 7)
+}
+
+export const proof = { joinTest, concatTest, logicalNotTest, strictEqualTest, additionTest, incrementTest, counterTest, stateScanToScanTest, foldToScanTest, reduceToScanTest }

package/fjs/types/function/operator/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Common higher-order operator type aliases.
+ *
+ * @module
+ */
+export type Binary<A, B, R> = (a: A) => (b: B) => R;
+export type Fold<I, O> = Binary<I, O, O>;
+export type Reduce<T> = Fold<T, T>;
+export type Unary<T, R> = (value: T) => R;
+export type Equal<T> = Binary<T, T, boolean>;
+export type Scan<I, O> = (input: I) => readonly [O, Scan<I, O>];
+/**
+ * One step of a stream transducer: given an `input` symbol and the `prior`
+ * state, produce an `output` and the next state. It both maps an input stream
+ * to an output stream and threads state, so it models tokenizers, decoders, and
+ * other stream-to-stream stages.
+ *
+ * This is the *shape* of a [Mealy machine](https://en.wikipedia.org/wiki/Mealy_machine)
+ * — a [finite-state transducer](https://en.wikipedia.org/wiki/Finite-state_transducer)
+ * — but only its signature. The state `S` (and `I`, `O`) is an arbitrary type,
+ * not a finite set, so a `StateScan` is strictly more expressive than a Mealy
+ * machine — its power is the power of `S`:
+ * - a finite `S`/`I`/`O` recovers the classical finite-state machine (e.g. the
+ *   DFA states in `../../../fsm/module.f.mjs`);
+ * - an `S` that is a stack makes it a
+ *   [pushdown / stack machine](https://en.wikipedia.org/wiki/Pushdown_automaton)
+ *   (context-free power — balanced brackets, nested structure, the AST tier);
+ * - an unbounded `S` like `bigint` can count, which no finite automaton can.
+ *
+ * And `O` may be a list (0+ symbols per input), not the single symbol strict
+ * Mealy emits. (Functional/coalgebraic usage still calls this `(input, state)
+ * => [output, state]` shape a "Mealy machine", finiteness aside.)
+ *
+ * A {@link Fold} is the output-less special case (state only); driving a
+ * `StateScan` over a `List` is `stateScan` in `../../list/module.f.mjs`, and
+ * {@link ./module.f.mjs | `stateScanToScan`} hides the state to recover a
+ * {@link Scan}.
+ */
+export type StateScan<I, S, O> = (input: I, prior: S) => readonly [O, S];

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

@@ -0,0 +1,16 @@
+import { fn } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = () => {
+    /** @type {(x: string) => readonly [string]} */
+    const f = x => [x]
+    /** @type {(x: readonly [string]) => readonly [number]} */
+    const g = ([x]) => [x.length]
+    /** @type {(x: readonly [number]) => number} */
+    const w = ([x]) => x
+
+    const r = fn(f).map(g).map(w).result
+
+    const result = r('hello')
+    assertEq(result, 5, r)
+}

package/fjs/types/function/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Types for function composition.
+ *
+ * @module
+ */
+/**
+ * A generic function type.
+ */
+export type Func<I, O> = (_: I) => O;
+/**
+ * A functional utility type that enables seamless chaining of transformations.
+ */
+export type Fn<I, O> = {
+    readonly result: Func<I, O>;
+    readonly map: <T>(g: Func<O, T>) => Fn<I, T>;
+};