functionalscript 0.43.0 → 0.44.0

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

@@ -0,0 +1,186 @@
+/** @import { Unknown } from '../../media/json/types.ts' */
+
+/** @import { RangeMapArray, Properties, RangeMap } from './types.ts' */
+import { get, merge, fromRange, rangeMap } from './module.f.mjs'
+import { stringify } from '../../media/json/module.f.mjs'
+import { sort } from '../object/module.f.mjs'
+import { union } from '../sorted_set/module.f.mjs'
+/** @import { SortedSet } from '../sorted_set/types.ts' */
+import { equal, toArray } from '../list/module.f.mjs'
+import { strictEqual } from '../function/operator/module.f.mjs'
+import { cmp } from '../string/module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+/** @type {(a: readonly Unknown[]) => string} */
+const str = stringify(sort)
+
+/** @type {Properties<SortedSet<string>>} */
+const op = {
+    union: union(cmp),
+    equal: equal(strictEqual),
+    def: []
+}
+
+export const proof = {
+    example: () => {
+        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)
+        assertEq(get(-1), 0, 'error')
+        //
+        assertEq(get(0), 2, 'error')
+        assertEq(get(2), 2, 'error')
+        // 2 | 5 = 7
+        assertEq(get(7), 7, 'error')
+        //
+        assertEq(get(12), 5, 'error')
+        assertEq(get(15), 5, 'error')
+        //
+        assertEq(get(16), 0, 'error')
+    },
+    merge: [
+        () => {
+            /** @type {RangeMap<SortedSet<string>>} */
+            const a = [[['a'], 1], [['b'], 2]]
+            /** @type {RangeMap<SortedSet<string>>} */
+            const b = null
+            const merged = merge(op)(a)(b)
+            const result = str(toArray(merged))
+            assertEq(result, '[[["a"],1],[["b"],2]]')
+        },
+        () => {
+            /** @type {RangeMap<SortedSet<string>>} */
+            const a = null
+            /** @type {RangeMap<SortedSet<string>>} */
+            const b = [[['a'], 1], [['b'], 2]]
+            const merged = merge(op)(a)(b)
+            const result = str(toArray(merged))
+            assertEq(result, '[[["a"],1],[["b"],2]]')
+        },
+        () => {
+            /** @type {RangeMap<SortedSet<string>>} */
+            const a = [[['a'], 1], [['b'], 2]]
+            /** @type {RangeMap<SortedSet<string>>} */
+            const b = [[['a'], 1], [['b'], 2]]
+            const merged = merge(op)(a)(b)
+            const result = str(toArray(merged))
+            assertEq(result, '[[["a"],1],[["b"],2]]')
+        },
+        () => {
+            /** @type {RangeMap<SortedSet<string>>} */
+            const a = [[['a'], 1], [['c'], 3]]
+            /** @type {RangeMap<SortedSet<string>>} */
+            const b = [[['b'], 2], [['d'], 4]]
+            const merged = merge(op)(a)(b)
+            const result = str(toArray(merged))
+            assertEq(result, '[[["a","b"],1],[["b","c"],2],[["c","d"],3],[["d"],4]]')
+        },
+        () => {
+            /** @type {RangeMap<SortedSet<string>>} */
+            const a = [[['a'], 1], [['d'], 4]]
+            /** @type {RangeMap<SortedSet<string>>} */
+            const b = [[['b'], 2], [['c'], 3]]
+            const merged = merge(op)(a)(b)
+            const result = str(toArray(merged))
+            assertEq(result, '[[["a","b"],1],[["b","d"],2],[["c","d"],3],[["d"],4]]')
+        },
+        () => {
+            /** @type {RangeMap<SortedSet<string>>} */
+            const a = [[['a'], 1], [['b'], 2]]
+            /** @type {RangeMap<SortedSet<string>>} */
+            const b = [[['b'], 1], [['a'], 2]]
+            const merged = merge(op)(a)(b)
+            const result = str(toArray(merged))
+            assertEq(result, '[[["a","b"],2]]')
+        },
+        () => {
+            /** @type {RangeMap<SortedSet<string>>} */
+            const a = [[['a'], 1], [['b'], 2], [['a'], 3]]
+            /** @type {RangeMap<SortedSet<string>>} */
+            const b = [[['a'], 5]]
+            const merged = merge(op)(a)(b)
+            const result = str(toArray(merged))
+            assertEq(result, '[[["a"],1],[["a","b"],2],[["a"],5]]')
+        }
+    ],
+    get: () => {
+        /** @type {SortedSet<string>} */
+        const sortedSetEmpty = []
+        const at = get(sortedSetEmpty)
+        return [
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = [[['a'], 10], [['b'], 20], [['c'], 30]]
+                const result = str(at(rm)(5))
+                assertEq(result, '["a"]')
+            },
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = [[['a'], 10], [['b'], 20], [['c'], 30]]
+                const result = str(at(rm)(10))
+                assertEq(result, '["a"]')
+            },
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = [[['a'], 10], [['b'], 20], [['c'], 30]]
+                const result = str(at(rm)(15))
+                assertEq(result, '["b"]')
+            },
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = [[['a'], 10], [['b'], 20], [['c'], 30]]
+                const result = str(at(rm)(20))
+                assertEq(result, '["b"]')
+            },
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = [[['a'], 10], [['b'], 20], [['c'], 30]]
+                const result = str(at(rm)(25))
+                assertEq(result, '["c"]')
+            },
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = [[['a'], 10], [['b'], 20], [['c'], 30]]
+                const result = str(at(rm)(30))
+                assertEq(result, '["c"]')
+            },
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = [[['a'], 10], [['b'], 20], [['c'], 30]]
+                const result = str(at(rm)(35))
+                assertEq(result, '[]')
+            },
+            () => {
+                /** @type {RangeMapArray<SortedSet<string>>} */
+                const rm = []
+                const result = str(at(rm)(10))
+                assertEq(result, '[]')
+            }
+        ]
+    },
+    fromRange: () => {
+        const def = -1
+        const rm = fromRange(def)(42)([1, 7])
+        const g = get(def)(rm)
+        return [
+            () => assertEq(g(0), -1),
+            () =>assertEq(g(1), 42),
+            () => assertEq(g(3), 42),
+            () =>assertEq(g(7), 42),
+            () => assertEq(g(9), -1),
+        ]
+    },
+}

