@react-fabric/utilities 1.0.0-beta.6 → 1.0.0-beta.60

package/src/_format.ts

@@ -21,7 +21,7 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { differenceInDays, format, parseISO } from "date-fns";
+import { differenceInDays, format as dtformat, parseISO } from "date-fns";
 import {
   parsePhoneNumberFromString,
   type CountryCode,
@@ -30,9 +30,12 @@ import numeral from "numeral";
 import Countries from "./_countries";
 import { isEmpty, isNil } from "./_isType";
 
-// eslint-disable-next-line @typescript-eslint/no-namespace
+/**
+ * Format utility functions for various data types.
+ * This namespace provides methods to format phone numbers, numbers, bytes, percentages, dates, and durations.
+ */
+ 
 export namespace Format {
-  /** ***************** get phone number object using `libphonenumber-js` *******************/
   const getPhone = (value: string, country: string) => {
     const phone =
       value.match(/^[0+]/) != null ? value.replace(/^00/, "+") : `+${value}`;
@@ -46,7 +49,6 @@ export namespace Format {
     );
   };
 
-  /** ***************** common number format method using `numeral` *******************/
   const numberFormat = (number?: string | number, format = "0,0[.]00a") => {
     if (isNil(number)) {
       return "";
@@ -59,7 +61,7 @@ export namespace Format {
     if (!isNaN(value)) {
       const days = differenceInDays(value, 0);
       const prefix = days > 0 ? `${days}d:` : "";
-      let time = format(
+      let time = dtformat(
         parseISO(new Date(value).toISOString().replace("Z", "")),
         fmt,
       );
@@ -68,7 +70,19 @@ export namespace Format {
     }
   };
 
-  /** ***************** format phone number using `libphonenumber-js` *******************/
+  /**
+   * Format phone number with country flag or emoji.
+   * It takes a phone number string, a country code, and a boolean to indicate whether to use CSS classes for flags.
+   * If the phone number is empty, less than 6 characters, or does not match the regex for valid phone numbers,
+   * it returns the original value.
+   * If the phone number is valid, it formats the phone number using `libphonenumber-js` and returns it with the country flag or emoji.
+   * The country flag is represented as a CSS class, and the emoji is obtained from the `Countries` module.
+   *
+   * @param {string} value - The phone number to format.
+   * @param {string} country - The country code to use for formatting.
+   * @param {boolean} useCss - Whether to use CSS classes for flags.
+   * @returns {string} The formatted phone number with country flag or emoji.
+   */
   export const phone = (value?: string, country = "AE", useCss = false) => {
     if (isEmpty(value) || value.length < 6 || !/^[\d+\s\-()]+$/.test(value))
       return value;
@@ -80,28 +94,74 @@ export namespace Format {
         : Countries.emoji(phone.country ?? "")
     } ${phone.formatInternational()}`;
   };
-  /** ***************** format whole number using `numeral` *******************/
+  /**
+   * Format number using `numeral`.
+   * It takes a number or string and a format string, and returns the formatted number.
+   * If the number is undefined or null, it returns an empty string.
+   * If the number starts with a '+', it retains the '+' sign in the formatted output.
+   * This function is useful for displaying numbers in a human-readable format,
+   * such as for financial data, statistics, or any numerical representation.
+   *
+   * @param {string | number} number - number or string to format
+   * @param {string} [format] - optional format string, defaults to "0,0[.]00a"
+   * @returns {string} formatted number
+   */
   export const number = (number?: string | number, format?: string) => {
     return numberFormat(number, format);
   };
-  /** ***************** format bytes using `numeral` *******************/
+  /**
+   * Format bytes using `numeral`.
+   * It takes a number or string and returns the formatted bytes.
+   * If the number is undefined or null, it returns an empty string.
+   * If the number starts with a '+', it retains the '+' sign in the formatted output.
+   * This function is useful for displaying file sizes or data transfer amounts in a human-readable format.
+   *
+   * @param {string | number} number - number or string to format
+   * @returns {string} formatted bytes
+   */
   export const bytes = (number?: string | number) => {
     return numberFormat(number, "0,0[.]00b");
   };
-  /** ***************** format percentage using `numeral` *******************/
+  /**
+   * Format percentage using `numeral`.
+   * It takes a number or string and returns the formatted percentage.
+   * If the number is undefined or null, it returns an empty string.
+   * If the number starts with a '+', it retains the '+' sign in the formatted output.
+   *
+   * @param {string | number} number - number or string to format
+   * @returns {string} formatted percentage
+   */
   export const percent = (number?: string | number) => {
     return numberFormat(number, "0,0[.]00%");
   };
-  /** ***************** format date using `date-fns` *******************/
-  export const date = (date?: Date | string | number, fmt = "d-M-y") => {
-    return date ? format(new Date(date), fmt) : "";
+  /**
+   * Format date using `date-fns`.
+   * It takes a date (as a Date object, string, or number) and a format string.
+   * If the date is undefined or null, it returns an empty string.
+   * If the date is a valid date, it formats it using the provided format string.
+   * Format defaults to "d-M-y" if not provided.
+   *
+   * @param {date | string | number} date - Date object, string, or number to format
+   * @typedef {string} format - Optional format string, defaults to "d-M-y"
+   * @returns {string} - Formatted date string
+   */
+  export const date = (date?: Date | string | number, format = "d-M-y") => {
+    return date ? dtformat(new Date(date), format) : "";
   };
   /** ***************** format time duration from total seconds/milliseconds *******************/
   /**
    * Format time duration with milliseconds
-   * @param number
-   * @param isFraction
-   * @returns
+   * This function takes a number or string representing a duration in seconds or milliseconds,
+   * and returns a formatted string in the format "HH:mm:ss.SSS".
+   * If the input is undefined or null, it returns "00:00.000".
+   * If the input is Infinity, it returns "∞".
+   * The function also accepts an optional boolean parameter `isFraction` to indicate whether the input is in seconds (true) or milliseconds (false).
+   * If `isFraction` is true, the input is multiplied by 1000 to convert seconds to milliseconds.
+   * The function uses the `makeDuration` helper function to format the duration.
+   *
+   * @param {string | number} number - The duration to format, can be a string or number.
+   * @param {boolean} isFraction - Optional parameter to indicate if the input is in seconds (true) or milliseconds (false).
+   * @returns {string} - The formatted duration string.
    */
   export const duration = (number?: string | number, isFraction?: boolean) => {
     if (isNil(number)) {
@@ -117,10 +177,19 @@ export namespace Format {
     return "00:00.000";
   };
   /**
-   * Format time duration without milliseconds
-   * @param number
-   * @param isFraction
-   * @returns
+   * Format time duration in seconds
+   * This function takes a number or string representing a duration in seconds,
+   * and returns a formatted string in the format "HH:mm:ss".
+   * If the input is undefined or null, it returns "00:00".
+   * If the input is Infinity, it returns "∞".
+   * The function also accepts an optional boolean parameter `isFraction` to indicate whether the input is in seconds (true) or milliseconds (false).
+   * If `isFraction` is true, the input is multiplied by 1000 to convert seconds to milliseconds.
+   * The function uses the `makeDuration` helper function to format the duration.
+   * This function is useful for displaying durations in a human-readable format, such as for timers or elapsed time.
+   *
+   * @param {string | number} number - The duration to format, can be a string or number.
+   * @param {boolean} isFraction - Optional parameter to indicate if the input is in seconds (true) or milliseconds (false).
+   * @returns {string} - The formatted duration string.
    */
   export const durationSeconds = (
     number?: string | number,

package/src/_getByPath.ts

@@ -35,10 +35,10 @@ const _get = (hit: any, field: string): any => {
     return hit;
   }
 
-  if (isObject(hit)) {
+  if (isObject(hit) || isArray(hit)) {
     /** ***************** return value if object.property is not empty *******************/
-    if (!isNil(hit[field])) {
-      return hit[field];
+    if (!isNil(hit[field as any])) {
+      return hit[field as any];
     }
 
     /** ***************** if property name contains `.` separator split to multiple property names *******************/
@@ -80,8 +80,14 @@ const _get = (hit: any, field: string): any => {
 };
 
 /**
- * get property value by path
- * @internal
+ * Get a value from an object by a given path.
+ * This function allows you to retrieve a value from a nested object structure using a dot-separated path.
+ * If the path does not exist or the object is empty, it returns a default value.
+ * @param {KeyValue} obj - The object from which to retrieve the value.
+ * @param {string} path - The dot-separated path to the value within the object.
+ * @param {any} defaultValue - The value to return if the path does not exist or the object is empty.
+ * @typedef {T} AnyObject - The type of the value to be returned.
+ * @returns {T} The value at the specified path, or the default value if the path does not exist.
  */
 export const getByPath = <T = any>(
   obj: KeyValue,
@@ -100,8 +106,13 @@ export const getByPath = <T = any>(
 };
 
 /**
- * get first available value in list
- * @internal
+ * Get the first non-empty value from the provided arguments.
+ * This function is useful for finding a default value or fallback when multiple values are provided.
+ * It checks each argument in order and returns the first one that is not empty.
+ * If all arguments are empty, it returns `undefined`.
+ *
+ * @param {...any} args - The values to check for non-emptiness.
+ * @returns {any} The first non-empty value, or `undefined` if all are empty.
  */
 export const getValue = (...args: any[]) => {
   return args.find((a) => !isEmpty(a));

package/src/_hash.ts

@@ -24,9 +24,11 @@
 import { isEmpty } from "./_isType";
 
 /**
- * calculate hash from string
+ * Generate a hash from a string.
+ * This function computes a simple hash by iterating over each character in the string,
+ * performing bitwise operations to produce a 32-bit integer hash.
  * @param str
- * @internal
+ * @returns {number} A 32-bit integer hash of the input string.
  */
 export const hash = (str: string) => {
   let hash = 0;
@@ -42,16 +44,20 @@ export const hash = (str: string) => {
 };
 
 /**
- * generate short hash from current time
- * @internal
+ * Generate a short hash using the current timestamp and a random number.
+ * This function creates a unique identifier by combining the current time in milliseconds
+ * with a random number, and then converting it to a base-36 string.
+ * @returns {string} A short hash string.
  */
 export const shortHash = () => {
-  return (new Date().getTime() + Math.trunc(Math.random() * 1000)).toString(36);
+  return (new Date().getTime() * Math.random()).toString(36);
 };
 
 /**
- * generate uuid using `crypto.getRandomValues`
- * @internal
+ * Generate a UUID (Universally Unique Identifier).
+ * This function creates a version 4 UUID by generating random numbers
+ * and formatting them according to the UUID standard.
+ * @returns {string} A UUID string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.
  */
 export const uuid = () => {
   return [1e7, 1e3, 4e3, 8e3, 1e11]

package/src/_interpolate.ts

@@ -24,8 +24,13 @@
 import { getByPath } from "./_getByPath";
 
 /**
- * interpolate string template using model
- * @internal
+ * Interpolate a string with values from a model.
+ * This function replaces placeholders in the format ${key} with corresponding values from the model object.
+ * If the value is not a string or number, it returns an empty string.
+ *
+ * @param {string} str - The string to interpolate.
+ * @param {KeyValue} model - The model object containing key-value pairs for interpolation.
+ * @returns {string} The interpolated string with placeholders replaced by values from the model.
  */
 export const interpolate = (str: string, model: KeyValue) => {
   return str.replace(/\${([^{}]*)}/g, (a: string, b: string): string => {
@@ -34,6 +39,16 @@ export const interpolate = (str: string, model: KeyValue) => {
   });
 };
 
+/**
+ * Render a template string with values from a model.
+ * This function replaces placeholders in the format {{key}} with corresponding values from the model object.
+ * If the value is not a string or number, it returns an empty string.
+ * This is similar to the interpolate function but for handlebar templates.
+ *
+ * @param {string} str - The template string to render.
+ * @param {KeyValue} model - The model object containing key-value pairs for rendering the template.
+ * @returns {string} The rendered template string with placeholders replaced by values from the model.
+ */
 export const renderTemplate = (str: string, model: KeyValue) => {
   return str.replace(/{{([^{}]*)}}/g, (a: string, b: string): string => {
     const r = getByPath(model, b);

package/src/_isEqual.ts

@@ -22,13 +22,26 @@
  */
 
 import { ascii } from "./_ascii";
-import { isBoolean, isNumber, isObject, isString } from "./_isType";
+import { isBoolean, isNil, isNumber, isObject, isString } from "./_isType";
 
 /**
- * check equality of objects
- * @internal
+ * Compare two objects or values for equality.
+ * This function checks if two values are equal, including nested objects and arrays.
+ * It handles various data types such as strings, numbers, booleans, arrays, and objects.
+ * If both values are `null` or `undefined`, they are considered equal.
+ * If both values are primitive types (string, number, boolean), they are compared directly.
+ * If both values are arrays, they are compared element by element.
+ * If both values are objects, they are compared by their keys and values.
+ * If the values are of different types or structures, they are considered not equal.
+ *
+ * @param {unknown} obj - The first value to compare.
+ * @param {unknown} test - The second value to compare against the first.
+ * @returns {boolean} - Returns true if the values are equal, false otherwise.
  */
 export const isEqual = (obj: unknown, test: unknown): boolean => {
+  if (isNil(obj) && isNil(test)) {
+    return true;
+  }
   if (isString(obj) || isNumber(obj) || isBoolean(obj)) {
     return obj === test;
   } else if (Array.isArray(obj) && Array.isArray(test)) {
@@ -56,8 +69,20 @@ export const isEqual = (obj: unknown, test: unknown): boolean => {
 };
 
 /**
- * match strings
- * @internal
+ * Match a string against another string with options for equality.
+ * This function checks if the base string starts with, includes, or is equal to the match string,
+ * based on the specified equality condition.
+ * It normalizes both strings to lowercase and ASCII format before comparison.
+ * This is useful for case-insensitive and ASCII-only comparisons,
+ * such as when filtering or searching through text data.
+ *
+ * @param {string} base - The base string to match against.
+ * @param {string} match - The string to match with the base string.
+ * @param {("start" | boolean)} equality - The type of match to perform:
+ *                   - "start": checks if the base string starts with the match string.
+ *                   - true: checks for exact equality.
+ *                   - false (default): checks if the base string includes the match string.
+ * @returns {boolean} - Returns true if the base string matches the conditions specified by the match string and equality.
  */
 export const matchString = (
   base: string,
@@ -75,8 +100,17 @@ export const matchString = (
 };
 
 /**
- * compare values
- * @internal
+ * Compare two values for sorting.
+ * This function compares two values based on the specified order (ascending or descending).
+ * If a key is provided, it compares the values of that key in the objects.
+ * It handles various data types such as strings, numbers, booleans, and objects.
+ * It returns a comparison function that can be used with array sorting methods.
+ * * The comparison is done in a case-insensitive manner for strings,
+ *  treating special characters as their ASCII equivalents.
+ *
+ * @param {("asc" | "desc")} order - The order of comparison, either "asc" for ascending or "desc" for descending.
+ * @param {string} key - An optional key to compare values within objects.
+ * @returns {Function} A comparison function that can be used with array sorting methods.
  */
 export const compareValues =
   (order: "asc" | "desc" = "asc", key?: string) =>

package/src/_isType.ts

@@ -21,23 +21,54 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * Check if a value is undefined.
+ * @param value - The value to check.
+ * @returns true if the value is undefined, false otherwise.
+ */
 export const isUndefined = (value: AnyObject): value is undefined => {
   return value === undefined;
 };
 
+/**
+ * Check if a value is null.
+ * @param value - The value to check.
+ * @returns true if the value is null, false otherwise.
+ */
 export const isNull = (value: AnyObject): value is null => {
   return value === null;
 };
 
-export const isNil = (val: AnyObject): val is undefined => {
+/**
+ * Check if a value is either null or undefined.
+ * @param val - The value to check.
+ * @returns true if the value is null or undefined, false otherwise.
+ */
+export const isNil = (val: AnyObject): val is null | undefined => {
   return val === undefined || val === null;
 };
+
+export const isDefined = (val: AnyObject): boolean => !isNil(val) && val !== "";
+
+/**
+ * Check if a value is empty.
+ * A value is considered empty if it is:
+ * - undefined
+ * - null
+ * - an empty string
+ * - an empty array
+ * - an empty object
+ * - an empty Map or Set
+ * - a boolean, number, or bigint (not empty)
+ * @param val - The value to check.
+ * @returns true if the value is empty, false otherwise.
+ */
 export const isEmpty = (val: AnyObject): val is undefined => {
   if (val instanceof Date) return false;
   if (isNil(val) || val === "") {
     return true;
   }
-  if (Array.isArray(val) && val.filter(Boolean).length === 0) {
+  if (Array.isArray(val) && val.filter(isDefined).length === 0) {
     return true;
   }
   if (val instanceof Map || val instanceof Set) return val.size === 0;
@@ -47,6 +78,16 @@ export const isEmpty = (val: AnyObject): val is undefined => {
   return !!val && typeof val === "object" && Object.entries(val).length === 0;
 };
 
+/**
+ * Check if a value is an object.
+ * An object is considered valid if it is:
+ * - not null or undefined
+ * - not a Date instance
+ * - of type 'object'
+ * - not an array
+ * @param val - The value to check.
+ * @returns true if the value is an object, false otherwise.
+ */
 export const isObject = (val: AnyObject): val is KeyValue => {
   return (
     !isNil(val) &&
@@ -55,21 +96,60 @@ export const isObject = (val: AnyObject): val is KeyValue => {
     !Array.isArray(val)
   );
 };
+
+/**
+ * Check if a value is an array.
+ * An array is considered valid if it is:
+ * - not null or undefined
+ * - an instance of Array
+ * @param val - The value to check.
+ * @returns true if the value is an array, false otherwise.
+ */
 export const isArray = <T = AnyObject>(val: AnyObject): val is T[] => {
   return Array.isArray(val);
 };
 
+/**
+ * Check if a value is a string.
+ * A string is considered valid if it is:
+ * - not null or undefined
+ * - of type 'string'
+ * @param value - The value to check.
+ * @returns true if the value is a string, false otherwise.
+ */
 export const isString = (value: AnyObject): value is string => {
   return typeof value === "string";
 };
 
+/**
+ * Check if a value is a number.
+ * A number is considered valid if it is:
+ * - not null or undefined
+ * - of type 'number'
+ * @param value - The value to check.
+ * @returns true if the value is a number, false otherwise.
+ */
 export const isNumber = (value: AnyObject): value is number => {
   return typeof value === "number";
 };
 
+/**
+ * Check if a value is a boolean.
+ * A boolean is considered valid if it is:
+ * - not null or undefined
+ * - of type 'boolean'
+ */
 export const isBoolean = (value: AnyObject): value is boolean => {
   return typeof value === "boolean";
 };
+
+/**
+ * Check if a value is a true.
+ * A value is considered true if it is:
+ * - strictly equal to true
+ * - equal to 1
+ * - a string that is "yes" or "true" (case insensitive)
+ */
 export const isTrue = (value: AnyObject = ""): value is true => {
   return (
     value === true ||
@@ -78,6 +158,14 @@ export const isTrue = (value: AnyObject = ""): value is true => {
     value?.toString().toLowerCase() === "true"
   );
 };
+
+/**
+ * Check if a value is false.
+ * A value is considered false if it is:
+ * - strictly equal to false
+ * - equal to 0
+ * - a string that is "no" or "false" (case insensitive)
+ */
 export const isFalse = (value: AnyObject = ""): value is false => {
   return (
     value === false ||
@@ -87,6 +175,17 @@ export const isFalse = (value: AnyObject = ""): value is false => {
   );
 };
 
+/**
+ * Check if a value is a valid color.
+ * A color is considered valid if it:
+ * - starts with a '#' (hex color)
+ * - starts with 'rgb' (RGB color)
+ * - starts with 'hsl' (HSL color)
+ * - starts with 'lab' (Lab color)
+ * - is equal to 'transparent'
+ * @param color - The value to check.
+ * @returns true if the value is a valid color, false otherwise.
+ */
 export const isColor = (color: string) =>
   color.startsWith?.("#") ||
   color.startsWith?.("rgb") ||
@@ -94,12 +193,27 @@ export const isColor = (color: string) =>
   color.startsWith?.("lab") ||
   color === "transparent";
 
+/**
+ * Check if a value is a valid SVG path.
+ * A valid SVG path is a string that:
+ * - starts with 'M' or 'm' (move to command)
+ * - contains at least one digit or decimal point
+ * - ends with 'Z' or 'z' (close path command)
+ * @param value - The value to check.
+ * @returns true if the value is a valid SVG path, false otherwise.
+ */
 export const isSvgPath = (value: AnyObject): value is string => {
   return (
     typeof value === "string" && value.match(/^[Mm][\d.].*[\dzZ]$/) !== null
   );
 };
 
+/**
+ * Check if the document is in RTL (Right-to-Left) mode.
+ * This function checks the computed style of the document's root element
+ * to determine if the direction is set to 'rtl'.
+ * @returns true if the document is in RTL mode, false otherwise.
+ */
 export const isRtl = () => {
   return getComputedStyle(document.documentElement).direction === "rtl";
 };