atomic-fns 0.3.1 → 0.3.3

package/{src → core}/itertools/index.ts

@@ -6,15 +6,15 @@
 
 import {
   call,
-  Comp,
   Function,
   isEmpty,
   isObject,
+  Iteratee,
   notNull,
   Predicate,
   ValueError
 } from '../globals/index.js'
-import { add, bool, comp, eq, id } from '../operators/index.js'
+import { add, bool, compare, Comparer, eq, id } from '../operators/index.js'
 
 /**
  * Make an iterator that returns accumulated sums, or accumulated results of other binary functions (specified via the optional `func` argument).
@@ -119,7 +119,7 @@ export function contains(collection: Iterable<any>, value) {
   return any(collection, (x) => eq(value, x))
 }
 
-const compKey = (cmp: Comp, key) => (x, y) => cmp(key(x), key(y))
+const compKey = (compare: Comparer, key) => (x, y) => compare(key(x), key(y))
 
 /**
  * Returns a generator that drops elements from the iterable as long as the predicate is `true`; afterwards, returns every remaining element. Note, the generator does not produce any output until the predicate first becomes `false`.
@@ -144,6 +144,24 @@ export function* dropWhile<T>(iterable: Iterable<T>, predicate: Predicate) {
   }
 }
 
+export function iforEach<T>(iterable: Iterable<T>, fun: Iteratee<T>) {
+  for (const [index, value] of enumerate(iterable)) {
+    if (fun(value as T, index, iterable) === false) {
+      return
+    }
+  }
+}
+
+export function IterableIterator<T = any>(next) {
+  const it: Iterator<T> & Iterable<T> = {
+    next,
+    [Symbol.iterator]() {
+      return this
+    }
+  }
+  return it
+}
+
 /**
  * Yields elements like `[index, item]` from an iterable. Index starts at zero by default.
  * @template T
@@ -177,7 +195,7 @@ export function first<T>(iterable: Iterable<T>) {
 }
 
 /**
- * Creates a new generator that filters all `falsey` and empty values from iterable.
+ * Creates a new generator that filters all falsy and empty values from iterable.
  * @param arr The array to compact
  * @returns A new array with the filtered values.
  * @example
@@ -201,7 +219,7 @@ export function* ifilter<T>(iterable: Iterable<T>, predicate: Predicate) {
   }
 }
 
-export function* imap<T>(iterable: Iterable<T>, mapFn: (x: T) => any) {
+export function* imap<T, TReturn = any>(iterable: Iterable<T>, mapFn: (x: T) => TReturn) {
   for (const item of iterable) {
     yield mapFn(item)
   }
@@ -352,7 +370,7 @@ export function reversed<T>(iterable: Iterable<T>) {
 
 export function sorted(args: any[]): any[]
 export function sorted(args: any[], reverse: boolean): any[]
-export function sorted(args: any[], reverse: boolean, comp: Comp): any[]
+export function sorted(args: any[], reverse: boolean, comp: Comparer): any[]
 export function sorted(args: any[], key: Function): any[]
 export function sorted(args: any[], key: Function, reverse: boolean): any[]
 
@@ -369,11 +387,16 @@ export function sorted(args: any[], key: Function, reverse: boolean): any[]
  *
  * @param {(Array | Object)} args
  * @param {(boolean | Function)} [key]
- * @param {(boolean | Comp)} [reverse]
- * @param {Comp} [compareFn]
+ * @param {(boolean | Comparer)} [reverse]
+ * @param {Comparer} [compareFn]
  * @return
  */
