@react-fabric/utilities 1.0.0-beta.8 → 1.0.1

package/src/data/format.ts

@@ -0,0 +1,192 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 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 as dtformat, parseISO } from "date-fns";
+import { parsePhoneNumberFromString, type CountryCode } from "libphonenumber-js";
+import numeral from "numeral";
+import Countries from "../data/countries";
+import { isEmpty } from "../matchers/isEmpty";
+import { isNil } from "../matchers/nullChecks";
+
+/**
+ * Format utility functions for various data types.
+ * This namespace provides methods to format phone numbers, numbers, bytes, percentages, dates, and durations.
+ */
+
+export namespace Format {
+  function getPhone(value: string, country: string) {
+    const phone = value.match(/^[0+]/) != null ? value.replace(/^00/, "+") : `+${value}`;
+    const number = parsePhoneNumberFromString(phone, country as CountryCode);
+    /* istanbul ignore next */
+    return (
+      number ?? {
+        country: "",
+        formatInternational: () => value,
+      }
+    );
+  }
+
+  function numberFormat(number?: string | number, format = "0,0[.]00a") {
+    if (isNil(number)) {
+      return "";
+    }
+    const prefix = `${number}`.startsWith("+") ? "+" : "";
+    return prefix + numeral(number).format(format);
+  }
+
+  function makeDuration(value: number, fmt = "HH:mm:ss.SSS") {
+    if (!isNaN(value)) {
+      const days = differenceInDays(value, 0);
+      const prefix = days > 0 ? `${days}d:` : "";
+      let time = dtformat(parseISO(new Date(value).toISOString().replace("Z", "")), fmt);
+      if (!prefix) time = time.replace(/^00:/, "");
+      return `${prefix}${time}`;
+    }
+  }
+
+  /**
+   * 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 function phone(value?: string, country = "AE", useCss = false) {
+    if (isEmpty(value) || value.length < 6 || !/^[\d+\s\-()]+$/.test(value)) return value;
+    const phone = getPhone(value, country);
+    /* istanbul ignore next */
+    return `${useCss ? `<span class="iconify-color circle-flags--${phone.country}"></span>` : Countries.emoji(phone.country ?? "")} ${phone.formatInternational()}`;
+  }
+  /**
+   * 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 function number(number?: string | number, format?: string) {
+    return numberFormat(number, format);
+  }
+  /**
+   * 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 function bytes(number?: string | number) {
+    return numberFormat(number, "0,0[.]00b");
+  }
+  /**
+   * 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 function percent(number?: string | number) {
+    return numberFormat(number, "0,0[.]00%");
+  }
+  /**
+   * 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 function 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
+   * 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 function duration(number?: string | number, isFraction?: boolean) {
+    if (isNil(number)) {
+      return "00:00.000";
+    }
+    if (number === Infinity) {
+      return "∞";
+    }
+    const value = parseFloat(`${number}`) * (isFraction ? 1000 : 1);
+    return makeDuration(value) ?? "00:00.000";
+  }
+  /**
+   * 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 function durationSeconds(number?: string | number, isFraction?: boolean) {
+    if (isNil(number)) {
+      return "00:00";
+    }
+    if (number === Infinity) {
+      return "∞";
+    }
+    const value = parseFloat(`${number}`) * (isFraction ? 1000 : 1);
+    return makeDuration(value, "HH:mm:ss") ?? "00:00";
+  }
+}

package/src/helpers/debounce.ts

@@ -0,0 +1,49 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/* istanbul ignore file */
+
+/**
+ * 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 function debounce(fn: (...rest: AnyObject[]) => unknown, timeout = 500) {
+  /** ***************** create debounce timer id using callback hash *******************/
+  let _timer: number;
+
+  /** ***************** return debounced function *******************/
+  const cb = (...args: AnyObject[]) => {
+    clearTimeout(_timer);
+    if (typeof window !== "undefined") _timer = window.setTimeout(() => fn?.(...(args as unknown[])), timeout);
+  };
+  cb.cancel = () => clearTimeout(_timer);
+  return cb;
+}

