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

package/dist/cjs/_isType.js

@@ -25,15 +25,46 @@ var _typeof = require('@babel/runtime/helpers/typeof');
  * 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.
+ */
 var isUndefined = function isUndefined(value) {
   return value === undefined;
 };
+
+/**
+ * Check if a value is null.
+ * @param value - The value to check.
+ * @returns true if the value is null, false otherwise.
+ */
 var isNull = function isNull(value) {
   return value === null;
 };
+
+/**
+ * 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.
+ */
 var isNil = function isNil(val) {
   return val === undefined || val === null;
 };
+
+/**
+ * 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.
+ */
 var isEmpty = function isEmpty(val) {
   if (val instanceof Date) return false;
   if (isNil(val) || val === "") {
@@ -48,36 +79,126 @@ var isEmpty = function isEmpty(val) {
   }
   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.
+ */
 var isObject = function isObject(val) {
   return !isNil(val) && !(val instanceof Date) && _typeof(val) === "object" && !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.
+ */
 var isArray = function isArray(val) {
   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.
+ */
 var isString = function isString(value) {
   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.
+ */
 var isNumber = function isNumber(value) {
   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'
+ */
 var isBoolean = function isBoolean(value) {
   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)
+ */
 var isTrue = function isTrue() {
   var value = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "";
   return value === true || value === 1 || (value === null || value === void 0 ? void 0 : value.toString().toLowerCase()) === "yes" || (value === null || value === void 0 ? void 0 : 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)
+ */
 var isFalse = function isFalse() {
   var value = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "";
   return value === false || value === 0 || (value === null || value === void 0 ? void 0 : value.toString().toLowerCase()) === "no" || (value === null || value === void 0 ? void 0 : value.toString().toLowerCase()) === "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.
+ */
 var isColor = function isColor(color) {
   var _color$startsWith, _color$startsWith2, _color$startsWith3, _color$startsWith4;
   return ((_color$startsWith = color.startsWith) === null || _color$startsWith === void 0 ? void 0 : _color$startsWith.call(color, "#")) || ((_color$startsWith2 = color.startsWith) === null || _color$startsWith2 === void 0 ? void 0 : _color$startsWith2.call(color, "rgb")) || ((_color$startsWith3 = color.startsWith) === null || _color$startsWith3 === void 0 ? void 0 : _color$startsWith3.call(color, "hsl")) || ((_color$startsWith4 = color.startsWith) === null || _color$startsWith4 === void 0 ? void 0 : _color$startsWith4.call(color, "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.
+ */
 var isSvgPath = function isSvgPath(value) {
   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.
+ */
 var isRtl = function isRtl() {
   return getComputedStyle(document.documentElement).direction === "rtl";
 };

package/dist/cjs/_lonlat.js

@@ -0,0 +1,87 @@
+'use strict';
+
+var _slicedToArray = require('@babel/runtime/helpers/slicedToArray');
+var _isType = require('./_isType.js');
+
+/**
+ * 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.
+ */
+var convertLatLng = function convertLatLng(lonLat) {
+  if (_isType.isArray(lonLat) && lonLat.length === 2 || _isType.isArray(lonLat) && lonLat.length === 3) {
+    return [Number(lonLat[0]), Number(lonLat[1])];
+  }
+  if (_isType.isObject(lonLat)) {
+    if ("longitude" in lonLat) {
+      return [lonLat.longitude, lonLat.latitude];
+    }
+    return ["lon" in lonLat ? lonLat.lon : lonLat.lng, lonLat.lat];
+  }
+  if (_isType.isString(lonLat)) {
+    var _lonLat$split = lonLat.split(","),
+      _lonLat$split2 = _slicedToArray(_lonLat$split, 2),
+      _lat = _lonLat$split2[0],
+      _lon = _lonLat$split2[1];
+    return [+_lon, +_lat];
+  }
+  throw Error("Invalid geo coordinates");
+};
+
+/**
+ * Convert a coordinate to Degrees, Minutes, Seconds (DMS) format.
+ * This function takes a coordinate and returns a string in the format "degrees˚minutes'seconds" with direction (N/S or E/W).
+ * It handles both latitude and longitude coordinates.
+ * This function assumes that the input coordinate is in decimal degrees format.
+ * It converts the coordinate to DMS format by calculating the degrees, minutes, and seconds,
+ * and then formatting the result as a string.
+ *
+ * @param {number} coord - The coordinate to convert.
+ * @param {boolean} isLat - Whether the coordinate is latitude (default is false for longitude).
+ * @returns {string} A string representation of the coordinate in DMS format.
+ */
+var convertToDMS = function convertToDMS(coord) {
+  var isLat = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  var degree = Math.floor(coord);
+  var hour = (coord - degree) * 60;
+  var minute = (hour - Math.floor(hour)) * 60;
+  return "".concat(degree, "\u02DA").concat(Math.floor(hour), "'").concat(minute.toFixed(2), "\"").concat(coord < 0 ? isLat ? "S" : "W" : isLat ? "N" : "E");
+};
+
+/**
+ * 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"
+ * ```
+ */
+var getLocationAsText = function getLocationAsText(latlon) {
+  var _convertLatLng = convertLatLng(latlon),
+    _convertLatLng2 = _slicedToArray(_convertLatLng, 2),
+    lon = _convertLatLng2[0],
+    lat = _convertLatLng2[1];
+  return "".concat(convertToDMS(lat, true), ", ").concat(convertToDMS(lon));
+};
+
+exports.convertLatLng = convertLatLng;
+exports.getLocationAsText = getLocationAsText;

package/dist/cjs/_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/cjs/_tokenize.js

@@ -27,10 +27,14 @@ var _isType = require('./_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 (_isType.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/cjs/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/cjs/index.js

@@ -13,6 +13,7 @@ var _hash = require('./_hash.js');
 var _interpolate = require('./_interpolate.js');
 var _isEqual = require('./_isEqual.js');
 var _isType = require('./_isType.js');
+var _lonlat = require('./_lonlat.js');
 var _mergeRefs = require('./_mergeRefs.js');
 var _tokenize = require('./_tokenize.js');
 var getImageColorset = require('./getImageColorset.js');
@@ -106,6 +107,8 @@ exports.isString = _isType.isString;
 exports.isSvgPath = _isType.isSvgPath;
 exports.isTrue = _isType.isTrue;
 exports.isUndefined = _isType.isUndefined;
+exports.convertLatLng = _lonlat.convertLatLng;
+exports.getLocationAsText = _lonlat.getLocationAsText;
 exports.mergeRefs = _mergeRefs.mergeRefs;
 exports.iconToken = _tokenize.iconToken;
 exports.tokenize = _tokenize.tokenize;

package/dist/cjs/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/esm/_ascii.js

@@ -1,8 +1,31 @@
 'use client';
 
-import _slicedToArray from '@babel/runtime/helpers/slicedToArray';
 import { isEmpty } from './_isType.js';
 
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * 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:
+ *
+ * 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.
+ */
+
+
 /** ***************** latin-ascii conversions *******************/
 var conversions = {
   AE: "Æ|Ǽ",
@@ -58,17 +81,19 @@ var 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.
  */
 var ascii = function ascii(str) {
   if (isEmpty(str)) return "";
-  Object.entries(conversions).forEach(function (_ref) {
-    var _ref2 = _slicedToArray(_ref, 2),
-      a = _ref2[0],
-      l = _ref2[1];
-    var re = new RegExp(l, "g");
-    str = "".concat(str).replace(re, a);
+  Object.entries(conversions).forEach(function (entry) {
+    var re = new RegExp(entry[1], "g");
+    str = "".concat(str).replace(re, entry[0]);
   });
   return str;
 };

package/dist/esm/_boundingBox.js

@@ -18,8 +18,13 @@ var _getBox = function _getBox(box) {
 };
 
 /**
- * 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]
  */
 var getBox = function getBox() {
   var box = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "0,0,0,0";
@@ -37,8 +42,15 @@ var getBox = function 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]
  */
 var getBoundingBox = function getBoundingBox() {
   var box = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "0,0,0,0";

package/dist/esm/_countries.js

@@ -26,32 +26,42 @@
 /* istanbul ignore file */
 
 /**
- * @internal
+ * Country interface
  */
 
 /**
- * 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[]}
  */
 var Countries = {
   /**
-   * 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: function toIso2(code) {
     var 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: function toIso3(code) {
     var 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: function emoji(code) {
     var ctry = this.find(code);
@@ -59,25 +69,25 @@ var Countries = {
   },
   /**
    * 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 name(code) {
     var 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: function find(code) {
     return this.list.find(function (ct) {
@@ -85,6 +95,14 @@ var Countries = {
       return ((_ct$alt = ct.alt) !== null && _ct$alt !== void 0 ? _ct$alt : "__").toLowerCase() === code.toLowerCase() || ct.iso3.toLowerCase() === code.toLowerCase() || 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",
     iso2: "AF",

package/dist/esm/_debounce.js

@@ -26,8 +26,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.
  */
 var debounce = function debounce(fn) {
   var timeout = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 500;

package/dist/esm/_dedupe.js

@@ -25,6 +25,18 @@ import { isEmpty } from './_isType.js';
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+
+/**
+ * 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.
+ */
 var dedupe = function dedupe(list, key) {
   var filtered = list.filter(function (i) {
     return !isEmpty(i);
@@ -33,20 +45,54 @@ var dedupe = function dedupe(list, key) {
     return Array.from(new Set(filtered).values());
   }
   return Array.from(new Map(filtered.map(function (obj) {
-    var _obj$key;
-    return [(_obj$key = obj[key]) !== null && _obj$key !== void 0 ? _obj$key : obj, obj];
+    return [obj[key], obj];
   })).values());
 };
+
+/**
+ * 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.
+ */
 var flatten = function flatten(list) {
   return list.flat(5).filter(function (i) {
     return !isEmpty(i);
   });
 };
+
+/**
+ * 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.
+ */
 var flattenAndDedupe = function flattenAndDedupe() {
   var list = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
   var key = arguments.length > 1 ? arguments[1] : undefined;
   return dedupe(flatten(list), 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.
+ */
 var groupBy = function groupBy(list, prop, missingKey) {
   return list.reduce(function (r, i) {
     var _i$prop;