-export function sorted(args, key?: boolean | Function, reverse?: boolean | Comp, compareFn?: Comp) {
+export function sorted(
+  args,
+  key?: boolean | Function,
+  reverse?: boolean | Comparer,
+  compareFn?: Comparer
+) {
   if (isObject(args)) args = Object.keys(args)
   if (typeof key === 'boolean') {
     if (typeof reverse === 'function') {
@@ -385,7 +408,7 @@ export function sorted(args, key?: boolean | Function, reverse?: boolean | Comp,
     key = id
   }
   const copy = Array.from(args)
-  const _compare = compKey(compareFn || comp, key || id)
+  const _compare = compKey(compareFn || compare, key || id)
   copy.sort(_compare)
   if (reverse) copy.reverse()
   return copy
@@ -393,8 +416,8 @@ export function sorted(args, key?: boolean | Function, reverse?: boolean | Comp,
 
 export function sort(args: any[]): any[]
 export function sort(args: any[], reverse: boolean): any[]
-export function sort(args: any[], compareFn: Comp): any[]
-export function sort(args: any[], reverse: boolean, compareFn: Comp): any[]
+export function sort(args: any[], compareFn: Comparer): any[]
+export function sort(args: any[], reverse: boolean, compareFn: Comparer): any[]
 
 /**
  * Sort `args` in place. Can be called like this:
@@ -403,16 +426,16 @@ export function sort(args: any[], reverse: boolean, compareFn: Comp): any[]
  *   - sort([...], true, (x, y) => number) => reverse and using custom compare
  *
  * @param {any[]} args
- * @param {(boolean | Comp)} [reverse]
- * @param {Comp} [compareFn]
+ * @param {(boolean | Comparer)} [reverse]
+ * @param {Comparer} [compareFn]
  * @return
  */
-export function sort(args: any[], reverse?: boolean | Comp, compareFn?: Comp) {
+export function sort(args: any[], reverse?: boolean | Comparer, compareFn?: Comparer) {
   if (typeof reverse === 'function') {
     compareFn = reverse
     reverse = false
   }
-  args.sort(compareFn || comp)
+  args.sort(compareFn || compare)
   if (reverse === true) args.reverse()
   return args
 }

package/core/operators/index.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Generic operations for both values and objects.
+ *
+ * @module Operators
+ */
+/** This is the identity function. It always returns the same value that was passed in */
+export declare const id: (x: any) => any;
+/**
+ * Called to implement truth value testing.
+ * @param x
+ * @returns {boolean} `x.bool()` if exists or `!!x`.
+ */
+export declare const bool: (x: any) => any;
+/**
+ * Returns `true` if `x` is a falsy value.
+ * @see {@link bool}
+ */
+export declare const not: (x: any) => boolean;
+/**
+ * Returns `true` if `x` is an instance of class `y`
+ * @param x The instance object
+ * @param y The parent class
+ * @returns {boolean}
+ */
+export declare const isinstance: (x: any, y: any) => boolean;
+/** Describes a function used to compare two values.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#parameters Array.sort()}
+ */
+export declare type Comparer<T = any> = (x: T, y: T) => number;
+/**
+ * Checks whether `x` is a comparable type and returns the result of `x.compare(y)`.
+ * Otherwise the return value of the compare function is equivalent to `obj === other ? 0 : obj < other ? -1 : 1`
+ * @param {*} x An initial value
+ * @param {*} y Other value to compare
+ * @returns {number} The comparison result
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#parameters Array.sort()}
+ * @see {@link eq}
+ * @see {@link lt}
+ */
+export declare function compare(x: any, y: any): number;
+/**
+ * Compares two values to check if they are the same. If `x` is an object with an `eq` method, it returns `x.eq(y)`.
+ * Otherwise it returns the result of `x === y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` and `y` are equal or `false` otherwise.
+ */
+export declare function eq(x: any, y: any): boolean;
+/**
+ * Compares two values to check if `x` is strictly less than `y`. If `x` is an object with a `lt` method, it returns `x.lt(y)`.
+ * Otherwise it returns the result of `x < y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is strictly less than `y` or `false` otherwise.
+ */
+export declare function lt(x: any, y: any): boolean;
+/**
+ * Compares two values to check if `x <= y`. If `x` is an object with a `lte` method, it returns `x.lte(y)`, also checks `x.eq(y)` and `x.lt(y)`.
+ * Otherwise it returns the result of `x <= y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is less than or equal to `y` or `false` otherwise.
+ * @see {@link eq}
+ * @see {@link lt}
+ */
+export declare function lte(x: any, y: any): boolean;
+/**
+ * Compares two values to check if `x` is strictly greater than `y`. If `x` is an object with a `gt` method, it returns `x.gt(y)`.
+ * Otherwise it returns the result of `x > y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is strictly greater than `y` or `false` otherwise.
+ */
+export declare function gt(x: any, y: any): any;
+/**
+ * Compares two values to check if `x >= y`. If `x` is an object with a `gte` method, it returns `x.gte(y)`, also checks `x.eq(y)` and `x.gt(y)`.
+ * Otherwise it returns the result of `x >= y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is less greater than or equal to `y` or `false` otherwise.
+ * @see {@link eq}
+ * @see {@link gt}
+ */
+export declare function gte(x: any, y: any): boolean;
+/**
+ * The addition (+) operator. If `x` is an object with an `add` method, it returns `x.add(y)`.
+ * Otherwise it returns the result of `x + y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x + y
+ */
+export declare function add(x: any, y: any): any;
+/**
+ * The subtraction (-) operator. If `x` is an object with a `sub` method, it returns `x.sub(y)`.
+ * Otherwise it returns the result of `x - y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x - y
+ */
+export declare function sub(x: any, y: any): any;
+/**
+ * The multiplication (*) operator. If `x` is an object with an `mul` method, it returns `x.mul(y)`.
+ * Otherwise it returns the result of `x * y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x * y
+ */
+export declare function mul(x: any, y: any): any;
+/**
+ * The division (/) operator. If `x` is an object with a `div` method, it returns `x.div(y)`.
+ * Otherwise it returns the result of `x / y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x / y
+ */
+export declare function div(x: any, y: any): any;
+/**
+ * The modulo (%) operator. If `x` is an object with a `mod` method, it returns `x.mod(y)`.
+ * Otherwise it returns the result of `x % y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x % y
+ */
+export declare function mod(x: any, y: any): any;
+/**
+ * The power (**) operator. If `x` is an object with a `pow` method, it returns `x.pow(y)`.
+ * Otherwise it returns the result of `x ** y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x ** y
+ */
+export declare function pow(x: any, y: any): any;
+/**
+ * Performs a shallow comparison of two objects or arrays to check if they have the same keys, length and values.
+ * @param obj
+ * @param other
+ * @returns `true` if the objects are considered equal.
+ * @see {@link deepEqual}
+ */
+export declare function shallowEqual(obj: any, other: any): boolean;
+/**
+ * Performs a recursive comparison of two objects or arrays to check if they have the same keys, length and values. Unlike {@link shallowEqual} this method compares nested values also.
+ * @param obj
+ * @param other
+ * @returns `true` if the objects are considered equal.
+ */
+export declare function deepEqual(obj: any, other: any, checker?: typeof eq): boolean;

package/core/operators/index.js

@@ -0,0 +1,271 @@
+/**
+ * Generic operations for both values and objects.
+ *
+ * @module Operators
+ */
+import { call, isObject } from '../globals/index.js';
+/** This is the identity function. It always returns the same value that was passed in */
+export const id = (x) => x;
+/**
+ * Called to implement truth value testing.
+ * @param x
+ * @returns {boolean} `x.bool()` if exists or `!!x`.
+ */
+export const bool = (x) => {
+    const r = call(x, 'bool');
+    if (r != null)
+        return r;
+    return !!x;
+};
+/**
+ * Returns `true` if `x` is a falsy value.
+ * @see {@link bool}
+ */
+export const not = (x) => !bool(x);
+/**
+ * Returns `true` if `x` is an instance of class `y`
+ * @param x The instance object
+ * @param y The parent class
+ * @returns {boolean}
+ */
+export const isinstance = (x, y) => x instanceof y;
+/**
+ * Checks whether `x` is a comparable type and returns the result of `x.compare(y)`.
+ * Otherwise the return value of the compare function is equivalent to `obj === other ? 0 : obj < other ? -1 : 1`
+ * @param {*} x An initial value
+ * @param {*} y Other value to compare
+ * @returns {number} The comparison result
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#parameters Array.sort()}
+ * @see {@link eq}
+ * @see {@link lt}
+ */
+export function compare(x, y) {
+    if (x === y || eq(x, y))
+        return 0;
+    const op = call(x, 'compare', y);
+    if (typeof op === 'number')
+        return op;
+    if (x < y || lt(x, y))
+        return -1;
+    return 1;
+}
+/**
+ * Compares two values to check if they are the same. If `x` is an object with an `eq` method, it returns `x.eq(y)`.
+ * Otherwise it returns the result of `x === y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` and `y` are equal or `false` otherwise.
+ */
+export function eq(x, y) {
+    return x === y || call(x, 'eq', y) != null;
+}
+/**
+ * Compares two values to check if `x` is strictly less than `y`. If `x` is an object with a `lt` method, it returns `x.lt(y)`.
+ * Otherwise it returns the result of `x < y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is strictly less than `y` or `false` otherwise.
+ */
+export function lt(x, y) {
+    return x < y || call(x, 'lt', y) != null;
+}
+/**
+ * Compares two values to check if `x <= y`. If `x` is an object with a `lte` method, it returns `x.lte(y)`, also checks `x.eq(y)` and `x.lt(y)`.
+ * Otherwise it returns the result of `x <= y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is less than or equal to `y` or `false` otherwise.
+ * @see {@link eq}
+ * @see {@link lt}
+ */
+export function lte(x, y) {
+    if (x <= y || call(x, 'lte', y))
+        return true;
+    if (x === y || eq(x, y))
+        return true;
+    if (x < y || lt(x, y))
+        return true;
+    return false;
+}
+/**
+ * Compares two values to check if `x` is strictly greater than `y`. If `x` is an object with a `gt` method, it returns `x.gt(y)`.
+ * Otherwise it returns the result of `x > y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is strictly greater than `y` or `false` otherwise.
+ */
+export function gt(x, y) {
+    return x > y || call(x, 'gt', y);
+}
+/**
+ * Compares two values to check if `x >= y`. If `x` is an object with a `gte` method, it returns `x.gte(y)`, also checks `x.eq(y)` and `x.gt(y)`.
+ * Otherwise it returns the result of `x >= y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {boolean} `true` if `x` is less greater than or equal to `y` or `false` otherwise.
+ * @see {@link eq}
+ * @see {@link gt}
+ */
+export function gte(x, y) {
+    if (x <= y || call(x, 'gte', y))
+        return true;
+    if (x === y || eq(x, y))
+        return true;
+    if (x > y || gt(x, y))
+        return true;
+    return false;
+}
+/**
+ * The addition (+) operator. If `x` is an object with an `add` method, it returns `x.add(y)`.
+ * Otherwise it returns the result of `x + y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x + y
+ */
+export function add(x, y) {
+    const op = call(x, 'add', y);
+    if (op != null)
+        return op;
+    return x + y;
+}
+/**
+ * The subtraction (-) operator. If `x` is an object with a `sub` method, it returns `x.sub(y)`.
+ * Otherwise it returns the result of `x - y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x - y
+ */
+export function sub(x, y) {
+    const op = call(x, 'sub', y);
+    if (op != null)
+        return op;
+    return x - y;
+}
+/**
+ * The multiplication (*) operator. If `x` is an object with an `mul` method, it returns `x.mul(y)`.
+ * Otherwise it returns the result of `x * y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x * y
+ */
+export function mul(x, y) {
+    const op = call(x, 'mul', y);
+    if (op != null)
+        return op;
+    return x * y;
+}
+/**
+ * The division (/) operator. If `x` is an object with a `div` method, it returns `x.div(y)`.
+ * Otherwise it returns the result of `x / y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x / y
+ */
+export function div(x, y) {
+    const op = call(x, 'div', y);
+    if (op != null)
+        return op;
+    return x / y;
+}
+/**
+ * The modulo (%) operator. If `x` is an object with a `mod` method, it returns `x.mod(y)`.
+ * Otherwise it returns the result of `x % y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x % y
+ */
+export function mod(x, y) {
+    const op = call(x, 'mod', y);
+    if (op != null)
+        return op;
+    return x % y;
+}
+/**
+ * The power (**) operator. If `x` is an object with a `pow` method, it returns `x.pow(y)`.
+ * Otherwise it returns the result of `x ** y`.
+ * @param {*} x
+ * @param {*} y
+ * @returns {*} x ** y
+ */
+export function pow(x, y) {
+    const op = call(x, 'pow', y);
+    if (op != null)
+        return op;
+    return x ** y;
+}
+/**
+ * Performs a shallow comparison of two objects or arrays to check if they have the same keys, length and values.
+ * @param obj
+ * @param other
+ * @returns `true` if the objects are considered equal.
+ * @see {@link deepEqual}
+ */
+export function shallowEqual(obj, other) {
+    if (obj === other)
+        return true;
+    if (!obj || !other)
+        return false;
+    if (Array.isArray(obj)) {
+        // compare the arrays
+        if (obj.length !== other.length)
+            return false;
+        for (let i = 0; i < obj.length; i++) {
+            if (obj[i] !== other[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    else if (isObject(obj)) {
+        // compare the object keys
+        const objKeys = Object.keys(obj);
+        const otherKeys = Object.keys(other);
+        if (objKeys.length !== otherKeys.length)
+            return false;
+        for (const key of objKeys) {
+            if (!Object.prototype.hasOwnProperty.call(other, key) || obj[key] !== other[key]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Performs a recursive comparison of two objects or arrays to check if they have the same keys, length and values. Unlike {@link shallowEqual} this method compares nested values also.
+ * @param obj
+ * @param other
+ * @returns `true` if the objects are considered equal.
+ */
+export function deepEqual(obj, other, checker = eq) {
+    if (checker(obj, other))
+        return true;
+    if (!obj || !other)
+        return false;
+    if (Array.isArray(obj)) {
+        // compare the arrays
+        if (obj.length !== other.length)
+            return false;
+        for (let i = 0; i < obj.length; i++) {
+            if (!deepEqual(obj[i], other[i], checker)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    else if (isObject(obj)) {
+        // compare the object keys
+        const objKeys = Object.keys(obj);
+        const otherKeys = Object.keys(other);
+        if (objKeys.length !== otherKeys.length)
+            return false;
+        for (const key of objKeys) {
+            if (!Object.prototype.hasOwnProperty.call(other, key) ||
+                !deepEqual(obj[key], other[key], checker)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}