package/fjs/types/range_map/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Types for managing and merging range maps.
+ *
+ * @module
+ */
+import type { Equal, Reduce } from '../function/operator/types.ts';
+import type { Range } from '../range/types.ts';
+import type { SortedList } from '../sorted_list/types.ts';
+export type Entry<T> = [T, number];
+/**
+ * A sorted list of entries, where each entry is a tuple `[T, number]` that maps
+ * a value of type `T` to an upper boundary of a numeric range.
+ */
+export type RangeMap<T> = SortedList<Entry<T>>;
+export type RangeMapArray<T> = readonly Entry<T>[];
+/**
+ * Defines the properties and operations required for managing range maps.
+ *
+ * @property union
+ *
+ * A function to merge two values of type `T`. This defines how overlapping ranges are combined.
+ *
+ * @property equal
+ *
+ * A function to check equality between two values of type `T`.
+ *
+ * @property def
+ *
+ * The default value used when no range matches or for initializing ranges.
+ */
+export type Properties<T> = {
+    readonly union: Reduce<T>;
+    readonly equal: Equal<T>;
+    readonly def: T;
+};
+export type RangeMerge<T> = Reduce<RangeMap<T>>;
+/**
+ * Represents a set of operations for managing range maps.
+ *
+ * @property merge
+ *
+ * Merges two range maps into a single range map.
+ *
+ * @property get
+ *
+ * Retrieves the value associated with a given numeric range.
+ *
+ * @property fromRange
+ *
+ * Constructs a range map for a single numeric range and value.
+ */
+export type RangeMapOp<T> = {
+    readonly merge: RangeMerge<T>;
+    readonly get: (rm: RangeMapArray<T>) => (value: number) => T;
+    readonly fromRange: (value: T) => (r: Range) => RangeMapArray<T>;
+};

package/fjs/types/range_map/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for managing and merging range maps.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Constructs a range set containing a single numeric range.
+ */
+export declare const fromRange: (r: import("../range/types.ts").Range) => import("../range_map/types.ts").RangeMapArray<boolean>;
+export declare const merge: import("../range_map/types.ts").RangeMerge<boolean>, get: (rm: import("../range_map/types.ts").RangeMapArray<boolean>) => (value: number) => boolean;

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

@@ -0,0 +1,19 @@
+/**
+ * A set of numeric ranges, represented as a `range_map` of `boolean`.
+ *
+ * @module
+ */
+import { rangeMap } from '../range_map/module.f.mjs'
+
+const map = rangeMap({
+    union: a => b => a || b,
+    equal: a => b => a === b,
+    def: false,
+})
+
+/**
+ * Constructs a range set containing a single numeric range.
+ */
+export const fromRange = map.fromRange(true)
+
+export const { merge, get } = map

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

