functionalscript 0.3.10 → 0.3.12

package/types/range_map/module.f.d.ts

@@ -1,14 +1,91 @@
+/**
+ * Utility functions and types for managing and merging range maps.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * const rmOps = rangeMap({
+ *     union: a => b => a | b,
+ *     equal: a => b => a === b,
+ *     def: 0,
+ * })
+ *
+ * // Create range maps
+ * const range1 = rmOps.fromRange([0, 10])(2)
+ * const range2 = rmOps.fromRange([5, 15])(5)
+ *
+ * // Merge range maps
+ * const merged = toArray(rmOps.merge(range1)(range2))
+ *
+ * // Retrieve values from the merged range map
+ * //
+ * if (rmOps.get(-1)(merged) !== 0) { throw 'error' }
+ * //
+ * if (rmOps.get(0)(merged) !== 2) { throw 'error' }
+ * if (rmOps.get(2)(merged) !== 2) { throw 'error' }
+ * // overlapped: 2 | 5 = 7
+ * if (rmOps.get(7)(merged) !== 7) { throw 'error' }
+ * //
+ * if (rmOps.get(12)(merged) !== 5) { throw 'error' }
+ * if (rmOps.get(15)(merged) !== 5) { throw 'error' }
+ * //
+ * if (rmOps.get(16)(merged) !== 0) { throw 'error' }
+ * ```
+ */
 import { type SortedList } from '../sorted_list/module.f.ts';
 import type { Reduce, Equal } from '../function/operator/module.f.ts';
 import type { Range } from '../range/module.f.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>[];
