data-structure-typed 1.52.4 → 1.52.5

package/dist/mjs/types/utils/utils.d.ts

@@ -1,17 +1,18 @@
-export type ToThunkFn = () => ReturnType<TrlFn>;
-export type Thunk = () => ReturnType<ToThunkFn> & {
-    __THUNK__: symbol;
+export type ToThunkFn<R = any> = () => R;
+export type Thunk<R = any> = ToThunkFn<R> & {
+    __THUNK__?: symbol;
 };
-export type TrlFn = (...args: any[]) => any;
+export type TrlFn<A extends any[] = any[], R = any> = (...args: A) => R;
 export type TrlAsyncFn = (...args: any[]) => any;
 export type SpecifyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 export type Any = string | number | bigint | boolean | symbol | undefined | object;
-export type Comparable = number | string | bigint | boolean | ({
+export type ComparablePrimitive = number | bigint | string | boolean;
+export type ComparableObject = {
     [key in string]: any;
-} & {
-    valueOf(): Comparable;
-}) | ({
-    [key in string]: any;
-} & {
-    toString(): Comparable;
-}) | (() => Comparable);
+} & ({
+    valueOf: () => ComparablePrimitive | ComparableObject;
+    toString?: () => string;
+} | {
+    toString: () => string;
+});
+export type Comparable = ComparablePrimitive | Date | ComparableObject;

package/dist/mjs/utils/number.d.ts

@@ -1 +1,14 @@
+/**
+ * The function `toBinaryString` converts a number to a binary string representation with a specified
+ * number of digits.
+ * @param {number} num - The `num` parameter in the `toBinaryString` function represents the number
+ * that you want to convert to a binary string.
+ * @param [digit=32] - The `digit` parameter in the `toBinaryString` function represents the number of
+ * digits the binary string should have. By default, it is set to 32, meaning that the binary string
+ * will be padded with zeros at the beginning to ensure it is 32 bits long. You can provide a
+ * @returns The function `toBinaryString` takes a number as input and converts it to a binary string
+ * representation with a specified number of digits (default is 32). The binary string is padded with
+ * zeros at the beginning to ensure it has the specified number of digits. The function returns the
+ * binary string representation of the input number.
+ */
 export declare function toBinaryString(num: number, digit?: number): string;

package/dist/mjs/utils/number.js

@@ -1,3 +1,16 @@
+/**
+ * The function `toBinaryString` converts a number to a binary string representation with a specified
+ * number of digits.
+ * @param {number} num - The `num` parameter in the `toBinaryString` function represents the number
+ * that you want to convert to a binary string.
+ * @param [digit=32] - The `digit` parameter in the `toBinaryString` function represents the number of
+ * digits the binary string should have. By default, it is set to 32, meaning that the binary string
+ * will be padded with zeros at the beginning to ensure it is 32 bits long. You can provide a
+ * @returns The function `toBinaryString` takes a number as input and converts it to a binary string
+ * representation with a specified number of digits (default is 32). The binary string is padded with
+ * zeros at the beginning to ensure it has the specified number of digits. The function returns the
+ * binary string representation of the input number.
+ */
 export function toBinaryString(num, digit = 32) {
     // Convert number to binary string
     let binaryString = (num >>> 0).toString(2); // Use the unsigned right shift operator to ensure you get a binary representation of a 32-bit unsigned integer

package/dist/mjs/utils/utils.d.ts

@@ -6,21 +6,143 @@
  * @license MIT License
  */
 import type { Comparable, Thunk, ToThunkFn, TrlAsyncFn, TrlFn } from '../types';
+/**
+ * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
+ * @returns A randomly generated UUID (Universally Unique Identifier) in the format
+ * 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' where each 'x' is replaced with a random hexadecimal
+ * character.
+ */
 export declare const uuidV4: () => string;
+/**
+ * The `arrayRemove` function removes elements from an array based on a specified predicate function
+ * and returns the removed elements.
+ * @param {T[]} array - An array of elements that you want to filter based on the provided predicate
+ * function.
+ * @param predicate - The `predicate` parameter is a function that takes three arguments:
+ * @returns The `arrayRemove` function returns an array containing the elements that satisfy the given
+ * `predicate` function.
+ */
 export declare const arrayRemove: <T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean) => T[];
 export declare const THUNK_SYMBOL: unique symbol;
+/**
+ * The function `isThunk` checks if a given value is a function with a specific symbol property.
+ * @param {any} fnOrValue - The `fnOrValue` parameter in the `isThunk` function can be either a
+ * function or a value that you want to check if it is a thunk. Thunks are functions that are wrapped
+ * around a value or computation for lazy evaluation. The function checks if the `fnOrValue` is
+ * @returns The function `isThunk` is checking if the input `fnOrValue` is a function and if it has a
+ * property `__THUNK__` equal to `THUNK_SYMBOL`. The return value will be `true` if both conditions are
+ * met, otherwise it will be `false`.
+ */
 export declare const isThunk: (fnOrValue: any) => boolean;
+/**
+ * The `toThunk` function in TypeScript converts a function into a thunk by wrapping it in a closure.
+ * @param {ToThunkFn} fn - `fn` is a function that will be converted into a thunk.
+ * @returns A thunk function is being returned. Thunk functions are functions that delay the evaluation
+ * of an expression or operation until it is explicitly called or invoked. In this case, the `toThunk`
+ * function takes a function `fn` as an argument and returns a thunk function that, when called, will
+ * execute the `fn` function provided as an argument.
+ */
 export declare const toThunk: (fn: ToThunkFn) => Thunk;
+/**
+ * The `trampoline` function in TypeScript enables tail call optimization by using thunks to avoid
+ * stack overflow.
+ * @param {TrlFn} fn - The `fn` parameter in the `trampoline` function is a function that takes any
+ * number of arguments and returns a value.
+ * @returns The `trampoline` function returns an object with two properties:
+ * 1. A function that executes the provided function `fn` and continues to execute any thunks returned
+ * by `fn` until a non-thunk value is returned.
+ * 2. A `cont` property that is a function which creates a thunk for the provided function `fn`.
+ */
 export declare const trampoline: (fn: TrlFn) => ((...args: [...Parameters<TrlFn>]) => any) & {
-    cont: (...args: [...Parameters<TrlFn>]) => Thunk;
+    cont: (...args: [...Parameters<TrlFn>]) => ReturnType<TrlFn>;
 };
+/**
+ * The `trampolineAsync` function in TypeScript allows for asynchronous trampolining of a given
+ * function.
+ * @param {TrlAsyncFn} fn - The `fn` parameter in the `trampolineAsync` function is expected to be a
+ * function that returns a Promise. This function will be called recursively until a non-thunk value is
+ * returned.
+ * @returns The `trampolineAsync` function returns an object with two properties:
+ * 1. An async function that executes the provided `TrlAsyncFn` function and continues to execute any
+ * thunks returned by the function until a non-thunk value is returned.
+ * 2. A `cont` property that is a function which wraps the provided `TrlAsyncFn` function in a thunk
+ * and returns it.
+ */
 export declare const trampolineAsync: (fn: TrlAsyncFn) => ((...args: [...Parameters<TrlAsyncFn>]) => Promise<any>) & {
-    cont: (...args: [...Parameters<TrlAsyncFn>]) => Thunk;
+    cont: (...args: [...Parameters<TrlAsyncFn>]) => ReturnType<TrlAsyncFn>;
 };
+/**
+ * The function `getMSB` returns the most significant bit of a given number.
+ * @param {number} value - The `value` parameter is a number for which we want to find the position of
+ * the Most Significant Bit (MSB). The function `getMSB` takes this number as input and calculates the
+ * position of the MSB in its binary representation.
+ * @returns The function `getMSB` returns the most significant bit (MSB) of the input `value`. If the
+ * input value is less than or equal to 0, it returns 0. Otherwise, it calculates the position of the
+ * MSB using the `Math.clz32` function and bitwise left shifts 1 to that position.
+ */
 export declare const getMSB: (value: number) => number;
+/**
+ * The `rangeCheck` function in TypeScript is used to validate if an index is within a specified range
+ * and throws a `RangeError` with a custom message if it is out of bounds.
+ * @param {number} index - The `index` parameter represents the value that you want to check if it
+ * falls within a specified range.
+ * @param {number} min - The `min` parameter represents the minimum value that the `index` should be
+ * compared against in the `rangeCheck` function.
+ * @param {number} max - The `max` parameter in the `rangeCheck` function represents the maximum value
+ * that the `index` parameter is allowed to have. If the `index` is greater than this `max` value, a
+ * `RangeError` will be thrown.
+ * @param [message=Index out of bounds.] - The `message` parameter is a string that represents the
+ * error message to be thrown if the index is out of bounds. By default, if no message is provided when
+ * calling the `rangeCheck` function, the message "Index out of bounds." will be used.
+ */
 export declare const rangeCheck: (index: number, min: number, max: number, message?: string) => void;
+/**
+ * The function `throwRangeError` throws a RangeError with a custom message if called.
+ * @param [message=The value is off-limits.] - The `message` parameter is a string that represents the
+ * error message to be displayed when a `RangeError` is thrown. If no message is provided, the default
+ * message is 'The value is off-limits.'.
+ */
 export declare const throwRangeError: (message?: string) => void;
+/**
+ * The function `isWeakKey` checks if the input is an object or a function in TypeScript.
+ * @param {unknown} input - The `input` parameter in the `isWeakKey` function is of type `unknown`,
+ * which means it can be any type. The function checks if the `input` is an object (excluding `null`)
+ * or a function, and returns a boolean indicating whether the `input` is a weak
+ * @returns The function `isWeakKey` returns a boolean value indicating whether the input is an object
+ * or a function.
+ */
 export declare const isWeakKey: (input: unknown) => input is object;
+/**
+ * The function `calcMinUnitsRequired` calculates the minimum number of units required to accommodate a
+ * given total quantity based on a specified unit size.
+ * @param {number} totalQuantity - The `totalQuantity` parameter represents the total quantity of items
+ * that need to be processed or handled.
+ * @param {number} unitSize - The `unitSize` parameter represents the size of each unit or package. It
+ * is used in the `calcMinUnitsRequired` function to calculate the minimum number of units required to
+ * accommodate a total quantity of items.
+ */
 export declare const calcMinUnitsRequired: (totalQuantity: number, unitSize: number) => number;
+/**
+ * The `roundFixed` function in TypeScript rounds a number to a specified number of decimal places.
+ * @param {number} num - The `num` parameter is a number that you want to round to a certain number of
+ * decimal places.
+ * @param {number} [digit=10] - The `digit` parameter in the `roundFixed` function specifies the number
+ * of decimal places to round the number to. By default, it is set to 10 if not provided explicitly.
+ * @returns The function `roundFixed` returns a number that is rounded to the specified number of
+ * decimal places (default is 10 decimal places).
+ */
 export declare const roundFixed: (num: number, digit?: number) => number;
-export declare function isComparable(key: any): key is Comparable;
+/**
+ * The function `isComparable` in TypeScript checks if a value is comparable, handling primitive values
+ * and objects with optional force comparison.
+ * @param {unknown} value - The `value` parameter in the `isComparable` function represents the value
+ * that you want to check if it is comparable. It can be of any type (`unknown`), and the function will
+ * determine if it is comparable based on certain conditions.
+ * @param [isForceObjectComparable=false] - The `isForceObjectComparable` parameter in the
+ * `isComparable` function is a boolean flag that determines whether to treat non-primitive values as
+ * comparable objects. When set to `true`, it forces the function to consider non-primitive values as
+ * comparable objects, regardless of their type.
+ * @returns The function `isComparable` returns a boolean value indicating whether the `value` is
+ * considered comparable or not.
+ */
+export declare function isComparable(value: unknown, isForceObjectComparable?: boolean): value is Comparable;

package/dist/mjs/utils/utils.js

@@ -1,9 +1,24 @@
+/**
+ * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
+ * @returns A randomly generated UUID (Universally Unique Identifier) in the format
+ * 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' where each 'x' is replaced with a random hexadecimal
+ * character.
+ */
 export const uuidV4 = function () {
     return 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.replace(/[x]/g, function (c) {
         const r = (Math.random() * 16) | 0, v = c == 'x' ? r : (r & 0x3) | 0x8;
         return v.toString(16);
     });
 };
+/**
+ * The `arrayRemove` function removes elements from an array based on a specified predicate function
+ * and returns the removed elements.
+ * @param {T[]} array - An array of elements that you want to filter based on the provided predicate
+ * function.
+ * @param predicate - The `predicate` parameter is a function that takes three arguments:
+ * @returns The `arrayRemove` function returns an array containing the elements that satisfy the given
+ * `predicate` function.
+ */
 export const arrayRemove = function (array, predicate) {
     let i = -1, len = array ? array.length : 0;
     const result = [];
@@ -18,14 +33,41 @@ export const arrayRemove = function (array, predicate) {
     return result;
 };
 export const THUNK_SYMBOL = Symbol('thunk');
+/**
+ * The function `isThunk` checks if a given value is a function with a specific symbol property.
+ * @param {any} fnOrValue - The `fnOrValue` parameter in the `isThunk` function can be either a
+ * function or a value that you want to check if it is a thunk. Thunks are functions that are wrapped
+ * around a value or computation for lazy evaluation. The function checks if the `fnOrValue` is
+ * @returns The function `isThunk` is checking if the input `fnOrValue` is a function and if it has a
+ * property `__THUNK__` equal to `THUNK_SYMBOL`. The return value will be `true` if both conditions are
+ * met, otherwise it will be `false`.
+ */
 export const isThunk = (fnOrValue) => {
     return typeof fnOrValue === 'function' && fnOrValue.__THUNK__ === THUNK_SYMBOL;
 };
+/**
+ * The `toThunk` function in TypeScript converts a function into a thunk by wrapping it in a closure.
+ * @param {ToThunkFn} fn - `fn` is a function that will be converted into a thunk.
+ * @returns A thunk function is being returned. Thunk functions are functions that delay the evaluation
+ * of an expression or operation until it is explicitly called or invoked. In this case, the `toThunk`
+ * function takes a function `fn` as an argument and returns a thunk function that, when called, will
+ * execute the `fn` function provided as an argument.
+ */
 export const toThunk = (fn) => {
     const thunk = () => fn();
     thunk.__THUNK__ = THUNK_SYMBOL;
     return thunk;
 };
+/**
+ * The `trampoline` function in TypeScript enables tail call optimization by using thunks to avoid
+ * stack overflow.
+ * @param {TrlFn} fn - The `fn` parameter in the `trampoline` function is a function that takes any
+ * number of arguments and returns a value.
+ * @returns The `trampoline` function returns an object with two properties:
+ * 1. A function that executes the provided function `fn` and continues to execute any thunks returned
+ * by `fn` until a non-thunk value is returned.
+ * 2. A `cont` property that is a function which creates a thunk for the provided function `fn`.
+ */
 export const trampoline = (fn) => {
     const cont = (...args) => toThunk(() => fn(...args));
     return Object.assign((...args) => {
@@ -36,6 +78,18 @@ export const trampoline = (fn) => {
         return result;
     }, { cont });
 };
+/**
+ * The `trampolineAsync` function in TypeScript allows for asynchronous trampolining of a given
+ * function.
+ * @param {TrlAsyncFn} fn - The `fn` parameter in the `trampolineAsync` function is expected to be a
+ * function that returns a Promise. This function will be called recursively until a non-thunk value is
+ * returned.
+ * @returns The `trampolineAsync` function returns an object with two properties:
+ * 1. An async function that executes the provided `TrlAsyncFn` function and continues to execute any
+ * thunks returned by the function until a non-thunk value is returned.
+ * 2. A `cont` property that is a function which wraps the provided `TrlAsyncFn` function in a thunk
+ * and returns it.
+ */
 export const trampolineAsync = (fn) => {
     const cont = (...args) => toThunk(() => fn(...args));
     return Object.assign(async (...args) => {
@@ -46,50 +100,152 @@ export const trampolineAsync = (fn) => {
         return result;
     }, { cont });
 };
+/**
+ * The function `getMSB` returns the most significant bit of a given number.
+ * @param {number} value - The `value` parameter is a number for which we want to find the position of
+ * the Most Significant Bit (MSB). The function `getMSB` takes this number as input and calculates the
+ * position of the MSB in its binary representation.
+ * @returns The function `getMSB` returns the most significant bit (MSB) of the input `value`. If the
+ * input value is less than or equal to 0, it returns 0. Otherwise, it calculates the position of the
+ * MSB using the `Math.clz32` function and bitwise left shifts 1 to that position.
+ */
 export const getMSB = (value) => {
     if (value <= 0) {
         return 0;
     }
     return 1 << (31 - Math.clz32(value));
 };
+/**
+ * The `rangeCheck` function in TypeScript is used to validate if an index is within a specified range
+ * and throws a `RangeError` with a custom message if it is out of bounds.
+ * @param {number} index - The `index` parameter represents the value that you want to check if it
+ * falls within a specified range.
+ * @param {number} min - The `min` parameter represents the minimum value that the `index` should be
+ * compared against in the `rangeCheck` function.
+ * @param {number} max - The `max` parameter in the `rangeCheck` function represents the maximum value
+ * that the `index` parameter is allowed to have. If the `index` is greater than this `max` value, a
+ * `RangeError` will be thrown.
+ * @param [message=Index out of bounds.] - The `message` parameter is a string that represents the
+ * error message to be thrown if the index is out of bounds. By default, if no message is provided when
+ * calling the `rangeCheck` function, the message "Index out of bounds." will be used.
+ */
 export const rangeCheck = (index, min, max, message = 'Index out of bounds.') => {
     if (index < min || index > max)
         throw new RangeError(message);
 };
+/**
+ * The function `throwRangeError` throws a RangeError with a custom message if called.
+ * @param [message=The value is off-limits.] - The `message` parameter is a string that represents the
+ * error message to be displayed when a `RangeError` is thrown. If no message is provided, the default
+ * message is 'The value is off-limits.'.
+ */
 export const throwRangeError = (message = 'The value is off-limits.') => {
     throw new RangeError(message);
 };
+/**
+ * The function `isWeakKey` checks if the input is an object or a function in TypeScript.
+ * @param {unknown} input - The `input` parameter in the `isWeakKey` function is of type `unknown`,
+ * which means it can be any type. The function checks if the `input` is an object (excluding `null`)
+ * or a function, and returns a boolean indicating whether the `input` is a weak
+ * @returns The function `isWeakKey` returns a boolean value indicating whether the input is an object
+ * or a function.
+ */
 export const isWeakKey = (input) => {
     const inputType = typeof input;
     return (inputType === 'object' && input !== null) || inputType === 'function';
 };
+/**
+ * The function `calcMinUnitsRequired` calculates the minimum number of units required to accommodate a
+ * given total quantity based on a specified unit size.
+ * @param {number} totalQuantity - The `totalQuantity` parameter represents the total quantity of items
+ * that need to be processed or handled.
+ * @param {number} unitSize - The `unitSize` parameter represents the size of each unit or package. It
+ * is used in the `calcMinUnitsRequired` function to calculate the minimum number of units required to
+ * accommodate a total quantity of items.
+ */
 export const calcMinUnitsRequired = (totalQuantity, unitSize) => Math.floor((totalQuantity + unitSize - 1) / unitSize);
+/**
+ * The `roundFixed` function in TypeScript rounds a number to a specified number of decimal places.
+ * @param {number} num - The `num` parameter is a number that you want to round to a certain number of
+ * decimal places.
+ * @param {number} [digit=10] - The `digit` parameter in the `roundFixed` function specifies the number
+ * of decimal places to round the number to. By default, it is set to 10 if not provided explicitly.
+ * @returns The function `roundFixed` returns a number that is rounded to the specified number of
+ * decimal places (default is 10 decimal places).
+ */
 export const roundFixed = (num, digit = 10) => {
     const multiplier = Math.pow(10, digit);
     return Math.round(num * multiplier) / multiplier;
 };
-export function isComparable(key) {
-    const keyType = typeof key;
-    if (keyType === 'number')
-        return !isNaN(key);
-    if (keyType === 'string')
-        return true;
-    if (keyType === 'bigint')
-        return true;
-    if (keyType === 'boolean')
-        return true;
-    if (keyType === 'symbol')
+/**
+ * The function `isPrimitiveComparable` checks if a value is a primitive type that can be compared.
+ * @param {unknown} value - The `value` parameter in the `isPrimitiveComparable` function is of type
+ * `unknown`, which means it can be any type. The function checks if the `value` is a primitive type
+ * that can be compared, such as number, bigint, string, or boolean.
+ * @returns The function `isPrimitiveComparable` returns a boolean value indicating whether the input
+ * `value` is a primitive value that can be compared using standard comparison operators (<, >, <=,
+ * >=).
+ */
+function isPrimitiveComparable(value) {
+    const valueType = typeof value;
+    if (valueType === 'number')
+        return !Number.isNaN(value);
+    return valueType === 'bigint' || valueType === 'string' || valueType === 'boolean';
+}
+/**
+ * The function `tryObjectToPrimitive` attempts to convert an object to a comparable primitive value by
+ * first checking the `valueOf` method and then the `toString` method.
+ * @param {object} obj - The `obj` parameter in the `tryObjectToPrimitive` function is an object that
+ * you want to convert to a primitive value. The function attempts to convert the object to a primitive
+ * value by first checking if the object has a `valueOf` method. If the `valueOf` method exists, it
+ * @returns The function `tryObjectToPrimitive` returns a value of type `ComparablePrimitive` if a
+ * primitive comparable value is found within the object, or a string value if the object has a custom
+ * `toString` method that does not return `'[object Object]'`. If neither condition is met, the
+ * function returns `null`.
+ */
+function tryObjectToPrimitive(obj) {
+    if (typeof obj.valueOf === 'function') {
+        const valueOfResult = obj.valueOf();
+        if (valueOfResult !== obj) {
+            if (isPrimitiveComparable(valueOfResult))
+                return valueOfResult;
+            if (typeof valueOfResult === 'object' && valueOfResult !== null)
+                return tryObjectToPrimitive(valueOfResult);
+        }
+    }
+    if (typeof obj.toString === 'function') {
+        const stringResult = obj.toString();
+        if (stringResult !== '[object Object]')
+            return stringResult;
+    }
+    return null;
+}
+/**
+ * The function `isComparable` in TypeScript checks if a value is comparable, handling primitive values
+ * and objects with optional force comparison.
+ * @param {unknown} value - The `value` parameter in the `isComparable` function represents the value
+ * that you want to check if it is comparable. It can be of any type (`unknown`), and the function will
+ * determine if it is comparable based on certain conditions.
+ * @param [isForceObjectComparable=false] - The `isForceObjectComparable` parameter in the
+ * `isComparable` function is a boolean flag that determines whether to treat non-primitive values as
+ * comparable objects. When set to `true`, it forces the function to consider non-primitive values as
+ * comparable objects, regardless of their type.
+ * @returns The function `isComparable` returns a boolean value indicating whether the `value` is
+ * considered comparable or not.
+ */
+export function isComparable(value, isForceObjectComparable = false) {
+    if (value === null || value === undefined)
         return false;
-    if (keyType === 'undefined')
+    if (isPrimitiveComparable(value))
+        return true;
+    if (typeof value !== 'object')
         return false;
-    if (keyType === 'function')
-        return isComparable(key());
-    if (keyType === 'object') {
-        if (key === null)
-            return true;
-        // if (typeof key.valueOf === 'function') return isComparable(key.valueOf());   // This will keep recursing because every object has a valueOf method.
-        // if (typeof key.toString === 'function') return isComparable(key.toString()); // This will also keep recursing because every string type has a toString method.
+    if (value instanceof Date)
+        return !Number.isNaN(value.getTime());
+    if (isForceObjectComparable)
+        return true;
+    const comparableValue = tryObjectToPrimitive(value);
+    if (comparableValue === null || comparableValue === undefined)
         return false;
-    }
-    return false;
+    return isPrimitiveComparable(comparableValue);
 }