@@ -0,0 +1,26 @@
+import { assert } from '../../asserts/module.f.mjs'
+import { toArray } from '../list/module.f.mjs'
+import { fromRange, merge, get } from './module.f.mjs'
+/** @import { Range } from '../range/types.ts' */
+
+/** @type {(a: string) => number} */
+const c = a => a.charCodeAt(0)
+
+/** @type {(_: string) => Range} */
+const range = ([a, b]) => [c(a), c(b)]
+
+export const proof = () => {
+    const digit = fromRange(range('09'))
+    const initial = toArray(merge
+        (fromRange(range('AZ')))
+        (fromRange(range('az'))))
+    const isInitial = get(initial)
+    assert(!isInitial(0))
+    assert(isInitial(c('a')))
+    assert(!isInitial(c('1')))
+    assert(isInitial(c('Z')))
+    const isNext = get(toArray(merge(initial)(digit)))
+    assert(isNext(c('0')))
+    assert(isNext(c('A')))
+    assert(!isNext(c('@')))
+}

package/fjs/types/result/module.d.mts

@@ -0,0 +1,5 @@
+import type { Result } from './types.ts';
+/** @type {<T>(f: () => T) => Result<T, unknown>} */
+export declare const tryCatch: <T>(f: () => T) => Result<T, unknown>;
+/** @type {<T>(f: () => Promise<T>) => Promise<Result<T, unknown>>} */
+export declare const asyncTryCatch: <T>(f: () => Promise<T>) => Promise<Result<T, unknown>>;

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

@@ -0,0 +1,59 @@
+/**
+ * A module for representing and handling operations that can succeed or fail.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```ts
+ * import { error, ok, unwrap, type Result } from './module.f.ts'
+ *
+ * const success: Result<number, string> = ok(42)
+ * const failure: Result<number, string> = error('Something went wrong')
+ *
+ * if (unwrap(success) !== 42) { throw 'error' }
+ * const [kind, v] = failure
+ * if (kind !== 'error') { throw 'error' }
+ * // `v` is inferred as `string` here
+ * if (v !== 'Something went wrong') { throw 'error' }
+ * ```
+ */
+import type { Ok, Error, Result } from './types.ts';
+/** @import { Ok, Error, Result } from './types.ts' */
+/**
+ * Creates a successful result.
+ *
+ * @template T
+ * @param {T} value - The value to wrap.
+ * @returns {Ok<T>} A successful result containing the value.
+ */
+export declare const ok: <T>(value: T) => Ok<T>;
+/**
+ * Creates a failed result.
+ *
+ * @template E
+ * @param {E} e - The error to wrap.
+ * @returns {Error<E>} A failed result containing the error.
+ */
+export declare const error: <E>(e: E) => Error<E>;
+/**
+ * Unwraps a result, returning the value if successful or throwing the error if failed.
+ *
+ * @template T
+ * @template E
+ * @param {Result<T, E>} param0 - The result to unwrap.
+ * @returns {T} The value if the result is successful. Otherwise, throws the error.
+ */
+export declare const unwrap: <T, E>([kind, v]: Result<T, E>) => T;
+/**
+ * Swaps the `ok` and `error` cases of a result.
+ *
+ * @type {<T, E>([k, v]: Result<T, E>) => Result<E, T>}
+ */
+export declare const invert: <T, E>([k, v]: Result<T, E>) => Result<E, T>;
+/**
+ * Maps the `ok` case of a result, passing an `error` through unchanged.
+ *
+ * @type {<T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) => Result<R, E>}
+ */
+export declare const mapOk: <T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) => Result<R, E>;

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

