@rimbu/common 0.12.3 → 1.0.0-alpha.2

package/src/eq.mts

@@ -0,0 +1,406 @@
+/**
+ * A function returning true if given `v1` and `v2` should be considered equal.
+ */
+export type Eq<T> = (v1: T, v2: T) => boolean;
+
+export namespace Eq {
+  export function convertAnyToString(value: any): string {
+    if (
+      typeof value !== 'object' ||
+      null === value ||
+      !('toString' in value) ||
+      typeof value.toString !== 'function' ||
+      value.toString !== Object.prototype.toString
+    ) {
+      return String(value);
+    }
+
+    return JSON.stringify(value);
+  }
+
+  const _anyFlatEq: Eq<any> = createAnyEq('FLAT');
+  const _anyShallowEq: Eq<any> = createAnyEq('SHALLOW');
+  const _anyDeepEq: Eq<any> = createAnyEq('DEEP');
+
+  /**
+   * Returns the default Eq instance, which is the Eq.anyDeepEq() instance.
+   */
+  export function defaultEq(): Eq<any> {
+    return _anyDeepEq;
+  }
+
+  /**
+   * An Eq instance that uses `Object.is` to determine if two objects are equal.
+   * @example
+   * ```ts
+   * const eq = Eq.objectIs
+   * console.log(eq(5, 5))
+   * // => true
+   * console.log(eq(5, 'a'))
+   * // => false
+   * ```
+   */
+  export const objectIs: Eq<any> = Object.is;
+
+  const _valueOfEq: Eq<{ valueOf(): any }> = (v1, v2) =>
+    Object.is(v1.valueOf(), v2.valueOf());
+
+  /**
+   * Returns an Eq instance for objects that have a `valueOf` method. It returns true if the `.valueOf` values of both given objects are equal.
+   * @typeparam T - the object type containing a valueOf function of type V
+   * @typeparam V - the valueOf result type
+   * @example
+   * ```ts
+   * const eq = Eq.valueOfEq()
+   * console.log(eq(new Number(5), new Number(5)))
+   * // => true
+   * console.log(eq(new Number(5), new Number(3)))
+   * // => false
+   * ```
+   */
+  export function valueOfEq<T extends { valueOf(): V }, V>(): Eq<T> {
+    return _valueOfEq;
+  }
+
+  /**
+   * Returns an Eq instance that compares Date objects according to their `valueOf` value.
+   * @example
+   * ```ts
+   * const eq = Eq.dateEq()
+   * console.log(eq(new Date(2020, 1, 1), new Date(2020, 1, 1))
+   * // => true
+   * console.log(eq(new Date(2020, 1, 1), new Date(2020, 2, 1))
+   * // => false
+   * ```
+   */
+  export function dateEq(): Eq<Date> {
+    return _valueOfEq;
+  }
+
+  function createIterableEq<T>(itemEq: Eq<T>): Eq<Iterable<T>> {
+    return (v1, v2) => {
+      if (Object.is(v1, v2)) return true;
+
+      const iter1 = v1[Symbol.iterator]();
+      const iter2 = v2[Symbol.iterator]();
+
+      while (true) {
+        const value1 = iter1.next();
+        const value2 = iter2.next();
+
+        if (value1.done || value2.done) return value1.done === value2.done;
+
+        if (!itemEq(value1.value, value2.value)) return false;
+      }
+    };
+  }
+
+  const _iterableAnyEq: Eq<Iterable<any>> = createIterableEq(defaultEq());
+
+  /**
+   * Returns an Eq instance that compares Iterables by comparing their elements with the given `itemEq` Eq instance.
+   * @typeparam T - the Iterable element type
+   * @param itemEq - (optional) the Eq instance to use to compare the Iterable's elements
+   * @example
+   * ```ts
+   * const eq = Eq.iterableEq();
+   * console.log(eq([1, 2, 3], [1, 2, 3])
+   * // => true
+   * console.log(eq([1, 2, 3], [1, 3, 2])
+   * // => false
+   * ```
+   */
+  export function iterableEq<T>(itemEq?: Eq<T>): Eq<Iterable<T>> {
+    if (undefined === itemEq) return _iterableAnyEq;
+
+    return createIterableEq(itemEq);
+  }
+
+  function createObjectEq(valueEq: Eq<any>): Eq<Record<any, any>> {
+    return (v1, v2) => {
+      if (Object.is(v1, v2)) return true;
+
+      if (v1.constructor !== v2.constructor) return false;
+
+      for (const key in v1) {
+        if (!(key in v2)) return false;
+      }
+
+      for (const key in v2) {
+        if (!(key in v1)) return false;
+      }
+
+      for (const key in v1) {
+        const value1 = v1[key];
+        const value2 = v2[key];
+
+        if (!valueEq(value1, value2)) return false;
+      }
+
+      return true;
+    };
+  }
+
+  const _objectEq: Eq<Record<any, any>> = createObjectEq(defaultEq());
+
+  /**
+   * Returns an Eq instance that checks equality of objects containing property values of type V by iteratively
+   * applying given `valueEq` to each of the object's property values.
+   * @typeparam - the object property value type
+   * @param valueEq - (optional) the Eq instance to use to compare property values
+   * @example
+   * ```ts
+   * const eq = Eq.objectEq()
+   * console.log(eq({ a: 1, b: { c: 2 }}, { b: { c: 2 }, a: 1 }))
+   * // => true
+   * console.log(eq({ a: 1, b: { c: 2 }}, { a: 1, b: { c: 3 }}))
+   * // => false
+   * ```
+   */
+  export function objectEq<V = any>(valueEq?: Eq<V>): Eq<Record<any, V>> {
+    if (undefined === valueEq) return _objectEq;
+
+    return createObjectEq(valueEq);
+  }
+
+  function createAnyEq(mode: 'FLAT' | 'SHALLOW' | 'DEEP'): Eq<any> {
+    const result: Eq<any> = (v1, v2): boolean => {
+      if (Object.is(v1, v2)) return true;
+
+      const type1 = typeof v1;
+      const type2 = typeof v2;
+
+      if (type1 !== type2) return false;
+
+      switch (type1) {
+        case 'undefined':
+        case 'bigint':
+        case 'boolean':
+        case 'number':
+        case 'string':
+        case 'symbol':
+        case 'function':
+          return Object.is(v1, v2);
+        case 'object': {
+          if (v1 === null || v2 === null) return false;
+
+          if (v1.constructor !== v2.constructor) {
+            return false;
+          }
+
+          if (
+            v1 instanceof Boolean ||
+            v1 instanceof Date ||
+            v1 instanceof Number ||
+            v1 instanceof String
+          ) {
+            return _valueOfEq(v1, v2);
+          }
+
+          if (mode !== 'FLAT') {
+            if (Symbol.iterator in v1 && Symbol.iterator in v2) {
+              if (mode === 'SHALLOW') {
+                return createIterableEq(_anyFlatEq)(v1, v2);
+              }
+
+              return createIterableEq(result)(v1, v2);
+            }
+
+            if (mode === 'SHALLOW') {
+              return createObjectEq(_anyFlatEq)(v1, v2);
+            }
+
+            return _objectEq(v1, v2);
+          }
+
+          // cannot establish that they are equal in flat mode
+          return false;
+        }
+      }
+    };
+
+    return result;
+  }
+
+  /**
+   * Returns an Eq instance that checks equality of any values. For composed values (objects and iterables)
+   * it will compare with Object.is.
+   * @typeparam T - the value type
+   * @example
+   * ```ts
+   * const eq = anyFlatEq()
+   * console.log(eq(1, 'a'))
+   * // => false
+   * console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
+   * // => false
+   * ```
+   */
+  export function anyFlatEq<T = any>(): Eq<T> {
+    return _anyFlatEq;
+  }
+
+  /**
+   * Returns an Eq instance that checks equality of any values. For composed values (objects and iterables)
+   * it will enter 1 level, and if again compound values are found, they are compared
+   * with Object.is.
+   * @typeparam T - the value type
+   * @example
+   * ```ts
+   * const eq = anyFlatEq()
+   * console.log(eq(1, 'a'))
+   * // => false
+   * console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
+   * // => true
+   * console.log(eq([{ a: 1, b: 2 }], [{ b: 2, a: 1 }]))
+   * // => false
+   * ```
+   */
+  export function anyShallowEq<T = any>(): Eq<T> {
+    return _anyShallowEq;
+  }
+
+  /**
+   * Returns an Eq instance that checks equality of any values. For composed values (objects and iterables)
+   * it will recursively compare the contained values.
+   * @note may have poor performance for deeply nested types and large arrays, and objects with circular structures
+   * may cause infinite loops
+   * @typeparam T - the value type
+   * @example
+   * ```ts
+   * const eq = anyFlatEq()
+   * console.log(eq(1, 'a'))
+   * // => false
+   * console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
+   * // => true
+   * console.log(eq([{ a: 1, b: 2 }], [{ b: 2, a: 1 }]))
+   * // => false
+   * ```
+   */
+  export function anyDeepEq<T = any>(): Eq<T> {
+    return _anyDeepEq;
+  }
+
+  const _defaultCollator = Intl.Collator('und');
+
+  const _defaultStringCollatorEq: Eq<any> = (v1, v2) =>
+    _defaultCollator.compare(v1, v2) === 0;
+
+  /**
+   * Returns an Eq instance that considers strings equal taking the given or default locale into account.
+   * @param locales - (optional) a locale or list of locales
+   * @param options - (optional) see String.localeCompare for details
+   * @example
+   * ```ts
+   * const eq = Eq.createStringCollatorEq()
+   * console.log(eq('a', 'a'))
+   * // => true
+   * console.log(eq('abc', 'aBc'))
+   * // => false
+   * ```
+   */
+  export function createStringCollatorEq(
+    ...args: ConstructorParameters<typeof Intl.Collator>
+  ): Eq<string> {
+    if (args.length === 0) return _defaultStringCollatorEq;
+
+    const collator = Intl.Collator(...args);
+
+    return (v1, v2) => collator.compare(v1, v2) === 0;
+  }
+
+  const _stringCaseInsensitiveEq: Eq<string> = createStringCollatorEq('und', {
+    sensitivity: 'accent',
+  });
+
+  /**
+   * Returns an Eq instance that considers strings equal regardless of their case.
+   * @example
+   * ```ts
+   * const eq = Eq.stringCaseInsentitiveEq()
+   * console.log(eq('aB', 'Ab'))
+   * // => true
+   * console.log(eq('aBc', 'abB'))
+   * // => false
+   * ```
+   */
+  export function stringCaseInsentitiveEq(): Eq<string> {
+    return _stringCaseInsensitiveEq;
+  }
+
+  const _stringCharCodeEq: Eq<string> = (v1, v2) => {
+    const len = v1.length;
+
+    if (len !== v2.length) return false;
+
+    let i = -1;
+
+    while (++i < len) {
+      if (v1.charCodeAt(i) !== v2.charCodeAt(i)) return false;
+    }
+
+    return true;
+  };
+
+  /**
+   * Returns an Eq instance that considers strings equal when all their charcodes are equal.
+   * @example
+   * ```ts
+   * const eq = Eq.stringCharCodeEq()
+   * console.log(eq('a', 'a'))
+   * // => true
+   * console.log(eq('abc', 'aBc'))
+   * // => false
+   * ```
+   */
+  export function stringCharCodeEq(): Eq<string> {
+    return _stringCharCodeEq;
+  }
+
+  const _anyToStringEq: Eq<any> = (v1, v2) =>
+    convertAnyToString(v1) === convertAnyToString(v2);
+
+  export function anyToStringEq(): Eq<any> {
+    return _anyToStringEq;
+  }
+
+  const _anyJsonEq: Eq<any> = (v1, v2) =>
+    JSON.stringify(v1) === JSON.stringify(v2);
+
+  /**
+   * Returns an Eq instance that considers values equal their JSON.stringify values are equal.
+   * @example
+   * ```ts
+   * const eq = Eq.anyJsonEq()
+   * console.log(eq({ a: 1, b: 2 }, { a: 1, b: 2 }))
+   * // => true
+   * console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
+   * // => false
+   * ```
+   */
+  export function anyJsonEq(): Eq<any> {
+    return _anyJsonEq;
+  }
+
+  /**
+   * Returns an `Eq` instance for tuples that considers two tuples [A, B] and [C, D] equal if [A, B] equals [C, D],
+   * or if [A, B] equals [D, C]
+   * @param eq - (optional) an alternative `Eq` instance to use for the values in the tuple
+   * @example
+   * ```ts
+   * const eq = Eq.tupleSymmetric()
+   * console.log(eq([1, 2], [1, 2]))
+   * // => true
+   * console.log(eq([1, 2], [2, 1]))
+   * // => true
+   * console.log(eq([1, 3], [2, 1]))
+   * // => false
+   * ```
+   */
+  export function tupleSymmetric<T>(
+    eq: Eq<T> = defaultEq()
+  ): Eq<readonly [T, T]> {
+    return (tup1: readonly [T, T], tup2: readonly [T, T]): boolean =>
+      (eq(tup1[0], tup2[0]) && eq(tup1[1], tup2[1])) ||
+      (eq(tup1[0], tup2[1]) && eq(tup1[1], tup2[0]));
+  }
+}

