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

package/dist/esm/_mergeRefs.js

@@ -25,6 +25,17 @@
 
 /* istanbul ignore file */
 
+/**
+ * Merge multiple refs into a single ref callback.
+ * This function allows you to combine multiple refs (either callback refs or React refs)
+ * into a single ref callback that can be used in React components.
+ * This is particularly useful when you want to assign a single element to multiple refs,
+ * such as when using third-party libraries that require refs or when you want to share refs between components.
+ * The function iterates over the provided refs and assigns the element to each ref.
+ *
+ * @param {AnyObject[]} refs - An array of refs to merge.
+ * @returns {function} A function that takes an element and assigns it to all provided refs.
+ */
 var mergeRefs = function mergeRefs() {
   for (var _len = arguments.length, refs = new Array(_len), _key = 0; _key < _len; _key++) {
     refs[_key] = arguments[_key];

package/dist/esm/_tokenize.js

@@ -27,10 +27,14 @@ import { isEmpty, isArray } from './_isType.js';
 
 
 /**
- * split text into array of tokens by word boundaries
- * @param str
- * @param keywords
- * @internal
+ * Tokenize a string based on provided keywords.
+ * This function splits the input string into tokens, where each token is an array containing
+ * the substring before the keyword and the keyword itself.
+ * If no keywords are provided, it returns the entire string as a single token.
+ *
+ * @param {string} str - The string to tokenize.
+ * @param {string | string[]} keywords - A string or an array of strings to use as keywords for tokenization.
+ * @returns {Array<[string, string]>} An array of tokens, where each token is an array of [substring, keyword].
  */
 var tokenize = function tokenize(str, keywords) {
   if (isEmpty(keywords)) {
@@ -56,6 +60,15 @@ var tokenize = function tokenize(str, keywords) {
   tokens.push([str.substring(lastIndex), ""]);
   return tokens;
 };
+
+/**
+ * Generate a token from a string.
+ * This function creates a token by taking the first letter of the first word and the first letter of the last word,
+ * or the first two letters of the first word if there is no last word.
+ *
+ * @param {string} str - The string to tokenize.
+ * @returns {string} A string token consisting of the first letters of the first and last words, or the first two letters of the first word.
+ */
 var iconToken = function iconToken(str) {
   var split = str.trim().split(" ");
   var first = split[0];

package/dist/esm/getImageColorset.js

@@ -25,6 +25,21 @@
 
 /* istanbul ignore file */
 
+/**
+ * Get the color set of an image element.
+ * This function analyzes the pixel data of an image to determine if it is predominantly light or dark.
+ * It returns "light", "dark", or "light_transparent"/"dark_transparent" based on the pixel analysis.
+ * It uses a canvas to draw the image and extract pixel data for analysis.
+ * * The function calculates the brightness of each pixel using the formula:
+ *  brightness = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ * * It counts the number of light and dark pixels, and determines the overall color set based on the ratio of light to dark pixels.
+ * * If the image has transparent pixels, it appends "_transparent" to the result.
+ * * This function is useful for determining the color scheme of an image, which can be helpful for UI design,
+ *   theming, and accessibility considerations.
+ *
+ * @param {HTMLImageElement} el - The HTMLImageElement to analyze.
+ * @returns {string} A string indicating the color set of the image.
+ */
 var getImageColorset = function getImageColorset(el) {
   // create canvas
   var canvas = document.createElement("canvas");
@@ -45,8 +60,8 @@ var getImageColorset = function getImageColorset(el) {
         transparent = true;
         continue;
       }
-      if (transparent && data[x - 1] === 1) {
-        continue;
+      if (data[x + 3] < 1) {
+        transparent = true;
       }
       r = data[x];
       g = data[x + 1];

package/dist/esm/index.js

@@ -12,7 +12,8 @@ export { getByPath, getValue } from './_getByPath.js';
 export { hash, shortHash, uuid } from './_hash.js';
 export { interpolate, renderTemplate } from './_interpolate.js';
 export { compareValues, isEqual, matchString } from './_isEqual.js';
-export { isArray, isBoolean, isColor, isEmpty, isFalse, isNil, isNull, isNumber, isObject, isRtl, isString, isSvgPath, isTrue, isUndefined } from './_isType.js';
+export { isArray, isBoolean, isColor, isDefined, isEmpty, isFalse, isNil, isNull, isNumber, isObject, isRtl, isString, isSvgPath, isTrue, isUndefined } from './_isType.js';
+export { convertLatLng, getLatitudeLongitude, getLocationAsText } from './_lonlat.js';
 export { mergeRefs } from './_mergeRefs.js';
 export { iconToken, tokenize } from './_tokenize.js';
 export { getImageColorset } from './getImageColorset.js';

package/dist/esm/useLogger.js

@@ -207,7 +207,15 @@ var logger = function logger() {
 };
 
 /**
- * @internal
+ * useLogger is a custom hook that provides logging functionality.
+ * It allows you to log messages with different levels (log, debug, info, error, warning)
+ * and also provides a timer function to measure the duration of processes.
+ * The logs can include additional details such as the module name, process name, duration, and total time.
+ * It is designed to work in both Node.js and browser environments, adapting the log format accordingly.
+ * It uses ANSI escape codes for terminal colors in Node.js and CSS styles for console logs in the browser.
+ *
+ * @param mod - Optional module name to include in the log details.
+ * @returns An object with methods for logging messages and a timer function.
  */
 var useLogger = function useLogger(mod) {
   return {

package/dist/types/_ascii.d.ts

@@ -1,5 +1,10 @@
 /**
- * latin to ascii converter for convenient searching
- * @internal
+ * Converts a string to its ASCII representation by replacing
+ * special characters with their ASCII equivalents.
+ * This function is useful for normalizing strings for search or display purposes.
+ * It replaces characters like "Ä" with "Ae", "ß" with "ss", etc.
+ *
+ * @param {string} str - The input string to be converted.
+ * @returns {string} - The ASCII representation of the input string.
  */
 export declare const ascii: (str: string) => string;

package/dist/types/_boundingBox.d.ts

@@ -1,10 +1,22 @@
 /**
- * box "x,y,w,h" | [x,y,w,h]
- * returns canvas box [x,y,w,h]
+ * Get bounding box from a string or array.
+ * The box can be in the format "x,y,w,h" or [x,y,w,h].
+ * The box is adjusted to ensure that x and y are non-negative.
+ * The width and height are adjusted accordingly.
+ *
+ * @param box "x,y,w,h" | [x,y,w,h]
+ * @returns canvas box [x,y,w,h]
  */
 export declare const getBox: (box?: string | [number, number, number, number]) => [number, number, number, number];
 /**
- * box "x1,y1,x2,y2" | [x1,y1,x2,y2]
- * returns canvas box [x,y,w,h]
+ * Get bounding box from a string or array.
+ * The box can be in the format "x1,y1,x2,y2" or [x1,y1,x2,y2].
+ * The box is adjusted to ensure that x1 and y1 are non-negative.
+ * The width and height are calculated as x2 - x1 and y2 - y1 respectively.
+ * If x1 or y1 are negative, they are set to 0 and the width and height are adjusted accordingly.
+ * This is useful for ensuring that the bounding box is always within the canvas area.
+ *
+ * @param box "x1,y1,x2,y2" | [x1,y1,x2,y2]
+ * @returns canvas box [x,y,w,h]
  */
 export declare const getBoundingBox: (box?: string | [number, number, number, number]) => [number, number, number, number];

package/dist/types/_countries.d.ts

@@ -1,5 +1,5 @@
 /**
- * @internal
+ * Country interface
  */
 export interface Country {
     continent: string;
@@ -16,44 +16,62 @@ export interface Country {
     emoji: string;
 }
 /**
- * country list with helper functions
+ * Country list with helper functions
+ * This is a list of all countries with their details.
+ * It includes information such as continent, ISO codes, name, full name, capital, top-level domain (TLD), currency, phone code, and emoji.
+ * This list can be used to retrieve country information based on various codes or names.
+ * @type {Country[]}
  */
 declare const _default: {
     /**
-     * Get iso2 code
-     * @param code
+     * Get ISO2 country code
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string | undefined} - Returns the ISO2 country code if found, otherwise undefined.
      */
     toIso2(code: string): string | undefined;
     /**
-     * Get iso3 code
-     * @param code
+     * Get ISO3 country code
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string | undefined} - Returns the ISO3 country code if found, otherwise undefined.
      */
     toIso3(code: string): string | undefined;
     /**
-     * Country flag emoji
-     * @param code
+     * Get country emoji
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string} - Returns the emoji representation of the country if found, otherwise returns a default flag emoji.
      */
     emoji(code: string): string;
     /**
      * Get country name
-     * @param code
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {string} - Returns the name of the country if found, otherwise returns the code itself.
      */
     name: (code: string) => string;
     /**
-     * Find country by code
-     * @param code
-     * @return continent: string;
-     * @return iso2: string;
-     * @return iso3: string;
-     * @return name: string;
-     * @return fullname: string;
-     * @return capital: string;
-     * @return tld: string;
-     * @return currency: string;
-     * @return phone: string;
-     * @return emoji: string;
+     * This function searches for a country in the list by its code.
+     * It supports various formats:
+     * - ISO2 code (e.g., "US")
+     * - ISO3 code (e.g., "USA")
+     * - Alternative code (e.g., "US", "USA", "United States")
+     * It returns the first matching country object or undefined if not found.
+     * This function is useful for retrieving country details based on different code formats.
+     *
+     * @param code - The country code to search for. It can be an ISO2 code, ISO3 code, or an alternative code.
+     * @return {Country | undefined} - Returns the country object if found, otherwise undefined.
      */
     find(code: string): Country | undefined;
+    /**
+     * Country list
+     * This is a list of all countries with their details.
+     * It includes information such as continent, ISO codes, name, full name, capital, top-level domain (TLD), currency, phone code, and emoji.
+     * This list can be used to retrieve country information based on various codes or names.
+     *
+     * @type {Country[]}
+     */
     list: ({
         continent: string;
         iso2: string;

package/dist/types/_debounce.d.ts

@@ -1,6 +1,12 @@
 /**
- * debounce callback
- * @internal
+ * Debounce function to limit the rate at which a function can fire.
+ * It will delay the execution of the function until after a specified timeout
+ * has elapsed since the last time the function was invoked.
+ *
+ * @param fn - The function to debounce.
+ * @param timeout - The number of milliseconds to wait before invoking the function.
+ * @returns A debounced version of the function that can be called with any arguments.
+ *          The debounced function also has a `cancel` method to clear the timeout.
  */
 export declare const debounce: (fn: (...rest: any) => any, timeout?: number) => {
     (...args: any): void;

package/dist/types/_dedupe.d.ts

@@ -1,4 +1,47 @@
-export declare const dedupe: (list: any[], key?: string) => any[];
-export declare const flatten: (list: any[]) => any[];
-export declare const flattenAndDedupe: (list?: any[], key?: string) => any[];
-export declare const groupBy: <T extends KeyValue<any>>(list: T[], prop: keyof T, missingKey?: string) => KeyValue<T[]>;
+/**
+ * Remove duplicates from a list of objects based on a key or the entire object.
+ * If a key is provided, it will deduplicate based on the value of that key.
+ * If no key is provided, it will deduplicate based on the entire object.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ *
+ * @param list
+ * @param key
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A new array with duplicates removed.
+ */
+export declare const dedupe: <T extends AnyObject>(list: T[], key?: keyof T) => T[];
+/**
+ * Flatten a list of objects, removing any empty objects.
+ * It will flatten up to 5 levels deep and filter out any empty objects.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ *
+ * @param list
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A flattened array of objects.
+ */
+export declare const flatten: <T extends AnyObject>(list: T[]) => (T extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr extends readonly (infer InnerArr)[] ? InnerArr : InnerArr : InnerArr : InnerArr : InnerArr : T)[];
+/**
+ * Flatten a list of objects and remove duplicates based on a key or the entire object.
+ * If a key is provided, it will deduplicate based on the value of that key.
+ * If no key is provided, it will deduplicate based on the entire object.
+ * This is useful for normalizing data structures that may have nested arrays or objects.
+ * Flattening is done first, followed by deduplication.
+ *
+ * @param list
+ * @param key
+ * @typedef {T} AnyObject - A generic type representing list items.
+ * @returns {T[]} - A new array with duplicates removed.
+ */
+export declare const flattenAndDedupe: <T extends AnyObject>(list?: T[][], key?: keyof T) => T[];
+/**
+ * Group a list of objects by a specific property.
+ * If the property is not present in an object, it will use the `missingKey` value as the key.
+ * This is useful for organizing data into categories based on a specific property.
+ *
+ * @param list
+ * @param prop
+ * @param missingKey
+ * @typedef {T} KeyValue - A generic type representing list items with key-value pairs.
+ * @returns {KeyValue<T[]>} - An object mapping keys to arrays of items.
+ */
+export declare const groupBy: <T extends KeyValue>(list: T[], prop: keyof T, missingKey?: string) => KeyValue<T[]>;

package/dist/types/_fetch.d.ts

@@ -5,19 +5,22 @@ declare interface FetchOptions {
     signal?: string | AbortSignal;
 }
 /**
- * Fetch helper
- * @param method
- * @param url
- * @param options.headers
- * @param options.body
- * @param options.signal
- * @internal
+ * Fetch utility function to make HTTP requests.
+ * It supports GET, POST, PUT, and DELETE methods.
+ * It automatically handles JSON responses and error codes.
+ * It also supports aborting requests using an AbortController.
+ *
+ * @param method - The HTTP method to use (GET, POST, PUT, DELETE).
+ * @param url - The URL to send the request to.
+ * @param options.headers - Headers to include in the request.
+ * @param options.body - The body of the request (for POST and PUT requests).
+ * @param options.signal - An AbortSignal to cancel the request.
+ * @returns A promise that resolves to the JSON response from the server.
+ * @throws An error if the request fails or if the response contains an error code.
  */
 export declare const _fetch: {
     (method: METHODS, url: string, { headers, body, signal }: FetchOptions): Promise<any>;
-    /** ***************** attach isAborted helper to fetch method *******************/
     isAborted({ name }: Error): boolean;
-    /** ***************** attach abort helper to fetch method *******************/
     abort(signal: string): void;
 };
 export {};

package/dist/types/_fileType.d.ts

@@ -1,5 +1,21 @@
+/**
+ * File type utility to get the file type from a MIME type.
+ * This utility provides a mapping of common MIME types to their human-readable names.
+ * It can be used to display file types in a user-friendly manner.
+ */
 declare const _default: {
+    /**
+     * Get the human-readable file type from a MIME type.
+     * This method looks up the MIME type in a predefined list
+     * and returns a user-friendly name.
+     *
+     * @param mime MIME type string, e.g. "application/pdf"
+     * @returns {string} - The human-readable file type.
+     */
     mime(mime?: string): any;
+    /**
+     * List of common MIME types and their human-readable names.
+     */
     mimeList: {
         "application/x-tika-msoffice": string;
         "application/x-tika-ooxml": string;

package/dist/types/_format.d.ts

@@ -1,27 +1,98 @@
+/**
+ * Format utility functions for various data types.
+ * This namespace provides methods to format phone numbers, numbers, bytes, percentages, dates, and durations.
+ */
 export declare 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.
+     */
     const phone: (value?: string, country?: string, useCss?: boolean) => string | undefined;
-    /** ***************** 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
+     */
     const number: (number?: string | number, format?: string) => string;
-    /** ***************** 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
+     */
     const bytes: (number?: string | number) => string;
-    /** ***************** 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
+     */
     const percent: (number?: string | number) => string;
-    /** ***************** format date using `date-fns` *******************/
-    const date: (date?: Date | string | number, fmt?: string) => string;
+    /**
+     * 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
+     */
+    const date: (date?: Date | string | number, format?: string) => string;
     /** ***************** 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.
      */
     const duration: (number?: string | number, isFraction?: boolean) => string | undefined;
     /**
-     * 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.
      */
     const durationSeconds: (number?: string | number, isFraction?: boolean) => string | undefined;
 }

package/dist/types/_getByPath.d.ts

@@ -1,10 +1,21 @@
 /**
- * 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 declare const getByPath: <T = any>(obj: KeyValue, path: string, defaultValue?: any) => T;
 /**
- * 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 declare const getValue: (...args: any[]) => any;

package/dist/types/_hash.d.ts

@@ -1,16 +1,22 @@
 /**
- * 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 declare const hash: (str: string) => number;
 /**
- * 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 declare const shortHash: () => string;
 /**
- * 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 declare const uuid: () => string;

package/dist/types/_interpolate.d.ts

@@ -1,6 +1,21 @@
 /**
- * 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 declare const interpolate: (str: string, model: KeyValue) => string;
+/**
+ * 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 declare const renderTemplate: (str: string, model: KeyValue) => string;

package/dist/types/_isEqual.d.ts

@@ -1,15 +1,46 @@
 /**
- * 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 declare 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 declare const matchString: (base: string, match: string, equality?: "start" | boolean) => boolean;
 /**
- * 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 declare const compareValues: (order?: "asc" | "desc", key?: string) => (a: unknown, b: unknown) => 0 | 1 | -1;