package/src/{useLogger.ts → helpers/getLogger.ts}

@@ -1,24 +1,26 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
- *
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
  *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
- * and associated documentation files (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
  *
- * The above copyright notice and this permission notice shall be included in all copies or substantial
- * portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
- * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
 interface LogDetail {
@@ -28,12 +30,12 @@ interface LogDetail {
   totalTime?: number;
 }
 
-enum LOG_LEVEL {
-  OFF,
-  WARNING,
-  INFO,
-  DEBUG,
-}
+const LOG_LEVEL = {
+  OFF: 0,
+  WARNING: 1,
+  INFO: 2,
+  DEBUG: 3,
+};
 
 /* istanbul ignore file */
 
@@ -51,71 +53,38 @@ const NODE = {
   logLevel() {
     return (
       // @ts-expect-error ignore
-      global.LOG_LEVEL ??
-      (process.env.NODE_ENV !== "production"
-        ? LOG_LEVEL.DEBUG
-        : LOG_LEVEL.WARNING)
+      (global.LOG_LEVEL as unknown as number) ?? (process.env.NODE_ENV !== "production" ? LOG_LEVEL.DEBUG : LOG_LEVEL.WARNING)
     );
   },
 
-  makeLog(
-    level: string,
-    { process, module, duration, totalTime }: LogDetail = {},
-  ) {
+  makeLog(level: string, { process, module, duration, totalTime }: LogDetail = {}) {
     const ret = [];
     if (process) ret.push(`${this.PROCESS}Process: ${process}${this.RESET}`);
     if (module) ret.push(`${this.PROCESS}Module: ${module}${this.RESET}`);
-    if (duration)
-      ret.push(`${this.DURATION}Duration: ${duration}${this.RESET}`);
-    if (module)
-      ret.push(`${this.DURATION}TotalTime: ${totalTime}${this.RESET}`);
+    if (duration) ret.push(`${this.DURATION}Duration: ${duration}${this.RESET}`);
+    if (module) ret.push(`${this.DURATION}TotalTime: ${totalTime}${this.RESET}`);
 
-    return [
-      `[${this.TIME}${new Date().toISOString()}${this.RESET}] ${level}`,
-      ret.join(" "),
-    ]
-      .filter(Boolean)
-      .join("\n");
+    return [`[${this.TIME}${new Date().toISOString()}${this.RESET}] ${level}`, ret.join(" ")].filter(Boolean).join("\n");
   },
 
   log(msg: string, opts: LogDetail, ...rest: unknown[]) {
     if (+this.logLevel() < LOG_LEVEL.DEBUG) return;
-    console.log(
-      this.makeLog(`${this.LOG}LOG${this.RESET}`, opts),
-      `\n${msg}\n`,
-      ...rest,
-    );
+    console.log(this.makeLog(`${this.LOG}LOG${this.RESET}`, opts), `\n${msg}\n`, ...rest);
   },
   debug(msg: string, opts: LogDetail, ...rest: unknown[]) {
     if (+this.logLevel() < LOG_LEVEL.DEBUG) return;
-    console.debug(
-      this.makeLog(`${this.DEBUG}DEBUG${this.RESET}`, opts),
-      `\n${msg}\n`,
-      ...rest,
-    );
+    console.debug(this.makeLog(`${this.DEBUG}DEBUG${this.RESET}`, opts), `\n${msg}\n`, ...rest);
   },
   info(msg: string, opts: LogDetail, ...rest: unknown[]) {
     if (+this.logLevel() < LOG_LEVEL.INFO) return;
-    console.info(
-      this.makeLog(`${this.INFO}INFO${this.RESET}`, opts),
-      `\n${msg}\n`,
-      ...rest,
-    );
+    console.info(this.makeLog(`${this.INFO}INFO${this.RESET}`, opts), `\n${msg}\n`, ...rest);
   },
   error(msg: string, opts: LogDetail, ...rest: unknown[]) {
-    console.error(
-      this.makeLog(`${this.ERROR}ERROR${this.RESET}`, opts),
-      `\n${msg}\n`,
-      ...rest,
-    );
+    console.error(this.makeLog(`${this.ERROR}ERROR${this.RESET}`, opts), `\n${msg}\n`, ...rest);
   },
   warning(msg: string, opts: LogDetail, ...rest: unknown[]) {
     if (+this.logLevel() < LOG_LEVEL.WARNING) return;
-    console.warn(
-      this.makeLog(`${this.WARNING}WARNING${this.RESET}`, opts),
-      `\n${msg}\n`,
-      ...rest,
-    );
+    console.warn(this.makeLog(`${this.WARNING}WARNING${this.RESET}`, opts), `\n${msg}\n`, ...rest);
   },
 };
 
@@ -132,23 +101,14 @@ const BROWSER = {
   logLevel() {
     return (
       // @ts-expect-error ignore
-      (typeof window !== "undefined" ? window.LOG_LEVEL : undefined) ??
-      (process.env.NODE_ENV !== "production"
-        ? LOG_LEVEL.DEBUG
-        : LOG_LEVEL.WARNING)
+      (typeof window !== "undefined" ? (window.LOG_LEVEL as number) : undefined) ??
+      (process.env.NODE_ENV !== "production" ? LOG_LEVEL.DEBUG : LOG_LEVEL.WARNING)
     );
   },
 
-  makeLog(
-    level: string,
-    color: string,
-    { process, module, duration, totalTime }: LogDetail = {},
-  ) {
+  makeLog(level: string, color: string, { process, module, duration, totalTime }: LogDetail = {}) {
     const ret = [];
-    const colors = [
-      `color:${this.TIME};font-weight:bold;`,
-      `color:${color};font-weight:bold;`,
-    ];
+    const colors = [`color:${this.TIME};font-weight:bold;`, `color:${color};font-weight:bold;`];
     if (module) ret.push(`%cModule: ${module}`);
     if (process) ret.push(`%cProcess: ${process}`);
     if (duration) ret.push(`%cDuration: ${duration}`);
@@ -158,12 +118,7 @@ const BROWSER = {
     if (duration) colors.push(`color:${this.DURATION}`);
     if (module) colors.push(`color:${this.DURATION}`);
 
-    return [
-      [`%c[${new Date().toISOString()}] ${level}`, ret.join(" ")]
-        .filter(Boolean)
-        .join("\n"),
-      colors,
-    ];
+    return [[`%c[${new Date().toISOString()}] ${level}`, ret.join(" ")].filter(Boolean).join("\n"), colors];
   },
 
   log(msg: string, opts: LogDetail, ...rest: unknown[]) {
@@ -198,9 +153,9 @@ const logger = () => {
 };
 
 /**
- * @internal
+ * Returns a logger object with log/debug/info/error/warning methods, adapted for Node or browser. Optionally takes a module name.
  */
-export const useLogger = (mod?: string) => ({
+export const getLogger = (mod?: string) => ({
   timer(process: string) {
     const startTime = new Date().getTime();
     let nextTime = new Date().getTime();
@@ -278,27 +233,23 @@ export const useLogger = (mod?: string) => ({
     };
   },
 
-  log(msg: string, { module = mod, ...opts }: LogDetail, ...rest: unknown[]) {
-    logger()?.log(msg, opts, ...rest);
+  log(msg: string, opts: LogDetail, ...rest: unknown[]) {
+    logger()?.log(msg, { module: mod, ...opts }, ...rest);
   },
 
-  debug(msg: string, { module = mod, ...opts }: LogDetail, ...rest: unknown[]) {
-    logger()?.debug(msg, opts, ...rest);
+  debug(msg: string, opts: LogDetail, ...rest: unknown[]) {
+    logger()?.debug(msg, { module: mod, ...opts }, ...rest);
   },
 
-  info(msg: string, { module = mod, ...opts }: LogDetail, ...rest: unknown[]) {
-    logger()?.info(msg, opts, ...rest);
+  info(msg: string, opts: LogDetail, ...rest: unknown[]) {
+    logger()?.info(msg, { module: mod, ...opts }, ...rest);
   },
 
-  error(msg: string, { module = mod, ...opts }: LogDetail, ...rest: unknown[]) {
-    logger()?.error(msg, opts, ...rest);
+  error(msg: string, opts: LogDetail, ...rest: unknown[]) {
+    logger()?.error(msg, { module: mod, ...opts }, ...rest);
   },
 
-  warning(
-    msg: string,
-    { module = mod, ...opts }: LogDetail,
-    ...rest: unknown[]
-  ) {
-    logger()?.warning(msg, opts, ...rest);
+  warning(msg: string, opts: LogDetail, ...rest: unknown[]) {
+    logger()?.warning(msg, { module: mod, ...opts }, ...rest);
   },
 });

package/src/helpers/lonlat.ts

@@ -0,0 +1,124 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2025 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import { isEmpty } from "../matchers/isEmpty";
+import { isArray, isObject, isString } from "../matchers/typeChecks";
+
+export type LngLatLike =
+  | {
+      lng: number;
+      lat: number;
+    }
+  | {
+      lon: number;
+      lat: number;
+    }
+  | {
+      longitude: number;
+      latitude: number;
+    }
+  | [lon: number | string, lat: number | string]
+  | [lon: number | string, lat: number | string, z: number | string]
+  | string;
+
+/**
+ * Convert a decimal degree coordinate to Degrees, Minutes, Seconds (DMS) format.
+ * Takes a single coordinate value and returns a formatted string with direction
+ * indicators (N/S for latitude, E/W for longitude).
+ *
+ * @param {number} coord - The decimal degree coordinate to convert.
+ * @param {boolean} [isLat=false] - Whether this is a latitude coordinate (affects direction suffix).
+ * @returns {string} A string in the format `"degrees˚minutes'seconds" Direction` (e.g., `"40˚42'51.36"N"`).
+ */
+function convertToDMS(coord: number, isLat = false) {
+  const degree = Math.floor(Math.abs(coord));
+  const hour = (Math.abs(coord) - degree) * 60;
+  const minute = (hour - Math.floor(hour)) * 60;
+
+  return `${degree}˚${Math.floor(hour)}'${minute.toFixed(2)}"${coord < 0 ? (isLat ? "S" : "W") : isLat ? "N" : "E"}`;
+}
+
+/**
+ * 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 function convertToLonLat(lonLat: LngLatLike): [lon: number, lat: number] {
+  if (isEmpty(lonLat)) {
+    throw Error("Invalid geo coordinates");
+  }
+  if ((isArray(lonLat) && lonLat.length === 2) || (isArray(lonLat) && lonLat.length === 3)) {
+    return [Number(lonLat[0]), Number(lonLat[1])];
+  }
+
+  if (isObject(lonLat)) {
+    if ("longitude" in lonLat) {
+      return [lonLat.longitude, lonLat.latitude];
+    }
+    return ["lon" in lonLat ? lonLat.lon : lonLat.lng, lonLat.lat];
+  }
+
+  if (isString(lonLat)) {
+    const [lat, lon] = lonLat.split(",");
+    if (!isNaN(+lat) && !isNaN(+lon)) return [+lon, +lat];
+  }
+
+  throw Error("Invalid geo coordinates");
+}
+
+export function getLatitudeLongitude(lonLat: LngLatLike): { latitude: number; longitude: number } {
+  const [lon, lat] = convertToLonLat(lonLat);
+  return { latitude: lat, longitude: lon };
+}
+
+/**
+ * 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 function getLocationAsText(latlon: LngLatLike) {
+  const [lon, lat] = convertToLonLat(latlon);
+  return `${convertToDMS(lat, true)}, ${convertToDMS(lon)}`;
+}