functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,54 @@
+/**
+ * A sorted set, implemented as a sorted array.
+ *
+ * @module
+ *
+ * @note
+ *
+ * All input arrays must be pre-sorted according to the provided comparison function (`Cmp<T>`).
+ * The correctness of these functions depend on this requirement.
+ *
+ * @example
+ *
+ * ```js
+ * import { union, intersect, has } from './module.f.mjs'
+ *
+ * const cmp = (a: number) => (b: number) => a < b ? -1 : a > b ? 1 : 0
+ *
+ * const setA = [1, 3, 5]
+ * const setB = [3, 4, 5]
+ *
+ * const unionSet = union(cmp)(setA)(setB) // [1, 3, 4, 5]
+ *
+ * const intersectionSet = intersect(cmp)(setA)(setB) // [3, 5]
+ *
+ * has(cmp)(3)(setA) // true
+ * has(cmp)(2)(setA) // false
+ * ```
+ *
+ * @import { Cmp } from '../function/compare/types.ts'
+ * @import { SortedSet } from './types.ts'
+ */
+import type { Cmp } from '../function/compare/types.ts';
+import type { SortedSet } from './types.ts';
+export declare const union: <T>(
+/**
+ * @template T
+ * @param {Cmp<T>} cmp
+ * @returns {(a: SortedSet<T>) => (b: SortedSet<T>) => SortedSet<T>}
+ */
+cmp: Cmp<T>) => (a: SortedSet<T>) => (b: SortedSet<T>) => SortedSet<T>;
+export declare const intersect: <T>(
+/**
+ * @template T
+ * @param {Cmp<T>} cmp
+ * @returns {(a: SortedSet<T>) => (b: SortedSet<T>) => SortedSet<T>}
+ */
+cmp: Cmp<T>) => (a: SortedSet<T>) => (b: SortedSet<T>) => SortedSet<T>;
+export declare const has: <T>(
+/**
+ * @template T
+ * @param {Cmp<T>} cmp
+ * @returns {(value: T) => (set: SortedSet<T>) => boolean}
+ */
+cmp: Cmp<T>) => (value: T) => (set: SortedSet<T>) => boolean;

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

@@ -0,0 +1,58 @@
+/**
+ * A sorted set, implemented as a sorted array.
+ *
+ * @module
+ *
+ * @note
+ *
+ * All input arrays must be pre-sorted according to the provided comparison function (`Cmp<T>`).
+ * The correctness of these functions depend on this requirement.
+ *
+ * @example
+ *
+ * ```js
+ * import { union, intersect, has } from './module.f.mjs'
+ *
+ * const cmp = (a: number) => (b: number) => a < b ? -1 : a > b ? 1 : 0
+ *
+ * const setA = [1, 3, 5]
+ * const setB = [3, 4, 5]
+ *
+ * const unionSet = union(cmp)(setA)(setB) // [1, 3, 4, 5]
+ *
+ * const intersectionSet = intersect(cmp)(setA)(setB) // [3, 5]
+ *
+ * has(cmp)(3)(setA) // true
+ * has(cmp)(2)(setA) // false
+ * ```
+ *
+ * @import { Cmp } from '../function/compare/types.ts'
+ * @import { SortedSet } from './types.ts'
+ */
+
+import { toArray } from "../list/module.f.mjs"
+import { merge, intersect as listIntersect, find } from '../sorted_list/module.f.mjs'
+
+export const union =
+    /**
+     * @template T
+     * @param {Cmp<T>} cmp
+     * @returns {(a: SortedSet<T>) => (b: SortedSet<T>) => SortedSet<T>}
+     */
+    cmp => a => b => toArray(merge(cmp)(a)(b))
+
+export const intersect =
+    /**
+     * @template T
+     * @param {Cmp<T>} cmp
+     * @returns {(a: SortedSet<T>) => (b: SortedSet<T>) => SortedSet<T>}
+     */
+    cmp => a => b => toArray(listIntersect(cmp)(a)(b))
+
+export const has =
+    /**
+     * @template T
+     * @param {Cmp<T>} cmp
+     * @returns {(value: T) => (set: SortedSet<T>) => boolean}
+     */
+    cmp => value => set => find(cmp)(value)(set) === value

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

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

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

