@rimbu/common 2.0.4 → 2.0.6

package/dist/bun/comp.mts

@@ -1,625 +0,0 @@
-import { Eq } from './internal.mts';
-
-/**
- * An object providing methods to compare two values of type `K`.
- * @typeparam K - the value type
- */
-export interface Comp<K> {
-  /**
-   * Returns 0 if given `value1` and `value2` are equal, a positive value is `value1` is greater than
-   * `value2`, and a negative value otherwise.
-   * @param value1 - the first value to compare
-   * @param value2 - the seconds value to compare
-   * @example
-   * ```ts
-   * const c = Comp.numberComp()
-   * console.log(c.compare(5, 5))
-   * // => 0
-   * console.log(c.compare(3, 5))
-   * // => -2
-   * console.log(c.compare(5, 3))
-   * // => 2
-   * ```
-   */
-  compare(value1: K, value2: K): number;
-  /**
-   * Returns true if this instance can compare given `obj`.
-   * @param obj - the object to check
-   * @example
-   * ```ts
-   * const c = Comp.numberComp()
-   * console.log(c.isComparable(5))
-   * // => true
-   * console.log(c.isComparable('a'))
-   * // => false
-   * ```
-   */
-  isComparable(obj: any): obj is K;
-}
-
-export namespace Comp {
-  const _anyFlatComp: Comp<any> = createAnyComp('FLAT');
-  const _anyShallowComp: Comp<any> = createAnyComp('SHALLOW');
-  const _anyDeepComp: Comp<any> = createAnyComp('DEEP');
-
-  /**
-   * Returns the default Comp instance, which is the Comp.anyDeepComp() instance.
-   */
-  export function defaultComp(): Comp<any> {
-    return _anyDeepComp;
-  }
-
-  const _numberComp: Comp<number> = {
-    isComparable(obj): obj is number {
-      return typeof obj === 'number';
-    },
-    compare(v1, v2) {
-      if (Number.isFinite(v1) && Number.isFinite(v2)) {
-        return v1 - v2;
-      }
-      if (Number.isNaN(v1)) {
-        if (Number.isNaN(v2)) return 0;
-        if (v2 === Number.POSITIVE_INFINITY) return 1;
-        if (v2 === Number.NEGATIVE_INFINITY) return -1;
-        return -1;
-      }
-
-      // only infinities remain
-      if (v1 === Number.POSITIVE_INFINITY) {
-        return v2 === Number.POSITIVE_INFINITY ? 0 : 1;
-      }
-
-      // v1 === Number.NEGATIVE_INFINITY
-      return v2 === Number.NEGATIVE_INFINITY ? 0 : -1;
-    },
-  };
-
-  /**
-   * Returns a default number Comp instance that orders numbers naturally.
-   * @example
-   * ```ts
-   * const c = Comp.numberComp();
-   * console.log(c.compare(3, 5))
-   * // => -2
-   * ```
-   */
-  export function numberComp(): Comp<number> {
-    return _numberComp;
-  }
-
-  const _booleanComp: Comp<boolean> = {
-    isComparable(obj): obj is boolean {
-      return typeof obj === 'boolean';
-    },
-    compare(v1, v2) {
-      return v1 === v2 ? 0 : v1 ? 1 : -1;
-    },
-  };
-
-  /**
-   * Returns a default boolean Comp instance that orders booleans according to false < true.
-   * @example
-   * ```ts
-   * const c = Comp.booleanComp();
-   * console.log(c.compare(false, true) < 0)
-   * // => true
-   * console.log(c.compare(true, true))
-   * // => 0
-   * ```
-   */
-  export function booleanComp(): Comp<boolean> {
-    return _booleanComp;
-  }
-
-  const _bigIntComp: Comp<bigint> = {
-    isComparable(obj): obj is bigint {
-      return typeof obj === 'bigint';
-    },
-    compare(v1, v2) {
-      const res = v1 - v2;
-      if (res > 0) return 1;
-      if (res < 0) return -1;
-      return 0;
-    },
-  };
-
-  /**
-   * Returns a default bigint Comp instance that orders bigint numbers naturally.
-   */
-  export function bigIntComp(): Comp<bigint> {
-    return _bigIntComp;
-  }
-
-  const _defaultCollator = Intl.Collator('und');
-
-  const _stringComp: Comp<string> = {
-    isComparable(obj): obj is string {
-      return typeof obj === 'string';
-    },
-    compare: _defaultCollator.compare,
-  };
-
-  const _anyStringJSONComp: Comp<any> = {
-    isComparable(obj): obj is any {
-      return true;
-    },
-    compare(v1, v2) {
-      return _defaultCollator.compare(JSON.stringify(v1), JSON.stringify(v2));
-    },
-  };
-
-  /**
-   * Returns a Comp instance converts values to string with JSON.stringify, and orders the resulting string naturally.
-   */
-  export function anyStringJSONComp<T>(): Comp<T> {
-    return _anyStringJSONComp;
-  }
-
-  /**
-   * Returns a `Comp` instance that compares strings based on the string's `localeCompare` method.
-   * @param locales - (optional) a locale or list of locales
-   * @param options - (optional) see String.localeCompare for details
-   */
-  export function stringComp(
-    ...args: ConstructorParameters<typeof Intl.Collator>
-  ): Comp<string> {
-    if (args.length === 0) return _stringComp;
-
-    const collator = Intl.Collator(...args);
-
-    return {
-      isComparable(obj): obj is string {
-        return typeof obj === 'string';
-      },
-      compare: collator.compare,
-    };
-  }
-
-  /**
-   * Returns a `Comp` instance that compares strings in a case-insensitive way.
-   */
-  export function stringCaseInsensitiveComp(): Comp<string> {
-    return stringComp('und', { sensitivity: 'accent' });
-  }
-
-  const _stringCharCodeComp: Comp<string> = {
-    isComparable(obj: any): obj is any {
-      return typeof obj === 'string';
-    },
-    compare(v1: any, v2: any): number {
-      const len = Math.min(v1.length, v2.length);
-
-      let i = -1;
-
-      while (++i < len) {
-        const diff = v1.charCodeAt(i) - v2.charCodeAt(i);
-        if (diff !== 0) return diff;
-      }
-
-      return v1.length - v2.length;
-    },
-  };
-
-  /**
-   * Returns a string Comp instance that orders strings according to their indexed char codes.
-   */
-  export function stringCharCodeComp(): Comp<string> {
-    return _stringCharCodeComp;
-  }
-
-  const _anyToStringComp: Comp<any> = {
-    isComparable(obj: any): obj is any {
-      return true;
-    },
-    compare(v1: any, v2: any): number {
-      return _defaultCollator.compare(
-        Eq.convertAnyToString(v1),
-        Eq.convertAnyToString(v2)
-      );
-    },
-  };
-
-  /**
-   * Returns a any Comp instance that orders any according to their toString values.
-   */
-  export function anyToStringComp(): Comp<any> {
-    return _anyToStringComp;
-  }
-
-  /**
-   * Returns a Comp instance that orders objects with a `valueOf` method according to the given `valueComp` instance for the valueOf values.
-   * @param cls - the constructor of the values the Comp instance can compare
-   * @param valueComp - (optional) the Comp instance to use on the .valueOf values
-   */
-  export function createValueOfComp<T extends { valueOf(): V }, V>(
-    cls: {
-      new (): T;
-    },
-    valueComp: Comp<V> = anyShallowComp()
-  ): Comp<T> {
-    return {
-      isComparable(obj): obj is T {
-        return obj instanceof cls;
-      },
-      compare(v1, v2): number {
-        return valueComp.compare(v1.valueOf(), v2.valueOf());
-      },
-    };
-  }
-
-  const _DateComp: Comp<Date> = createValueOfComp(Date, _numberComp);
-
-  /**
-   * Returns a Date Comp instance that orders Dates according to their `.valueOf` value.
-   */
-  export function dateComp(): Comp<Date> {
-    return _DateComp;
-  }
-
-  function createIterableComp<T>(itemComp: Comp<T>): Comp<Iterable<T>> {
-    return {
-      isComparable(obj): obj is Iterable<T> {
-        // unfortunately we cannot check element compatability
-        return (
-          typeof obj === 'object' && obj !== null && Symbol.iterator in obj
-        );
-      },
-      compare(v1, v2): number {
-        const iter1 = v1[Symbol.iterator]();
-        const iter2 = v2[Symbol.iterator]();
-
-        while (true) {
-          const value1 = iter1.next();
-          const value2 = iter2.next();
-
-          if (value1.done) return value2.done ? 0 : -1;
-          if (value2.done) return 1;
-
-          const result = itemComp.compare(value1.value, value2.value);
-
-          if (result !== 0) return result;
-        }
-      },
-    };
-  }
-
-  const _iterableAnyComp: Comp<Iterable<any>> = createIterableComp(
-    Comp.defaultComp()
-  );
-
-  /**
-   * Returns a Comp instance for Iterable objects that orders the Iterables by comparing the elements with the given `itemComp` Comp instance.
-   * @param itemComp - (optional) the Comp instance to use to compare the Iterable's elements.
-   * @example
-   * ```ts
-   * const c = Comp.iterableComp();
-   * console.log(c.compare([1, 3, 2], [1, 3, 2]))
-   * // => 0
-   * console.log(c.compare([1, 2, 3, 4], [1, 3, 2]) < 0)
-   * // => true
-   * ```
-   */
-  export function iterableComp<T>(itemComp?: Comp<T>): Comp<Iterable<T>> {
-    if (undefined === itemComp) return _iterableAnyComp;
-
-    return createIterableComp(itemComp);
-  }
-
-  const _BooleanComp = createValueOfComp(Boolean, _booleanComp);
-  const _NumberComp = createValueOfComp(Number, _numberComp);
-  const _StringComp = createValueOfComp(String, _stringComp);
-
-  const _wrappedComps: Comp<unknown>[] = [
-    _BooleanComp,
-    _DateComp,
-    _NumberComp,
-    _StringComp,
-  ];
-
-  function tryWrappedComp(v1: any, v2: any): number | undefined {
-    let i = -1;
-    const len = _wrappedComps.length;
-
-    while (++i < len) {
-      const comp = _wrappedComps[i];
-
-      if (comp.isComparable(v1) && comp.isComparable(v2)) {
-        return comp.compare(v1, v2);
-      }
-    }
-
-    return undefined;
-  }
-
-  function createObjectComp(
-    keyComp: Comp<any> = anyFlatComp(),
-    valueComp: Comp<any> = defaultComp()
-  ): Comp<Record<any, any>> {
-    return {
-      isComparable(obj): obj is Record<any, any> {
-        return true;
-      },
-      compare(v1, v2): number {
-        const keys1 = Object.keys(v1);
-        const keys2 = Object.keys(v2);
-
-        if (keys1.length === 0) {
-          return keys2.length === 0 ? 0 : -1;
-        }
-        if (keys2.length === 0) {
-          return keys1.length === 0 ? 0 : 1;
-        }
-
-        keys1.sort(keyComp.compare);
-        keys2.sort(keyComp.compare);
-
-        const length = Math.min(keys1.length, keys2.length);
-
-        for (let index = 0; index < length; index++) {
-          const key1 = keys1[index];
-          const key2 = keys2[index];
-          const keyResult = keyComp.compare(key1, key2);
-
-          if (keyResult !== 0) return keyResult;
-
-          const value1 = v1[key1];
-          const value2 = v2[key2];
-
-          const valueResult = valueComp.compare(value1, value2);
-
-          if (valueResult !== 0) return valueResult;
-        }
-
-        const keyDiff = keys1.length - keys2.length;
-
-        return keyDiff;
-      },
-    };
-  }
-
-  const _objectAnyComp: Comp<Record<any, any>> = createObjectComp();
-
-  /**
-   * Returns a Comp instance for objects that orders the object keys according to the given `keyComp`, and then compares the corresponding
-   * values using the given `valueComp`. Objects are then compared as follows:<br/>
-   * starting with the smallest key of either object:<br/>
-   * - if only one of the objects has the key, the object with the key is considered to be larger than the other<br/>
-   * - if both objects have the key, the values are compared with `valueComp`. If the values are not equal, this result is returned.<br/>
-   *
-   * if the objects have the same keys with the same values, they are considered equal<br/>
-   * @param keyComp - (optional) the Comp instance used to order the object keys
-   * @param valueComp - (optional) the Comp instance used to order the object values
-   * @example
-   * ```ts
-   * const c = Comp.objectComp();
-   * console.log(c.compare({ a: 1 }, { a: 1 }))
-   * // => 0
-   * console.log(c.compare({ a: 1 }, { a: 2 }) < 0)
-   * // => true
-   * console.log(c.compare({ b: 5 }, { a: 2 }) < 0)
-   * // => true
-   * console.log(c.compare({ a: 1, b: 2 }, { b: 5 }) < 0)
-   * // => true
-   * console.log(c.compare({ a: 1, b: 2 }, { b: 2, a: 1 }))
-   * // => 0
-   * ```
-   */
-  export function objectComp(options?: {
-    keyComp?: Comp<any>;
-    valueComp?: Comp<any>;
-  }): Comp<Record<any, any>> {
-    if (undefined === options) return _objectAnyComp;
-
-    return createObjectComp(options.keyComp, options.valueComp);
-  }
-
-  function createAnyComp(mode: 'FLAT' | 'SHALLOW' | 'DEEP'): Comp<any> {
-    return {
-      isComparable(obj): obj is any {
-        return true;
-      },
-      compare(v1, v2): number {
-        if (Object.is(v1, v2)) return 0;
-
-        const type1 = typeof v1;
-        const type2 = typeof v2;
-
-        if (type1 !== type2) {
-          // we can only compare different types though strings
-          return _anyToStringComp.compare(v1, v2);
-        }
-
-        switch (type1) {
-          case 'bigint':
-            return _bigIntComp.compare(v1, v2);
-          case 'boolean':
-            return _booleanComp.compare(v1, v2);
-          case 'number':
-            return _numberComp.compare(v1, v2);
-          case 'string':
-            return _stringComp.compare(v1, v2);
-          case 'object': {
-            if (null === v1) {
-              if (null === v2) return 0;
-
-              return -1;
-            }
-            if (null === v2) {
-              return 1;
-            }
-
-            const wrappedComp = tryWrappedComp(v1, v2);
-
-            if (undefined !== wrappedComp) return wrappedComp;
-
-            if (mode !== 'FLAT') {
-              if (
-                _iterableAnyComp.isComparable(v1) &&
-                _iterableAnyComp.isComparable(v2)
-              ) {
-                if (mode === 'SHALLOW') {
-                  return iterableComp(_anyFlatComp).compare(v1, v2);
-                }
-
-                return iterableComp(this).compare(v1, v2);
-              }
-
-              if (mode === 'SHALLOW') {
-                return createObjectComp(_anyFlatComp, _anyFlatComp).compare(
-                  v1,
-                  v2
-                );
-              }
-
-              return _objectAnyComp.compare(v1, v2);
-            }
-          }
-        }
-
-        return _anyToStringComp.compare(v1, v2);
-      },
-    };
-  }
-
-  /**
-   * Returns a Comp instance that compares any value using default comparison functions, but never recursively compares
-   * Iterables or objects. In those cases, it will use the stringComp instance.
-   * @example
-   * ```ts
-   * const c = Comp.anyFlatComp();
-   * console.log(c.compare({ a: 1, b: 1 }, { b: 1, a: 1 }) < 0)
-   * // => true
-   * // First object is smaller because the objects are converted to a string with and then compares the resulting string.
-   * ```
-   */
-  export function anyFlatComp<T>(): Comp<T> {
-    return _anyFlatComp;
-  }
-
-  /**
-   * Returns a Comp instance that compares any value using default comparison functions. For Iterables and objects, their elements are compared
-   * only one level deep for performance and to avoid infinite recursion.
-   * @example
-   * ```ts
-   * const c = Comp.anyShallowComp();
-   * console.log(c.compare({ a: 1, b: 1 }, { b: 1, a: 1 }))
-   * // => 0
-   * console.log(c.compare([{ a: 1, b: 1 }], [{ b: 1, a: 1 }]) < 0)
-   * // => true
-   * // First object is smaller because the objects are converted to a string and then compares the resulting string.
-   * ```
-   */
-  export function anyShallowComp<T>(): Comp<T> {
-    return _anyShallowComp;
-  }
-
-  /**
-   * Returns a Comp instance that compares any value using default comparison functions. For Iterables and objects, their elements are compared
-   * recursively.
-   * @note can become slow with large nested arrays and objects, and circular structures can cause infinite loops
-   * @example
-   * ```ts
-   * const c = Comp.anyDeepComp();
-   * console.log(c.compare({ a: 1, b: 1 }, { b: 1, a: 1 }))
-   * // => 0
-   * console.log(c.compare([{ a: 1, b: 1 }], [{ b: 1, a: 1 }]))
-   * // => 0
-   * ```
-   */
-  export function anyDeepComp<T>(): Comp<T> {
-    return _anyDeepComp;
-  }
-
-  /**
-   * Returns a Comp instance that extends the given `comp` instance with the capability to handle `undefined` values, where undefined is considered to be smaller
-   * than any other value, and equal to another undefined.
-   * @param comp - the Comp instance to wrap
-   * @example
-   * ```ts
-   * const c = Comp.withUndefined(Comp.numberComp())
-   * console.log(c.compare(undefined, 5) < 0)
-   * // => true
-   * console.log(c.compare(undefined, undefined))
-   * // => 0
-   * ```
-   */
-  export function withUndefined<T>(comp: Comp<T>): Comp<T | undefined> {
-    return {
-      isComparable(obj): obj is T | undefined {
-        return undefined === obj || comp.isComparable(obj);
-      },
-      compare(v1, v2): number {
-        if (undefined === v1) {
-          if (undefined === v2) return 0;
-          return -1;
-        }
-        if (undefined === v2) return 1;
-        return comp.compare(v1, v2);
-      },
-    };
-  }
-
-  /**
-   * Returns a Comp instance that extends the given `comp` instance with the capability to handle `null` values, where null is considered to be smaller
-   * than any other value, and equal to another null.
-   * @param comp - the Comp instance to wrap
-   * @example
-   * ```ts
-   * const c = Comp.withNull(Comp.numberComp())
-   * console.log(c.compare(null, 5) < 0)
-   * // => true
-   * console.log(c.compare(null, null))
-   * // => 0
-   * ```
-   */
-  export function withNull<T>(comp: Comp<T>): Comp<T | null> {
-    return {
-      isComparable(obj): obj is T | null {
-        return null === obj || comp.isComparable(obj);
-      },
-      compare(v1, v2): number {
-        if (null === v1) {
-          if (null === v2) return 0;
-          return -1;
-        }
-        if (null === v2) return 1;
-        return comp.compare(v1, v2);
-      },
-    };
-  }
-
-  /**
-   * Returns a Comp instance the reverses the order of the given `comp` instance.
-   * @param comp - the Comp instance to wrap
-   * @example
-   * ```ts
-   * const c = Comp.invert(Comp.numberComp())
-   * console.log(c.compare(3, 5) > 0)
-   * // => true
-   * console.log(c.compare(5, 5))
-   * // => 0
-   * ```
-   */
-  export function invert<T>(comp: Comp<T>): Comp<T> {
-    return {
-      compare(v1, v2): number {
-        return comp.compare(v2, v1);
-      },
-      isComparable: comp.isComparable,
-    };
-  }
-
-  /**
-   * Returns an `Eq` equality instance thet will return true when the given `comp` comparable instance returns 0.
-   * @param comp - the `Comp` comparable instance to convert
-   * @example
-   * ```ts
-   * const eq = Comp.toEq(Comp.objectComp())
-   * console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
-   * // => true
-   * ```
-   */
-  export function toEq<T>(comp: Comp<T>): Eq<T> {
-    return (v1: T, v2: T): boolean => comp.compare(v1, v2) === 0;
-  }
-}