@react-fabric/utilities 1.0.0-beta.5 → 1.0.0-beta.52

package/dist/types/_lonlat.d.ts

@@ -0,0 +1,45 @@
+type LngLatLike = {
+    lng: number;
+    lat: number;
+} | {
+    lon: number;
+    lat: number;
+} | {
+    longitude: number;
+    latitude: number;
+} | [lon: number | string, lat: number | string] | string;
+/**
+ * Convert various formats of longitude and latitude to a tuple of [lon, lat].
+ * This function supports:
+ * - Arrays with two or three elements (e.g., [lon, lat] or [lon, lat, alt])
+ * - Objects with properties `lng`, `lat`, `lon`, or `longitude` and `latitude`
+ * - Strings in the format "lat,lon"
+ * The function will return a tuple of numbers [lon, lat].
+ *
+ * @param {LngLatLike} lonLat - The input longitude and latitude in various formats.
+ * @returns { [lon: number, lat: number] } A tuple of [lon, lat] where lon and lat are numbers.
+ * @throws Error if the input is not a valid format.
+ */
+export declare const convertLatLng: (lonLat: LngLatLike) => [lon: number, lat: number];
+/**
+ * Convert a latitude and longitude to a human-readable text format.
+ * This function takes a latitude and longitude in various formats and
+ * returns a string in the format "degrees˚minutes'seconds" with direction (N/S, E/W).
+ *
+ * This function supports:
+ *
+ * - Objects with properties `lng`, `lat`, `lon`, or `longitude` and `latitude`
+ * - Arrays with two or three elements (e.g., [lon, lat] or [lon, lat, alt])
+ * - Strings in the format "lat,lon"
+ *
+ * @param {LngLatLike} latlon - The latitude and longitude in various formats.
+ * @returns {string} A string representation of the location in DMS format.
+ *
+ * @example
+ * ```jsx
+ * const location = getLocationAsText({ lat: 40.7128, lng: -74.0060 });
+ * console.log(location); // "40˚42'51.36"N, 74˚0'21.60"W"
+ * ```
+ */
+export declare const getLocationAsText: (latlon: LngLatLike) => string;
+export {};

package/dist/types/_mergeRefs.d.ts

@@ -1 +1,12 @@
+/**
+ * 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.
+ */
 export declare const mergeRefs: (...refs: AnyObject[]) => (el: AnyObject) => void;

package/dist/types/_tokenize.d.ts

@@ -1,8 +1,20 @@
 /**
- * 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].
  */
 export declare const tokenize: (str: string, keywords?: string | string[]) => string[][];
+/**
+ * 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.
+ */
 export declare const iconToken: (str: string) => string;

package/dist/types/getImageColorset.d.ts

@@ -1 +1,16 @@
+/**
+ * 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.
+ */
 export declare const getImageColorset: (el: HTMLImageElement) => string;

package/dist/types/index.d.ts

@@ -13,6 +13,7 @@ export * from "./_hash";
 export * from "./_interpolate";
 export * from "./_isEqual";
 export * from "./_isType";
+export * from "./_lonlat";
 export * from "./_mergeRefs";
 export * from "./_tokenize";
 export { getImageColorset } from "./getImageColorset";

package/dist/types/useLogger.d.ts

@@ -5,7 +5,15 @@ interface LogDetail {
     totalTime?: number;
 }
 /**
- * @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.
  */
 export declare const useLogger: (mod?: string) => {
     timer(process: string): {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-fabric/utilities",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.52",
   "description": "RUF: Utility package",
   "author": "Adarsh Pastakia <adarshpastakia@outlook.com>",
   "license": "MIT",
@@ -32,8 +32,8 @@
     "watch": "npm-run-all -p watch:rollup watch:dts"
   },
   "dependencies": {
-    "date-fns": "^4.0.0",
-    "libphonenumber-js": "^1.11.8",
+    "date-fns": "^4.1.0",
+    "libphonenumber-js": "^1.12.8",
     "numeral": "^2.0.6",
     "yup": "^1.4.0"
   },
@@ -44,5 +44,5 @@
     "node": ">=18.12.0",
     "npm": ">=8.19.0"
   },
-  "gitHead": "7d4a7ed1ea9890652826bef58d01c31280d761c8"
+  "gitHead": "0eabb9d88d91af93d657bcc209b226fd576e8260"
 }

package/src/_ascii.ts