@@ -0,0 +1,79 @@
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ */
+
+import { has, intersect, union } from './module.f.mjs'
+import { stringify } from '../../media/json/module.f.mjs'
+import { sort } from '../object/module.f.mjs'
+import { toArray, countdown, length } from '../list/module.f.mjs'
+import { flip } from '../function/module.f.mjs'
+import { cmp } from '../number/module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+/** @type {(a: readonly Unknown[]) => string} */
+const str = a => stringify(sort)(a)
+
+const reverseCmp = flip(cmp)
+
+export const proof = {
+    example: () => {
+        const cmp = (/** @type {number} */ a) => (/** @type {number} */ b) => a < b ? -1 : a > b ? 1 : 0
+
+        const setA = [1, 3, 5]
+        const setB = [3, 4, 5]
+
+        const unionSet = union(cmp)(setA)(setB) // [1, 3, 4, 5]
+        assertEq(str(unionSet), '[1,3,4,5]', 0)
+
+        const intersectionSet = intersect(cmp)(setA)(setB) // [3, 5]
+        assertEq(str(intersectionSet), '[3,5]', 1)
+
+        assert(has(cmp)(3)(setA), 2)
+        assert(!(has(cmp)(2)(setA)), 3)
+    },
+    union: [
+        () => {
+            const result = str(toArray(union(cmp)([2, 3, 4])([1, 3, 5])))
+            assertEq(result, '[1,2,3,4,5]')
+        },
+        () => {
+            const result = str(toArray(union(cmp)([1, 2, 3])([])))
+            assertEq(result, '[1,2,3]')
+        },
+        () => {
+            const n = 10_000
+            const sortedSet = toArray(countdown(n))
+            const result = union(reverseCmp)(sortedSet)(sortedSet)
+            const len = length(result)
+            assert(len == n, result)
+        }
+    ],
+    intersect: [
+        () => {
+            const result = str(toArray(intersect(cmp)([2, 3, 4])([1, 3, 5])))
+            assertEq(result, '[3]')
+        },
+        () => {
+            const result = str(toArray(intersect(cmp)([1, 2, 3])([])))
+            assertEq(result, '[]')
+        }
+    ],
+    has: [
+        () => {
+            const result = has(cmp)(0)([0, 10, 20, 30, 40, 50, 60, 70, 80, 90])
+            assert(result, result)
+        },
+        () => {
+            const result = has(cmp)(3)([0, 10, 20, 30, 40, 50, 60, 70, 80, 90])
+            assert(!(result), result)
+        },
+        () => {
+            const result = has(cmp)(77)([0, 10, 20, 30, 40, 50, 60, 70, 80, 90])
+            assert(!(result), result)
+        },
+        () => {
+            const result = has(cmp)(80)([0, 10, 20, 30, 40, 50, 60, 70, 80, 90])
+            assert(result, result)
+        }
+    ]
+}

package/fjs/types/sorted_set/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type-level API for the sorted-set module.
+ *
+ * @module
+ */
+export type SortedSet<T> = readonly T[];

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