-export type Operators<T> = {
+/**
+ * Defines the properties and operations required for managing range maps.
+ */
+export type Properties<T> = {
+    /**
+     * A function to merge two values of type `T`. This defines how overlapping ranges are combined.
+     */
     readonly union: Reduce<T>;
+    /**
+     * A function to check equality between two values of type `T`.
+     */
     readonly equal: Equal<T>;
+    /**
+     * The default value used when no range matches or for initializing ranges.
+     */
+    readonly def: T;
 };
 export type RangeMerge<T> = Reduce<RangeMap<T>>;
-export declare const merge: <T>(op: Operators<T>) => RangeMerge<T>;
+export declare const merge: <T>(op: Properties<T>) => RangeMerge<T>;
 export declare const get: <T>(def: T) => (value: number) => (rm: RangeMapArray<T>) => T;
 export declare const fromRange: <T>(def: T) => (r: Range) => (value: T) => RangeMapArray<T>;
+/**
+ * Represents a set of operations for managing range maps.
+ */
+export type RangeMapOp<T> = {
+    /**
+     * Merges two range maps into a single range map.
+     */
+    readonly merge: RangeMerge<T>;
+    /**
+     * Retrieves the value associated with a given numeric range.
+     */
+    readonly get: (value: number) => (rm: RangeMapArray<T>) => T;
+    /**
+     * Constructs a range map for a single numeric range and value.
+     */
+    readonly fromRange: (r: Range) => (value: T) => RangeMapArray<T>;
+};
+/**
+ * Creates a set of operations for managing range maps using the specified properties.
+ *
+ * @param op - The properties defining union and equality operations and the default value.
+ * @returns An object containing operations for merging, retrieving, and constructing range maps.
+ */
+export declare const rangeMap: <T>(op: Properties<T>) => RangeMapOp<T>;

package/types/range_map/module.f.js

@@ -1,7 +1,43 @@
+/**
+ * Utility functions and types for managing and merging range maps.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * const rmOps = rangeMap({
+ *     union: a => b => a | b,
+ *     equal: a => b => a === b,
+ *     def: 0,
+ * })
+ *
+ * // Create range maps
+ * const range1 = rmOps.fromRange([0, 10])(2)
+ * const range2 = rmOps.fromRange([5, 15])(5)
+ *
+ * // Merge range maps
+ * const merged = toArray(rmOps.merge(range1)(range2))
+ *
+ * // Retrieve values from the merged range map
+ * //
+ * if (rmOps.get(-1)(merged) !== 0) { throw 'error' }
+ * //
+ * if (rmOps.get(0)(merged) !== 2) { throw 'error' }
+ * if (rmOps.get(2)(merged) !== 2) { throw 'error' }
+ * // overlapped: 2 | 5 = 7
+ * if (rmOps.get(7)(merged) !== 7) { throw 'error' }
+ * //
+ * if (rmOps.get(12)(merged) !== 5) { throw 'error' }
+ * if (rmOps.get(15)(merged) !== 5) { throw 'error' }
+ * //
+ * if (rmOps.get(16)(merged) !== 0) { throw 'error' }
+ * ```
+ */
 import { genericMerge } from "../sorted_list/module.f.js";
 import { next } from "../list/module.f.js";
 import { cmp } from "../number/module.f.js";
-const reduceOp = union => equal => state => ([aItem, aMax]) => ([bItem, bMax]) => {
+const reduceOp = ({ union, equal }) => state => ([aItem, aMax]) => ([bItem, bMax]) => {
     const sign = cmp(aMax)(bMax);
     const min = sign === 1 ? bMax : aMax;
     const u = union(aItem)(bItem);
@@ -21,7 +57,7 @@ const tailReduce = equal => state => tail => {
     }
     return { first: state, tail: tailResult };
 };
-export const merge = ({ union, equal }) => genericMerge({ reduceOp: reduceOp(union)(equal), tailReduce: tailReduce(equal) })(null);
+export const merge = op => genericMerge({ reduceOp: reduceOp(op), tailReduce: tailReduce(op.equal) })(null);
 export const get = def => value => rm => {
     const len = rm.length;
     let b = 0;
@@ -43,3 +79,14 @@ export const get = def => value => rm => {
     }
 };
 export const fromRange = def => ([a, b]) => v => [[def, a - 1], [v, b]];
+/**
+ * Creates a set of operations for managing range maps using the specified properties.
+ *
+ * @param op - The properties defining union and equality operations and the default value.
+ * @returns An object containing operations for merging, retrieving, and constructing range maps.
+ */
+export const rangeMap = (op) => ({
+    merge: merge(op),
+    get: get(op.def),
+    fromRange: fromRange(op.def),
+});

package/types/range_map/test.f.d.ts

@@ -1,4 +1,5 @@
 declare const _default: {
+    example: () => void;
     merge: (() => void)[];
     get: () => (() => void)[];
     fromRange: () => (() => void)[];

package/types/range_map/test.f.js

@@ -1,19 +1,62 @@
-import * as _ from "./module.f.js";
+import { get, merge, fromRange, rangeMap } from "./module.f.js";
 import { unsafeCmp } from "../function/compare/module.f.js";
 import * as json from "../../json/module.f.js";
 import { sort } from "../object/module.f.js";
-import * as sortedSet from "../sorted_set/module.f.js";
-import * as list from "../list/module.f.js";
+import { union } from "../sorted_set/module.f.js";
+import { equal, toArray } from "../list/module.f.js";
 import * as operator from "../function/operator/module.f.js";
 const stringify = json.stringify(sort);
-const op = { union: sortedSet.union(unsafeCmp), equal: list.equal(operator.strictEqual) };
+const op = {
+    union: union(unsafeCmp),
+    equal: equal(operator.strictEqual),
+    def: []
+};
 export default {
+    example: () => {
+        const rmOps = rangeMap({
+            union: a => b => a | b,
+            equal: a => b => a === b,
+            def: 0,
+        });
+        // Create range maps
+        const range1 = rmOps.fromRange([0, 10])(2);
+        const range2 = rmOps.fromRange([5, 15])(5);
+        // Merge range maps
+        const merged = toArray(rmOps.merge(range1)(range2));
+        // Retrieve values from the merged range map
+        //
+        if (rmOps.get(-1)(merged) !== 0) {
+            throw 'error';
+        }
+        //
+        if (rmOps.get(0)(merged) !== 2) {
+            throw 'error';
+        }
+        if (rmOps.get(2)(merged) !== 2) {
+            throw 'error';
+        }
+        // 2 | 5 = 7
+        if (rmOps.get(7)(merged) !== 7) {
+            throw 'error';
+        }
+        //
+        if (rmOps.get(12)(merged) !== 5) {
+            throw 'error';
+        }
+        if (rmOps.get(15)(merged) !== 5) {
+            throw 'error';
+        }
+        //
+        if (rmOps.get(16)(merged) !== 0) {
+            throw 'error';
+        }
+    },
     merge: [
         () => {
             const a = [[['a'], 1], [['b'], 2]];
             const b = null;
-            const merged = _.merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const merged = merge(op)(a)(b);
+            const result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["b"],2]]') {
                 throw result;
             }
@@ -21,8 +64,8 @@ export default {
         () => {
             const a = null;
             const b = [[['a'], 1], [['b'], 2]];
-            const merged = _.merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const merged = merge(op)(a)(b);
+            const result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["b"],2]]') {
                 throw result;
             }
@@ -30,8 +73,8 @@ export default {
         () => {
             const a = [[['a'], 1], [['b'], 2]];
             const b = [[['a'], 1], [['b'], 2]];
-            const merged = _.merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const merged = merge(op)(a)(b);
+            const result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["b"],2]]') {
                 throw result;
             }
@@ -39,8 +82,8 @@ export default {
         () => {
             const a = [[['a'], 1], [['c'], 3]];
             const b = [[['b'], 2], [['d'], 4]];
-            const merged = _.merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const merged = merge(op)(a)(b);
+            const result = stringify(toArray(merged));
             if (result !== '[[["a","b"],1],[["b","c"],2],[["c","d"],3],[["d"],4]]') {
                 throw result;
             }
@@ -48,8 +91,8 @@ export default {
         () => {
             const a = [[['a'], 1], [['d'], 4]];
             const b = [[['b'], 2], [['c'], 3]];
-            const merged = _.merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const merged = merge(op)(a)(b);
+            const result = stringify(toArray(merged));
             if (result !== '[[["a","b"],1],[["b","d"],2],[["c","d"],3],[["d"],4]]') {
                 throw result;
             }
@@ -57,8 +100,8 @@ export default {
         () => {
             const a = [[['a'], 1], [['b'], 2]];
             const b = [[['b'], 1], [['a'], 2]];
-            const merged = _.merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const merged = merge(op)(a)(b);
+            const result = stringify(toArray(merged));
             if (result !== '[[["a","b"],2]]') {
                 throw result;
             }
@@ -66,8 +109,8 @@ export default {
         () => {
             const a = [[['a'], 1], [['b'], 2], [['a'], 3]];
             const b = [[['a'], 5]];
-            const merged = _.merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const merged = merge(op)(a)(b);
+            const result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["a","b"],2],[["a"],5]]') {
                 throw result;
             }
@@ -75,60 +118,60 @@ export default {
     ],
     get: () => {
         const sortedSetEmpty = [];
-        const get = _.get(sortedSetEmpty);
+        const at = get(sortedSetEmpty);
         return [
             () => {
                 const rm = [[['a'], 10], [['b'], 20], [['c'], 30]];
-                const result = stringify(get(5)(rm));
+                const result = stringify(at(5)(rm));
                 if (result !== '["a"]') {
                     throw result;
                 }
             },
             () => {
                 const rm = [[['a'], 10], [['b'], 20], [['c'], 30]];
-                const result = stringify(get(10)(rm));
+                const result = stringify(at(10)(rm));
                 if (result !== '["a"]') {
                     throw result;
                 }
             },
             () => {
                 const rm = [[['a'], 10], [['b'], 20], [['c'], 30]];
-                const result = stringify(get(15)(rm));
+                const result = stringify(at(15)(rm));
                 if (result !== '["b"]') {
                     throw result;
                 }
             },
             () => {
                 const rm = [[['a'], 10], [['b'], 20], [['c'], 30]];
-                const result = stringify(get(20)(rm));
+                const result = stringify(at(20)(rm));
                 if (result !== '["b"]') {
                     throw result;
                 }
             },
             () => {
                 const rm = [[['a'], 10], [['b'], 20], [['c'], 30]];
-                const result = stringify(get(25)(rm));
+                const result = stringify(at(25)(rm));
                 if (result !== '["c"]') {
                     throw result;
                 }
             },
             () => {
                 const rm = [[['a'], 10], [['b'], 20], [['c'], 30]];
-                const result = stringify(get(30)(rm));
+                const result = stringify(at(30)(rm));
                 if (result !== '["c"]') {
                     throw result;
                 }
             },
             () => {
                 const rm = [[['a'], 10], [['b'], 20], [['c'], 30]];
-                const result = stringify(get(35)(rm));
+                const result = stringify(at(35)(rm));
                 if (result !== '[]') {
                     throw result;
                 }
             },
             () => {
                 const rm = [];
-                const result = stringify(get(10)(rm));
+                const result = stringify(at(10)(rm));
                 if (result !== '[]') {
                     throw result;
                 }
@@ -137,34 +180,34 @@ export default {
     },
     fromRange: () => {
         const def = -1;
-        const rm = _.fromRange(def)([1, 7])(42);
+        const rm = fromRange(def)([1, 7])(42);
         return [
             () => {
-                const result = _.get(def)(0)(rm);
+                const result = get(def)(0)(rm);
                 if (result !== -1) {
                     throw result;
                 }
             },
             () => {
-                const result = _.get(def)(1)(rm);
+                const result = get(def)(1)(rm);
                 if (result !== 42) {
                     throw result;
                 }
             },
             () => {
-                const result = _.get(def)(3)(rm);
+                const result = get(def)(3)(rm);
                 if (result !== 42) {
                     throw result;
                 }
             },
             () => {
-                const result = _.get(def)(7)(rm);
+                const result = get(def)(7)(rm);
                 if (result !== 42) {
                     throw result;
                 }
             },
             () => {
-                const result = _.get(def)(9)(rm);
+                const result = get(def)(9)(rm);
                 if (result !== -1) {
                     throw result;
                 }

package/types/result/module.f.d.ts

@@ -1,6 +1,53 @@
+/**
+ * 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' }
+ * ```
+ */
+/**
+ * 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>;
+/**
+ * Creates a successful result.
+ *
+ * @param value - The value to wrap.
+ * @returns A successful result containing the value.
+ */
 export declare const ok: <T>(value: T) => Ok<T>;
+/**
+ * Creates a failed result.
+ *
+ * @param e - The error to wrap.
+ * @returns A failed result containing the error.
+ */
 export declare const error: <E>(e: E) => Error<E>;
-export declare const unwrap: <T, E>(r: Result<T, E>) => T;
+/**
+ * Unwraps a result, returning the value if successful or throwing the error if failed.
+ *
+ * @param param0 - The result to unwrap.
+ * @returns The value if the result is successful. Otherwise, throws the error.
+ */
+export declare const unwrap: <T, E>([kind, v]: Result<T, E>) => T;

package/types/result/module.f.js

@@ -1,5 +1,43 @@
-export const ok = value => ['ok', value];
-export const error = e => ['error', e];
+/**
+ * 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' }
+ * ```
+ */
+/**
+ * Creates a successful result.
+ *
+ * @param value - The value to wrap.
+ * @returns A successful result containing the value.
+ */
+export const ok = (value) => ['ok', value];
+/**
+ * Creates a failed result.
+ *
+ * @param e - The error to wrap.
+ * @returns 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.
+ *
+ * @param param0 - The result to unwrap.
+ * @returns The value if the result is successful. Otherwise, throws the error.
+ */
 export const unwrap = ([kind, v]) => {
     if (kind === 'error') {
         throw v;

package/types/result/test.f.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    example: () => void;
+};
+export default _default;

package/types/result/test.f.js

@@ -0,0 +1,18 @@
+import { error, ok, unwrap } from "./module.f.js";
+export default {
+    example: () => {
+        const success = ok(42);
+        const failure = 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';
+        }
+    }
+};

package/types/sorted_list/module.f.js

@@ -1,7 +1,7 @@
 import { next } from "../list/module.f.js";
 import { identity } from "../function/module.f.js";
 export const genericMerge = ({ reduceOp, tailReduce }) => {
-    const f = state => a => b => () => {
+    const f = (state) => (a) => (b) => () => {
         const aResult = next(a);
         if (aResult === null) {
             return tailReduce(state)(b);
@@ -22,20 +22,21 @@ export const merge = (cmp) => {
     const tailReduce = mergeTail;
     return genericMerge({ reduceOp: cmpReduce(cmp), tailReduce })(null);
 };
-const cmpReduce = cmp => () => a => b => {
+const cmpReduce = (cmp) => () => a => b => {
     const sign = cmp(a)(b);
     return [sign === 1 ? b : a, sign, null];
 };
 const mergeTail = () => identity;
-export const find = cmp => value => array => {
+export const find = (cmp) => (value) => (array) => {
+    const cmpValue = cmp(value);
     let b = 0;
     let e = array.length - 1;
     while (true) {
-        if (e - b < 0)
+        const d = e - b;
+        if (d < 0)
             return null;
-        const mid = b + (e - b >> 1);
-        const sign = cmp(value)(array[mid]);
-        switch (sign) {
+        const mid = b + (d >> 1);
+        switch (cmpValue(array[mid])) {
             case -1: {
                 e = mid - 1;
                 break;

package/types/sorted_set/module.f.d.ts

@@ -1,3 +1,31 @@
+/**
+ * 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.ts'
+ *
+ * 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 type { Sign } from '../function/compare/module.f.ts';
 export type SortedSet<T> = readonly T[];
 type Cmp<T> = (a: T) => (b: T) => Sign;

package/types/sorted_set/test.f.d.ts

@@ -1,4 +1,5 @@
 declare const _default: {
+    example: () => void;
     union: (() => void)[];
     intersect: (() => void)[];
     has: (() => void)[];

package/types/sorted_set/test.f.js

@@ -7,6 +7,25 @@ import { flip } from "../function/module.f.js";
 const stringify = a => json.stringify(sort)(a);
 const reverseCmp = flip(unsafeCmp);
 export default {
+    example: () => {
+        const cmp = (a) => (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]
+        if (stringify(unionSet) !== '[1,3,4,5]') {
+            throw 0;
+        }
+        const intersectionSet = intersect(cmp)(setA)(setB); // [3, 5]
+        if (stringify(intersectionSet) !== '[3,5]') {
+            throw 1;
+        }
+        if (!has(cmp)(3)(setA)) {
+            throw 2;
+        }
+        if (has(cmp)(2)(setA)) {
+            throw 3;
+        }
+    },
     union: [
         () => {
             const result = stringify(toArray(union(unsafeCmp)([2, 3, 4])([1, 3, 5])));

package/types/string/module.f.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Utility functions for working with strings and lists of strings.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { join, concat, repeat, cmp } from './module.f.ts'
+ *
+ * const words = ['hello', 'world']
+ * join(' ')(words) // 'hello world'
+ * concat(words) // 'helloworld'
+ * repeat('abc')(3) // 'abcabcabc'
+ * cmp('apple')('banana') // -1
+ * ```
+ */
 import { type List } from '../list/module.f.ts';
 import { type Sign } from '../function/compare/module.f.ts';
 export declare const join: (_: string) => (input: List<string>) => string;