package/src/err.mts

@@ -0,0 +1,43 @@
+/**
+ * Throws an `Err.ForcedError` error when called.
+ * @example
+ * ```ts
+ * const emptyMap = HashMap.empty<number, string>()
+ * emptyMap.get(5, Err);
+ * // throws: Err.CustomError(message: 'Err: forced to throw error')
+ * ```
+ */
+export function Err(): never {
+  return ErrBase.msg('Err: Forced to throw error')();
+}
+
+export namespace ErrBase {
+  /**
+   * A custom error instance.
+   */
+  export abstract class CustomError {
+    constructor(readonly message: string) {}
+
+    get name() {
+      return this.constructor.name;
+    }
+  }
+
+  export class ForcedError extends CustomError {}
+
+  /**
+   * Returns a function that, when called, throws an `Err.ForcedError` with the given `message` string.
+   * @param message - the message to put in the `Err.ForcedError` instance.
+   * @example
+   * ```ts
+   * const emptyMap = HashMap.empty<number, string>()
+   * emptyMap.get(5, ErrBase.msg('not found'));
+   * // throws: Err.CustomError(message: 'not found')
+   * ```
+   */
+  export function msg(message: string): () => never {
+    return function (): never {
+      throw new ErrBase.ForcedError(message);
+    };
+  }
+}