@@ -0,0 +1,40 @@
+/**
+ * Utility functions for working with strings and lists of strings.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { join, concat, repeat, cmp } from './module.f.mjs'
+ *
+ * const words = ['hello', 'world']
+ * join(' ')(words) // 'hello world'
+ * concat(words) // 'helloworld'
+ * repeat('abc')(3) // 'abcabcabc'
+ * cmp('apple')('banana') // -1
+ * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
+ */
+import type { List } from '../list/types.ts';
+import type { Sign } from '../function/compare/types.ts';
+/** @type {(_: string) => (input: List<string>) => string} */
+export declare const join: (_: string) => (input: List<string>) => string;
+/**
+ * String concatenation with identity `''` is a lawful monoid, so `concat` is a
+ * monoid fold. The operation is accumulator-first (`a` on the left), matching
+ * `monoid.fold`'s convention — unlike the element-first `concat` in
+ * `function/operator`, which is written for `list.reduce`.
+ *
+ * @type {(input: List<string>) => string}
+ */
+export declare const concat: (input: List<string>) => string;
+/** @type {(n: string) => (v: number) => string} */
+export declare const repeat: (n: string) => (v: number) => string;
+/** @type {(a: string) => (b: string) => Sign} */
+export declare const cmp: (a: string) => (b: string) => Sign;
+/** @type {(p: number) => (v: string) => readonly[string, string]} */
+export declare const splitAt: (p: number) => (v: string) => readonly [string, string];

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

@@ -0,0 +1,59 @@
+/**
+ * Utility functions for working with strings and lists of strings.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { join, concat, repeat, cmp } from './module.f.mjs'
+ *
+ * const words = ['hello', 'world']
+ * join(' ')(words) // 'hello world'
+ * concat(words) // 'helloworld'
+ * repeat('abc')(3) // 'abcabcabc'
+ * cmp('apple')('banana') // -1
+ * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
+ */
+
+import { reduce as listReduce, repeat as listRepeat } from '../list/module.f.mjs'
+import { compose } from '../function/module.f.mjs'
+import { cmp as uCmp } from '../function/compare/module.f.mjs'
+import { join as joinOp } from '../function/operator/module.f.mjs'
+import { fold } from '../../common/monoid/module.f.mjs'
+
+/**
+ * `join`'s per-separator reduction is seeded at `''` but is *not* a monoid fold:
+ * `joinOp(sep)` has no identity (`joinOp(sep)('')(x)` prepends a separator), so
+ * it stays a hand-seeded `reduce` rather than going through `monoid.fold`.
+ *
+ * @type {(o: Reduce<string>) => (input: List<string>) => string}
+ */
+const reduce = o => listReduce(o)('')
+
+/** @type {(_: string) => (input: List<string>) => string} */
+export const join = compose(joinOp)(reduce)
+
+/**
+ * String concatenation with identity `''` is a lawful monoid, so `concat` is a
+ * monoid fold. The operation is accumulator-first (`a` on the left), matching
+ * `monoid.fold`'s convention — unlike the element-first `concat` in
+ * `function/operator`, which is written for `list.reduce`.
+ *
+ * @type {(input: List<string>) => string}
+ */
+export const concat = fold({ identity: '', operation: a => b => a + b })
+
+/** @type {(n: string) => (v: number) => string} */
+export const repeat = v => compose(listRepeat(v))(concat)
+
+/** @type {(a: string) => (b: string) => Sign} */
+export const cmp = uCmp
+
+/** @type {(p: number) => (v: string) => readonly[string, string]} */
+export const splitAt = p => v =>
+    [v.substring(0, p), v.substring(p)]

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

