functionalscript 0.3.11 → 0.3.13

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 { get, merge, fromRange } 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 result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["b"],2]]') {
                 throw result;
             }
@@ -22,7 +65,7 @@ export default {
             const a = null;
             const b = [[['a'], 1], [['b'], 2]];
             const merged = merge(op)(a)(b);
-            const result = stringify(list.toArray(merged));
+            const result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["b"],2]]') {
                 throw result;
             }
@@ -31,7 +74,7 @@ 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 result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["b"],2]]') {
                 throw result;
             }
@@ -40,7 +83,7 @@ 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 result = stringify(toArray(merged));
             if (result !== '[[["a","b"],1],[["b","c"],2],[["c","d"],3],[["d"],4]]') {
                 throw result;
             }
@@ -49,7 +92,7 @@ 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 result = stringify(toArray(merged));
             if (result !== '[[["a","b"],1],[["b","d"],2],[["c","d"],3],[["d"],4]]') {
                 throw result;
             }
@@ -58,7 +101,7 @@ 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 result = stringify(toArray(merged));
             if (result !== '[[["a","b"],2]]') {
                 throw result;
             }
@@ -67,7 +110,7 @@ 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 result = stringify(toArray(merged));
             if (result !== '[[["a"],1],[["a","b"],2],[["a"],5]]') {
                 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

@@ -28,14 +28,15 @@ const cmpReduce = (cmp) => () => a => b => {
 };
 const mergeTail = () => identity;
 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;