package/src/index-range.mts

@@ -0,0 +1,120 @@
+import type { Range } from './internal.mjs';
+
+/**
+ * A flexible range specification for numeric indices.
+ * If a start or end is defined, a tuple can be used where the second item is a boolean
+ * indicating whether that end is inclusive or exclusive.<br/>
+ * An IndexRange can have one of the following forms:<br/>
+ * <br/>
+ * - { amount: number }<br/>
+ * - { start: number }<br/>
+ * - { start: number, amount: number }<br/>
+ * - { start: number, end: number }<br/>
+ * - { start: number, end: [number, boolean] }<br/>
+ * - { start: [number, boolean] }<br/>
+ * - { start: [number, boolean], amount: number }<br/>
+ * - { start: [number, boolean], end: number }<br/>
+ * - { start: [number, boolean], end: [number, boolean] }<br/>
+ * - { end: number }<br/>
+ * - { end: [number, boolean] }<br/>
+ */
+export type IndexRange =
+  | { amount: number; start?: number | [number, boolean]; end?: undefined }
+  | Range<number>;
+
+export namespace IndexRange {
+  /**
+   * Returns, given the `range` `IndexRange`, a normalized tuple containing the
+   * start index, and optionally an end index.
+   * @param range - the `IndexRange` to use
+   */
+  export function getIndexRangeIndices(
+    range: IndexRange
+  ): [number, number | undefined] {
+    if (undefined !== range.amount) {
+      if (undefined === range.start) return [0, range.amount - 1];
+
+      if (Array.isArray(range.start)) {
+        const [start, includeStart] = range.start;
+        if (includeStart) return [start, start + range.amount - 1];
+        return [start + 1, start + 1 + range.amount - 1];
+      }
+      return [range.start, range.start + range.amount - 1];
+    }
+
+    let start = 0;
+    let end: number | undefined = undefined;
+
+    if (`start` in range) {
+      if (Array.isArray(range.start)) {
+        if (range.start[1]) start = range.start[0];
+        else start = range.start[0] + 1;
+      } else start = range.start ?? 0;
+    }
+
+    if (`end` in range) {
+      if (Array.isArray(range.end)) {
+        if (range.end[1]) end = range.end[0];
+        else end = range.end[0] - 1;
+      } else end = range.end;
+    }
+
+    return [start, end];
+  }
+
+  /**
+   * Returns, given the `range` `IndexRange`, and a target maximum `length`, the actual index range.
+   * This can be one of three options:
+   * - 'empty': there are no elements within the range
+   * - 'all': all elements are within the range
+   * - [start: number, end: number]: an inclusive range of element indices within the given range
+   * @param range - the `IndexRange` to use
+   * @param length - the target maximum length
+   */
+  export function getIndicesFor(
+    range: IndexRange,
+    length: number
+  ): [number, number] | 'empty' | 'all' {
+    if (length <= 0) return 'empty';
+
+    let start = 0;
+    let end = length - 1;
+
+    if (undefined !== range.start) {
+      if (Array.isArray(range.start)) {
+        start = range.start[0];
+        if (!range.start[1]) start++;
+      } else start = range.start;
+
+      if (start >= length || -start > length) return 'empty';
+      if (start < 0) start = length + start;
+    }
+
+    if (undefined !== range.amount) {
+      if (range.amount <= 0) return 'empty';
+      if (undefined === range.start) {
+        if (range.amount >= length) return 'all';
+        return [0, Math.min(end, range.amount - 1)];
+      }
+
+      end = start + range.amount - 1;
+    } else if (undefined !== range.end) {
+      if (Array.isArray(range.end)) {
+        end = range.end[0];
+        if (!range.end[1]) {
+          if (end === 0) return 'empty';
+          end--;
+        }
+      } else end = range.end;
+
+      if (end < 0) end = length + end;
+    }
+
+    if (end < start) return 'empty';
+    end = Math.min(length - 1, end);
+
+    if (start === 0 && end === length - 1) return 'all';
+
+    return [start, end];
+  }
+}