@@ -0,0 +1,76 @@
+import { join, concat, repeat, cmp, splitAt } from './module.f.mjs'
+import { repeat as repeatList } from '../list/module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    example: () => {
+        const words = ['hello', 'world']
+        assertEq(join(' ')(words), 'hello world', 0)
+        assertEq(concat(words), 'helloworld', 1)
+        assertEq(repeat('abc')(3), 'abcabcabc', 2)
+        assertEq(cmp('apple')('banana'), -1, 3)
+    },
+    join: {
+        0: () => {
+            const result = join('/')([])
+            assertEq(result, '')
+        },
+        1: () => {
+            const result = join('/')([''])
+            assertEq(result, '')
+        },
+        3: () => {
+            const result = join(' ')(['hello', 'world', '!'])
+            assertEq(result, 'hello world !')
+        }
+    },
+    concat: () => {
+        const result = concat(['hello', 'world'])
+        assertEq(result, 'helloworld')
+    },
+    repeatList: {
+        0: () => {
+            const s = join('.')(repeatList('x')(0))
+            assert(s == '', s)
+        },
+        5: () => {
+            const s = join('.')(repeatList('x')(5))
+            assert(s == 'x.x.x.x.x', s)
+        }
+    },
+    repeat: () => {
+        const s = repeat('x')(5)
+        if(s != 'xxxxx') { throw s }
+    },
+    cmp: () => {
+        const result = cmp('3')('4')
+        assertEq(result, -1)
+    },
+    splitAt: {
+        middle: () => {
+            const [a, b] = splitAt(3)('hello')
+            assertEq(a, 'hel')
+            assertEq(b, 'lo')
+        },
+        zero: () => {
+            const [a, b] = splitAt(0)('hello')
+            assertEq(a, '')
+            assertEq(b, 'hello')
+        },
+        full: () => {
+            const [a, b] = splitAt(5)('hello')
+            assertEq(a, 'hello')
+            assertEq(b, '')
+        },
+        beyond: () => {
+            const [a, b] = splitAt(10)('hello')
+            assertEq(a, 'hello')
+            assertEq(b, '')
+        },
+        empty: () => {
+            const [a, b] = splitAt(0)('')
+            assertEq(a, '')
+            assertEq(b, '')
+        },
+    }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * A set of strings implemented as a B-Tree. See `./types.ts` for the
+ * `StringSet` type.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { set, contains, remove, fromValues, values, empty } from './module.f.mjs';
+ *
+ * let mySet = fromValues(['apple', 'banana', 'cherry']);
+ * if (!contains('banana')(mySet)) { throw '1' }
+ * if (contains('date')(mySet)) { throw '2' }
+ *
+ * mySet = set('date')(mySet);
+ * if (!contains('date')(mySet)) { throw '3' }
+ *
+ * mySet = remove('banana')(mySet);
+ * if (contains('banana')(mySet)) { throw '4' }
+ * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { StringSet } from './types.ts'
+ */
+import type { List } from '../list/types.ts';
+import type { StringSet } from './types.ts';
+/** @type {(s: StringSet) => List<string>} */
+export declare const values: (s: StringSet) => List<string>;
+/** @type {null} */
+export declare const empty: null;
+/** @type {(value: string) => (set: StringSet) => boolean} */
+export declare const contains: (value: string) => (set: StringSet) => boolean;
+/** @type {(value: string) => (s: StringSet) => StringSet} */
+export declare const set: (value: string) => (s: StringSet) => StringSet;
+/** @type {(input: List<string>) => StringSet} */
+export declare const fromValues: (input: List<string>) => StringSet;
+/** @type {(value: string) => (s: StringSet) => StringSet} */
+export declare const remove: (value: string) => (s: StringSet) => StringSet;

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