@@ -0,0 +1,67 @@
+/**
+ * A module for representing and handling operations that can succeed or fail.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```ts
+ * import { error, ok, unwrap, type Result } from './module.f.ts'
+ *
+ * const success: Result<number, string> = ok(42)
+ * const failure: Result<number, string> = error('Something went wrong')
+ *
+ * if (unwrap(success) !== 42) { throw 'error' }
+ * const [kind, v] = failure
+ * if (kind !== 'error') { throw 'error' }
+ * // `v` is inferred as `string` here
+ * if (v !== 'Something went wrong') { throw 'error' }
+ * ```
+ */
+
+/** @import { Ok, Error, Result } from './types.ts' */
+
+/**
+ * Creates a successful result.
+ *
+ * @template T
+ * @param {T} value - The value to wrap.
+ * @returns {Ok<T>} A successful result containing the value.
+ */
+export const ok = value  => ['ok', value]
+
+/**
+ * Creates a failed result.
+ *
+ * @template E
+ * @param {E} e - The error to wrap.
+ * @returns {Error<E>} A failed result containing the error.
+ */
+export const error = e => ['error', e]
+
+/**
+ * Unwraps a result, returning the value if successful or throwing the error if failed.
+ *
+ * @template T
+ * @template E
+ * @param {Result<T, E>} param0 - The result to unwrap.
+ * @returns {T} The value if the result is successful. Otherwise, throws the error.
+ */
+export const unwrap = ([kind, v]) => {
+    if (kind === 'error') { throw v }
+    return v
+}
+
+/**
+ * Swaps the `ok` and `error` cases of a result.
+ *
+ * @type {<T, E>([k, v]: Result<T, E>) => Result<E, T>}
+ */
+export const invert = ([k, v]) => k === 'ok' ? error(v) : ok(v)
+
+/**
+ * Maps the `ok` case of a result, passing an `error` through unchanged.
+ *
+ * @type {<T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) => Result<R, E>}
+ */
+export const mapOk = f => r => r[0] === 'ok' ? ok(f(r[1])) : r

package/fjs/types/result/module.mjs

@@ -0,0 +1,22 @@
+/** @import { Result } from './types.ts' */
+import { ok, error } from './module.f.mjs'
+
+/** @type {<T>(f: () => T) => Result<T, unknown>} */
+export const tryCatch = f => {
+    // Side effect: `try catch` is not allowed in FunctionalScript.
+    try {
+        return ok(f())
+    } catch (e) {
+        return error(e)
+    }
+}
+
+/** @type {<T>(f: () => Promise<T>) => Promise<Result<T, unknown>>} */
+export const asyncTryCatch = async f => {
+    // Side effect: `try catch` is not allowed in FunctionalScript.
+    try {
+        return ok(await f())
+    } catch (e) {
+        return error(e)
+    }
+}

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

@@ -0,0 +1,41 @@
+import { error, ok, unwrap, invert, mapOk } from './module.f.mjs'
+/** @import { Result } from './types.ts' */
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+const example = () => {
+    /** @type {Result<number, string>} */
+    const success = ok(42)
+    /** @type {Result<number, string>} */
+    const failure = error('Something went wrong')
+
+    assertEq(unwrap(success), 42, 'error')
+    const [kind, v] = failure
+    assertEq(kind, 'error')
+    // `v` is inferred as `string` here
+    assertEq(v, 'Something went wrong', 'error')
+}
+
+const invertTest = () => {
+    const [k0, v0] = invert(ok(42))
+    assert(!(k0 !== 'error' || v0 !== 42), [k0, v0])
+    const [k1, v1] = invert(error('oops'))
+    assert(!(k1 !== 'ok' || v1 !== 'oops'), [k1, v1])
+}
+
+const mapOkTest = () => {
+    /** @type {(n: number) => number} */
+    const inc = n => n + 1
+    const [k0, v0] = mapOk(inc)(ok(41))
+    assert(!(k0 !== 'ok' || v0 !== 42), [k0, v0])
+    const [k1, v1] = mapOk(inc)(error('oops'))
+    assert(!(k1 !== 'error' || v1 !== 'oops'), [k1, v1])
+}
+
+export const proof = {
+    example,
+    invertTest,
+    mapOkTest,
+    throw: {
+        unwrapError: () => unwrap(error('oops')),
+    },
+}

package/fjs/types/result/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Types for representing operations that can succeed or fail.
+ *
+ * @module
+ */
+/**
+ * Represents a successful result.
+ */
+export type Ok<T> = readonly ['ok', T];
+/**
+ * Represents a failed result.
+ */
+export type Error<E> = readonly ['error', E];
+/**
+ * Represents a result that can be either successful or failed.
+ */
+export type Result<T, E> = Ok<T> | Error<E>;

package/fjs/types/result/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for representing operations that can succeed or fail.
+ *
+ * @module
+ */
+export {};

package/fjs/types/rtti/common/module.f.d.mts

