@rimbu/common 0.8.2 → 0.9.2

package/dist/types/comp.d.ts

@@ -10,6 +10,7 @@ export interface Comp<K> {
      * @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
@@ -17,17 +18,20 @@ export interface Comp<K> {
      * // => -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;
 }
@@ -39,19 +43,23 @@ export declare namespace Comp {
     /**
      * Returns a default number Comp instance that orders numbers naturally.
      * @example
+     * ```ts
      * const c = Comp.numberComp();
      * console.log(c.compare(3, 5))
      * // => -2
+     * ```
      */
     function numberComp(): Comp<number>;
     /**
      * 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
+     * ```
      */
     function booleanComp(): Comp<boolean>;
     /**
@@ -98,23 +106,27 @@ export declare namespace Comp {
      * 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
+     * ```
      */
     function iterableComp<T>(itemComp?: Comp<T>): Comp<Iterable<T>>;
     /**
      * 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:
-     * - starting with the smallest key of either object:
-     *   - if only one of the objects has the key, the object with the key is considered to be larger than the other
-     *   - if both objects have the key, the values are compared with `valueComp`. If the values are not equal, this result is returned.
-     * - if the objects have the same keys with the same values, they are considered equal
+     * 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
@@ -126,6 +138,7 @@ export declare namespace Comp {
      * // => true
      * console.log(c.compare({ a: 1, b: 2 }, { b: 2, a: 1 }))
      * // => 0
+     * ```
      */
     function objectComp(options?: {
         keyComp?: Comp<any>;
@@ -135,22 +148,26 @@ export declare namespace Comp {
      * 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.
+     * ```
      */
     function anyFlatComp<T>(): Comp<T>;
     /**
      * 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.
+     * ```
      */
     function anyShallowComp<T>(): Comp<T>;
     /**
@@ -158,11 +175,13 @@ export declare namespace Comp {
      * 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
+     * ```
      */
     function anyDeepComp<T>(): Comp<T>;
     /**
@@ -170,11 +189,13 @@ export declare namespace Comp {
      * 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
+     * ```
      */
     function withUndefined<T>(comp: Comp<T>): Comp<T | undefined>;
     /**
@@ -182,31 +203,37 @@ export declare namespace Comp {
      * 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
+     * ```
      */
     function withNull<T>(comp: Comp<T>): Comp<T | null>;
     /**
      * 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
+     * ```
      */
     function invert<T>(comp: Comp<T>): Comp<T>;
     /**
      * 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
+     * ```
      */
     function toEq<T>(comp: Comp<T>): Eq<T>;
 }

package/dist/types/eq.d.ts

@@ -11,11 +11,13 @@ export declare namespace Eq {
     /**
      * 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
+     * ```
      */
     const objectIs: Eq<any>;
     /**
@@ -23,11 +25,13 @@ export declare namespace Eq {
      * @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
+     * ```
      */
     function valueOfEq<T extends {
         valueOf(): V;
@@ -35,11 +39,13 @@ export declare namespace Eq {
     /**
      * 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
+     * ```
      */
     function dateEq(): Eq<Date>;
     /**
@@ -47,11 +53,13 @@ export declare namespace Eq {
      * @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
+     * ```
      */
     function iterableEq<T>(itemEq?: Eq<T>): Eq<Iterable<T>>;
     /**
@@ -60,11 +68,13 @@ export declare namespace Eq {
      * @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
+     * ```
      */
     function objectEq<V = any>(valueEq?: Eq<V>): Eq<Record<any, V>>;
     /**
@@ -72,11 +82,13 @@ export declare namespace Eq {
      * 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
+     * ```
      */
     function anyFlatEq<T = any>(): Eq<T>;
     /**
@@ -85,6 +97,7 @@ export declare namespace Eq {
      * with Object.is.
      * @typeparam T - the value type
      * @example
+     * ```ts
      * const eq = anyFlatEq()
      * console.log(eq(1, 'a'))
      * // => false
@@ -92,6 +105,7 @@ export declare namespace Eq {
      * // => true
      * console.log(eq([{ a: 1, b: 2 }], [{ b: 2, a: 1 }]))
      * // => false
+     * ```
      */
     function anyShallowEq<T = any>(): Eq<T>;
     /**
@@ -101,6 +115,7 @@ export declare namespace Eq {
      * may cause infinite loops
      * @typeparam T - the value type
      * @example
+     * ```ts
      * const eq = anyFlatEq()
      * console.log(eq(1, 'a'))
      * // => false
@@ -108,6 +123,7 @@ export declare namespace Eq {
      * // => true
      * console.log(eq([{ a: 1, b: 2 }], [{ b: 2, a: 1 }]))
      * // => false
+     * ```
      */
     function anyDeepEq<T = any>(): Eq<T>;
     /**
@@ -115,42 +131,50 @@ export declare namespace Eq {
      * @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
+     * ```
      */
     function createStringCollatorEq(...args: ConstructorParameters<typeof Intl.Collator>): Eq<string>;
     /**
      * 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
+     * ```
      */
     function stringCaseInsentitiveEq(): Eq<string>;
     /**
      * 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
+     * ```
      */
     function stringCharCodeEq(): Eq<string>;
     function anyToStringEq(): Eq<any>;
     /**
      * 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
+     * ```
      */
     function anyJsonEq(): Eq<any>;
     /**
@@ -158,6 +182,7 @@ export declare namespace Eq {
      * 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
@@ -165,6 +190,7 @@ export declare namespace Eq {
      * // => true
      * console.log(eq([1, 3], [2, 1]))
      * // => false
+     * ```
      */
     function tupleSymmetric<T>(eq?: Eq<T>): Eq<readonly [T, T]>;
 }

package/dist/types/err.d.ts

@@ -1,9 +1,11 @@
 /**
  * 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 declare function Err(): never;
 export declare namespace ErrBase {

package/dist/types/index-range.d.ts

@@ -2,19 +2,20 @@ import type { Range } from './internal';
 /**
  * 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.
- * An IndexRange can have one of the following forms:
- * - { amount: number }
- * - { start: number }
- * - { start: number, amount: number }
- * - { start: number, end: number }
- * - { start: number, end: [number, boolean] }
- * - { start: [number, boolean] }
- * - { start: [number, boolean], amount: number }
- * - { start: [number, boolean], end: number }
- * - { start: [number, boolean], end: [number, boolean] }
- * - { end: number }
- * - { end: [number, 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 declare type IndexRange = {
     amount: number;

package/dist/types/index.d.ts

@@ -1 +1,6 @@
+/**
+ * @packageDocumentation
+ *
+ * The `@rimbu/common` package provides many commonly used types and utilities that can also be of use to Rimbu users.<br/>
+ */
 export * from './internal';

package/dist/types/optlazy.d.ts

@@ -7,9 +7,11 @@ export declare type OptLazy<T> = T | (() => T);
  * Returns the value contained in an `OptLazy` instance of type T.
  * @param optLazy - the `OptLazy` value of type T
  * @example
+ * ```ts
  * OptLazy(1)              // => 1
  * OptLazy(() => 1)        // => 1
  * OptLazy(() => () => 1)  // => () => 1
+ * ```
  */
 export declare function OptLazy<T>(optLazy: OptLazy<T>): T;
 /**
@@ -25,8 +27,10 @@ export declare type OptLazyOr<T, O> = T | ((none: O) => T | O);
  * @param optLazyOr - a value or a function returning a value or otherwise the received value
  * @param otherValue - the value to return if the optLazyOr does not return its own value
  * @example
+ * ```ts
  * OptLazyOr(1, 'a')               // => 1
  * OptLazyOr(() => 1, 'a')         // => 1
  * OptLazyOr((none) => none, 'a')  // => 'a'
+ * ```
  */
 export declare function OptLazyOr<T, O>(optLazyOr: OptLazyOr<T, O>, otherValue: O): T | O;

package/dist/types/range.d.ts

@@ -1,16 +1,17 @@
 /**
  * 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 or exclusive.
- * An Range of type T can have one of the following forms:
- * - { end: T }
- * - { end: [T, boolean] }
- * - { start: T }
- * - { start: T, end: T }
- * - { start: T, end: [T, boolean] }
- * - { start: [T, boolean] }
- * - { start: [T, boolean], end: T }
- * - { start: [T, boolean], end: [T, 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 declare type Range<T> = {
     start: T | [T, boolean];