@@ -0,0 +1,54 @@
+/**
+ * A set of strings implemented as a B-Tree. See `./types.ts` for the
+ * `StringSet` type.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { set, contains, remove, fromValues, values, empty } from './module.f.mjs';
+ *
+ * let mySet = fromValues(['apple', 'banana', 'cherry']);
+ * if (!contains('banana')(mySet)) { throw '1' }
+ * if (contains('date')(mySet)) { throw '2' }
+ *
+ * mySet = set('date')(mySet);
+ * if (!contains('date')(mySet)) { throw '3' }
+ *
+ * mySet = remove('banana')(mySet);
+ * if (contains('banana')(mySet)) { throw '4' }
+ * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { StringSet } from './types.ts'
+ */
+
+import { empty as btEmpty, values as btValues } from '../btree/module.f.mjs'
+import { find, isFound } from '../btree/find/module.f.mjs'
+import { remove as btreeRemove } from '../btree/remove/module.f.mjs'
+import { set as btreeSet } from '../btree/set/module.f.mjs'
+import { cmp } from "../string/module.f.mjs"
+import { fold } from '../list/module.f.mjs'
+import { compose } from '../function/module.f.mjs'
+
+/** @type {(s: StringSet) => List<string>} */
+export const values = btValues
+/** @type {null} */
+export const empty = btEmpty
+
+/** @type {(value: string) => (set: StringSet) => boolean} */
+export const contains =
+    value => {
+        const f = find(cmp(value))
+        return s => s !== null && isFound(f(s).first)
+    }
+
+/** @type {(value: string) => (s: StringSet) => StringSet} */
+export const set = value => btreeSet(cmp(value))(() => value)
+
+/** @type {(input: List<string>) => StringSet} */
+export const fromValues = fold(set)(null)
+
+/** @type {(value: string) => (s: StringSet) => StringSet} */
+export const remove = compose(cmp)(btreeRemove)

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

@@ -0,0 +1,46 @@
+import { contains, fromValues, remove, set } from './module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    example: () => {
+        let mySet = fromValues(['apple', 'banana', 'cherry']);
+        assert(contains('banana')(mySet), '1')
+        assert(!(contains('date')(mySet)), '2')
+
+        mySet = set('date')(mySet);
+        assert(contains('date')(mySet), '3')
+
+        mySet = remove('banana')(mySet);
+        assert(!(contains('banana')(mySet)), '4')
+    },
+    contains: () => {
+        const r = set('hello')(null)
+        assert(contains('hello')(r), r)
+        assert(!(contains('hello1')(r)), r)
+    },
+    remove: () => {
+        let r = set('hello')(null)
+        r = set('world')(r)
+        r = set('HELLO')(r)
+        r = set('WORLD!')(r)
+        assert(contains('hello')(r), r)
+        assert(!(contains('hello1')(r)), r)
+        assert(contains('HELLO')(r), r)
+        assert(!(contains('WORLD')(r)), r)
+        assert(contains('world')(r), r)
+        assert(!(contains('world!')(r)), r)
+        assert(contains('WORLD!')(r), r)
+        //
+        r = remove('hello')(r)
+        assert(!(contains('hello')(r)), r)
+        assert(contains('world')(r), r)
+        r = remove('world')(r)
+        assert(!(contains('world')(r)), r)
+        assert(contains('HELLO')(r), r)
+        r = remove('HELLO')(r)
+        assert(!(contains('HELLO')(r)), r)
+        assert(contains('WORLD!')(r), r)
+        r = remove('WORLD!')(r)
+        assertEq(r, null)
+    }
+}

package/fjs/types/string_set/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type-level API for the string-set module.
+ *
+ * @module
+ */
+import type { Tree } from '../btree/types/types.ts';
+export type StringSet = Tree<string>;

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

@@ -0,0 +1,22 @@
+/**
+ * TypeScript source-emitter helpers: the `Equal`/`Assert` compile-time
+ * predicates and a `Printer` that renders tuples, structs, arrays, records,
+ * primitive literals, and unions as TypeScript type expressions.
+ *
+ * @module
+ *
+ * @import { Printer } from './types.ts'
+ */
+import type { Printer } from './types.ts';
+/**
+ * Creates a `Printer`. Pass `true` to emit mutable (non-`readonly`) types.
+ *
+ * @type {(mut?: true) => Printer}
+ */
+export declare const printer: (mut?: true) => Printer;
+/**
+ * @type {(c: bigint|string|undefined|boolean|number|null) => string}
+ */
+export declare const primitive: (c: bigint | string | undefined | boolean | number | null) => string;
+/** @type {(types: readonly string[]) => string} */
+export declare const union: (types: readonly string[]) => string;

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