@@ -0,0 +1,86 @@
+import type { Primitive, Unknown } from '../ts/types.ts';
+import type { Info0, Primitive0, Type } from '../types.ts';
+import type { Error, Result as CommonResult } from '../../result/types.ts';
+import type { StringMap } from '../../object/types.ts';
+import type { Validate, Visitor, IsContainer, ResultE, ValidateE, ValidationError } from './types.ts';
+/** @import { StringMap } from '../../object/types.ts' */
+/** @import { Validate, Visitor, IsContainer, Container, ResultE, ValidateE, ValidationError } from './types.ts' */
+/** Builds an error result with empty path and the given message. */
+/** @type {(message: string) => Error<ValidationError>} */
+export declare const verror: (message: string) => Error<ValidationError>;
+/** Prepends `key` to the error's path, used to build the path bottom-up. */
+/** @type {(key: string, error: Error<ValidationError>) => Error<ValidationError>} */
+export declare const prependPath: (key: string, error: Error<ValidationError>) => Error<ValidationError>;
+/** Validates a `Tag0` primitive schema using `typeof`. */
+export declare const primitive0Validate: <K extends Primitive0, T extends Info0<K>>(
+/**
+ * @template {Primitive0} K
+ * @template {Info0<K>} T
+ * @param {K} tag
+ * @returns {Validate<T>}
+ */
+tag: K) => Validate<T>;
+/**
+ * Validates a primitive `Const` schema using `Object.is` (SameValue).
+ *
+ * `Object.is` is used instead of `===` so that:
+ * - `NaN` const schemas match `NaN` values (`===` would always fail because `NaN !== NaN`).
+ * - `+0` and `-0` are treated as distinct const values.
+ */
+export declare const constPrimitiveValidate: <T extends Primitive>(
+/**
+ * @template {Primitive} T
+ * @param {T} rtti
+ * @returns {Validate<T>}
+ */
+rtti: T) => Validate<T>;
+/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+/** @type {IsContainer<ReadonlyArray<Unknown>>} */
+export declare const isArray: IsContainer<ReadonlyArray<Unknown>>;
+/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+/** @type {IsContainer<StringMap<Unknown>>} */
+export declare const isObject: IsContainer<StringMap<Unknown>>;
+/**
+ * Runs `item` over each `[key, value]` entry, bailing out with the first
+ * error, path-prefixed with that entry's key. On success, folds each item's
+ * result into `acc` (starting from `init`) with `accumulate` and returns the
+ * final accumulator.
+ *
+ * Shared by `validate` and `parse`'s container builders (array/record/tuple/
+ * struct), which differ only in what `item` does with the value and what
+ * they accumulate: `validate` has nothing to collect — its entire schema is
+ * "did every entry succeed?" — so it passes `undefined`/`(acc) => acc` and
+ * pays no allocation per entry; `parse` needs the rebuilt `[key, value]`
+ * pairs, so it folds them into a `List` (see its call site) and converts to
+ * an array once at the end.
+ */
+export declare const eachEntry: <V, R, A>(entries: ReadonlyArray<readonly [string, V]>, item: (k: string, v: V) => CommonResult<R, ValidationError>, init: A, accumulate: (acc: A, k: string, value: R) => A) => CommonResult<A, ValidationError>;
+/**
+ * First variant in `variants` that `recurse` accepts, else `verror('no match')`.
+ *
+ * Shared `or` handler for `validate` and `parse`: both try each variant
+ * against the value and return the first `'ok'` verbatim, differing only in
+ * which recursive function (`validate` or `parse`) walks each variant. `recurse`
+ * is typed over the erased `ValidateE` alias — annotating it as `(t: Type) =>
+ * Validate<Type>` would itself instantiate `Validate<Type>` and hit TS2589 —
+ * so each caller passes its recursive function through one boundary cast.
+ *
+ * @type {(recurse: (t: Type) => ValidateE) => (variants: readonly Type[]) => (value: Unknown) => ResultE}
+ */
+export declare const orVisit: (recurse: (t: Type) => ValidateE) => (variants: readonly Type[]) => (value: Unknown) => ResultE;
+/**
+ * Visits a schema `Type` by dispatching to the matching handler in `v`.
+ *
+ * - `Thunk` schemas are evaluated once to read the `Info` descriptor, then
+ *   routed by tag (`'const'`, `'array'`, `'record'`, `'unknown'`, `'or'`,
+ *   or a `Tag0` primitive).
+ * - `Const` schemas (primitives, tuples, structs) are routed directly to
+ *   `tuple`, `struct`, or `constPrimitive`.
+ */
+export declare const visit: <R>(
+/**
+ * @template R
+ * @param {Visitor<R>} v
+ * @returns {(rtti: Type) => R}
+ */
+v: Visitor<R>) => (rtti: Type) => R;