package/{dist/module/index.js → src/index.mts}

@@ -3,5 +3,5 @@
  *
  * The `@rimbu/common` package provides many commonly used types and utilities that can also be of use to Rimbu users.<br/>
  */
-export * from './internal';
-//# sourceMappingURL=index.js.map
+
+export * from './internal.mjs';

package/src/internal.mts

@@ -0,0 +1,13 @@
+export * from './collect.mjs';
+export * from './comp.mjs';
+export * from './eq.mjs';
+export * from './err.mjs';
+export * from './index-range.mjs';
+export * from './optlazy.mjs';
+export * from './range.mjs';
+export * from './reducer.mjs';
+export * from './traverse-state.mjs';
+export * from './types.mjs';
+export * from './update.mjs';
+export * from './async-optlazy.mjs';
+export * from './async-reducer.mjs';

package/{dist/main/optlazy.js → src/optlazy.mts}

@@ -1,6 +1,9 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OptLazyOr = exports.OptLazy = void 0;
+/**
+ * A potentially lazy value of type T.
+ * @typeparam T - the value type
+ */
+export type OptLazy<T> = T | (() => T);
+
 /**
  * Returns the value contained in an `OptLazy` instance of type T.
  * @param optLazy - the `OptLazy` value of type T
@@ -11,12 +14,19 @@ exports.OptLazyOr = exports.OptLazy = void 0;
  * OptLazy(() => () => 1)  // => () => 1
  * ```
  */