@@ -80,14 +80,19 @@ const conversions = {
 };
 
 /**
- * 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 const ascii = (str: string) => {
   if (isEmpty(str)) return "";
-  Object.entries(conversions).forEach(([a, l]) => {
-    const re = new RegExp(l, "g");
-    str = `${str}`.replace(re, a);
+  Object.entries(conversions).forEach((entry) => {
+    const re = new RegExp(entry[1], "g");
+    str = `${str}`.replace(re, entry[0]);
   });
   return str;
 };

package/src/_boundingBox.ts

@@ -38,8 +38,13 @@ const _getBox = (
 };
 
 /**
- * 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 const getBox = (
   box: string | [number, number, number, number] = "0,0,0,0",
@@ -55,8 +60,15 @@ export const getBox = (
 };
 
 /**
- * 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 const getBoundingBox = (
   box: string | [number, number, number, number] = "0,0,0,0",

package/src/_countries.ts

@@ -24,7 +24,7 @@
 /* istanbul ignore file */
 
 /**
- * @internal
+ * Country interface
  */
 export interface Country {
   continent: string;
@@ -42,28 +42,38 @@ export interface Country {
 }
 
 /**
- * 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[]}
  */
 export 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) {
     const ctry = this.find(code);
     return ctry != null ? ctry.iso2 : 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) {
     const ctry = this.find(code);
     return ctry != null ? ctry.iso3 : 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) {
     const ctry = this.find(code);
@@ -71,25 +81,25 @@ export default {
   },
   /**
    * 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: function (code: string) {
     const ctry = this.find(code);
     return ctry != null ? ctry.name : code;
   },
   /**
-   * 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 {
     return this.list.find(
@@ -99,6 +109,14 @@ export default {
         ct.iso2.toLowerCase() === code.toLowerCase(),
     );
   },
+  /**
+   * 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: "Asia",

package/src/_debounce.ts

@@ -24,8 +24,14 @@
 /* istanbul ignore file */
 
 /**
- * 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 const debounce = (fn: (...rest: any) => any, timeout = 500) => {
   /** ***************** create debounce timer id using callback hash *******************/

package/src/_dedupe.ts

@@ -23,25 +23,71 @@
 
 import { isEmpty } from "./_isType";
 
-export const dedupe = (list: any[], key?: string) => {
+/**
+ * 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 const dedupe = <T extends AnyObject>(list: T[], key?: keyof T) => {
   const filtered = list.filter((i) => !isEmpty(i));
   if (!key) {
     return Array.from(new Set(filtered).values());
   }
 
   return Array.from(
-    new Map(filtered.map((obj) => [obj[key] ?? obj, obj])).values(),
+    new Map(filtered.map((obj) => [(obj as KeyValue)[key], obj])).values(),
   );
 };
 
-export const flatten = (list: any[]) => {
+/**
+ * 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 const flatten = <T extends AnyObject>(list: T[]) => {
   return list.flat(5).filter((i) => !isEmpty(i));
 };
 
-export const flattenAndDedupe = (list: any[] = [], key?: string) => {
-  return dedupe(flatten(list), key);
+/**
+ * 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 const flattenAndDedupe = <T extends AnyObject>(
+  list: T[][] = [],
+  key?: keyof T,
+) => {
+  return dedupe(flatten(list) as T[], key);
 };
 
+/**
+ * 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 const groupBy = <T extends KeyValue>(
   list: T[],
   prop: keyof T,

package/src/_fetch.ts

@@ -35,13 +35,18 @@ declare interface FetchOptions {
 const _signals = new Map<string, AbortController>();
 
 /**
- * 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 const _fetch = async (
   method: METHODS,

package/src/_fileType.ts

@@ -23,7 +23,20 @@
 
 /* istanbul ignore file */
 
+/**
+ * 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.
+ */
 export 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 = "") {
     const ret = (this.mimeList as KeyValue)[mime.split(";")[0]];
     if (!ret && !!mime) {
@@ -32,6 +45,9 @@ export default {
     }
     return ret || "Unknown type";
   },
+  /**
+   * List of common MIME types and their human-readable names.
+   */
   mimeList: {
     "application/x-tika-msoffice": "Microsft Office File",
     "application/x-tika-ooxml": "Open Office File",

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";
 
+/**
+ * Format utility functions for various data types.
+ * This namespace provides methods to format phone numbers, numbers, bytes, percentages, dates, and durations.
+ */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 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,