@@ -0,0 +1,51 @@
+/**
+ * TypeScript source-emitter helpers: the `Equal`/`Assert` compile-time
+ * predicates and a `Printer` that renders tuples, structs, arrays, records,
+ * primitive literals, and unions as TypeScript type expressions.
+ *
+ * @module
+ *
+ * @import { Printer } from './types.ts'
+ */
+
+/** @type {(open: string, close: string) => (i: readonly string[]) => string} */
+const complex = (open, close) => i =>
+    `${open}${i.join(',')}${close}`
+
+const structX = complex('{', '}')
+
+/**
+ * Creates a `Printer`. Pass `true` to emit mutable (non-`readonly`) types.
+ *
+ * @type {(mut?: true) => Printer}
+ */
+export const printer = (mut = undefined) => {
+    const ro = mut ? '' : 'readonly'
+    return {
+        tuple: (mut ? complex('[', ']') : complex('readonly[', ']')),
+        struct: fields =>
+            structX(fields.map(([k, v, opt]) => `${ro}${JSON.stringify(k)}${opt === true ? '?' : ''}:${v}`)),
+        array: type => `${ro}(${type})[]`,
+        // `[k:string]?:` is invalid TypeScript — optional keys on an infinite
+        // key set require mapped-type syntax.
+        record: type => structX([`${ro}[k in string]?:${type}`]),
+    }
+}
+
+/**
+ * @type {(c: bigint|string|undefined|boolean|number|null) => string}
+ */
+export const primitive = c => {
+    if (c === null) { return 'null' }
+    switch (typeof c) {
+        case 'bigint': return `${c}n`
+        case 'string': return JSON.stringify(c)
+        case 'number': return isFinite(c) ? String(c) : 'number'
+        case 'undefined':
+        case 'boolean': return String(c)
+    }
+}
+
+/** @type {(types: readonly string[]) => string} */
+export const union = types =>
+    types.length === 0 ? 'never' : types.join('|')

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

@@ -0,0 +1,39 @@
+export declare const primitiveNull: () => void;
+export declare const primitiveBigint: () => void;
+export declare const primitiveString: () => void;
+export declare const primitiveNumberFinite: () => void;
+export declare const primitiveNumberInfinite: () => void;
+export declare const primitiveUndefined: () => void;
+export declare const primitiveBoolean: () => void;
+export declare const unionEmpty: () => void;
+export declare const unionSingle: () => void;
+export declare const unionMulti: () => void;
+export declare const printerReadonlyTuple: () => void;
+export declare const printerReadonlyStruct: () => void;
+export declare const printerOptionalField: () => void;
+export declare const printerReadonlyArray: () => void;
+export declare const printerReadonlyRecord: () => void;
+export declare const printerMutableTuple: () => void;
+export declare const printerMutableStruct: () => void;
+export declare const printerMutableArray: () => void;
+export declare const printerMutableRecord: () => void;
+export declare const proof: {
+    primitiveNull: typeof primitiveNull;
+    primitiveBigint: typeof primitiveBigint;
+    primitiveString: typeof primitiveString;
+    primitiveNumberFinite: typeof primitiveNumberFinite;
+    primitiveNumberInfinite: typeof primitiveNumberInfinite;
+    primitiveUndefined: typeof primitiveUndefined;
+    primitiveBoolean: typeof primitiveBoolean;
+    unionEmpty: typeof unionEmpty;
+    unionSingle: typeof unionSingle;
+    unionMulti: typeof unionMulti;
+    printerReadonlyTuple: typeof printerReadonlyTuple;
+    printerReadonlyStruct: typeof printerReadonlyStruct;
+    printerReadonlyArray: typeof printerReadonlyArray;
+    printerReadonlyRecord: typeof printerReadonlyRecord;
+    printerMutableTuple: typeof printerMutableTuple;
+    printerMutableStruct: typeof printerMutableStruct;
+    printerMutableArray: typeof printerMutableArray;
+    printerMutableRecord: typeof printerMutableRecord;
+};