-function OptLazy(optLazy) {
-    if (optLazy instanceof Function)
-        return optLazy();
-    return optLazy;
+export function OptLazy<T>(optLazy: OptLazy<T>): T {
+  if (optLazy instanceof Function) return optLazy();
+  return optLazy;
 }
-exports.OptLazy = OptLazy;
+
+/**
+ * A potentially lazy value that, in case of a lazy function, received a default value
+ * that it can return.
+ * @typeparam T - the value type
+ * @typeparam O - the default value type
+ */
+export type OptLazyOr<T, O> = T | ((none: O) => T | O);
+
 /**
  * Returns the value contained in an `OptLazyOr` instance of type T, or the given
  * `otherValue` if the lazy function returns it.
@@ -29,10 +39,10 @@ exports.OptLazy = OptLazy;
  * OptLazyOr((none) => none, 'a')  // => 'a'
  * ```
  */
-function OptLazyOr(optLazyOr, otherValue) {
-    if (optLazyOr instanceof Function)
-        return optLazyOr(otherValue);
-    return optLazyOr;
+export function OptLazyOr<T, O>(
+  optLazyOr: OptLazyOr<T, O>,
+  otherValue: O
+): T | O {
+  if (optLazyOr instanceof Function) return optLazyOr(otherValue);
+  return optLazyOr;
 }
-exports.OptLazyOr = OptLazyOr;
-//# sourceMappingURL=optlazy.js.map

package/src/range.mts

@@ -0,0 +1,58 @@
+/**
+ * A range definition for any type of (orderable) value.
+ * If a start or end is defined, a tuple can be used where the second item is a boolean
+ * indicating whether that end is inclusive (true) or exclusive (false).<br/>
+ * A Range of type T can have one of the following forms:<br/>
+ * <br/>
+ * - { end: T }<br/>
+ * - { end: [T, boolean] }<br/>
+ * - { start: T }<br/>
+ * - { start: T, end: T }<br/>
+ * - { start: T, end: [T, boolean] }<br/>
+ * - { start: [T, boolean] }<br/>
+ * - { start: [T, boolean], end: T }<br/>
+ * - { start: [T, boolean], end: [T, boolean] }<br/>
+ */
+export type Range<T> =
+  | { start: T | [T, boolean]; end?: T | [T, boolean]; amount?: undefined }
+  | { start?: T | [T, boolean]; end: T | [T, boolean]; amount?: undefined };
+
+export namespace Range {
+  /**
+   * Simplifies a given `range` `Range` input for easier processing, by returning optional
+   * start and end ranges including whether they are inclusive or exclusive
+   * @param range - the `Range` to use
+   */
+  export function getNormalizedRange<T>(range: Range<T>): {
+    start?: [T, boolean] | undefined;
+    end?: [T, boolean] | undefined;
+  } {
+    let start: [T, boolean] | undefined = undefined;
+    let end: [T, boolean] | undefined = undefined;
+
+    if (`start` in range && undefined !== range.start) {
+      if (
+        Array.isArray(range.start) &&
+        range.start.length === 2 &&
+        typeof range.start[1] === 'boolean'
+      ) {
+        start = range.start;
+      } else {
+        start = [range.start as T, true];
+      }
+    }
+    if (`end` in range && undefined !== range.end) {
+      if (
+        Array.isArray(range.end) &&
+        range.end.length === 2 &&
+        typeof range.end[1] === 'boolean'
+      ) {
+        end = range.end;
+      } else {
+        end = [range.end as T, true];
+      }
+    }
+
+    return { start, end };
+  }
+}