@catbee/utils 2.0.0-next.0 → 2.0.0

package/{validate/validate.utils.d.ts → validation/index.d.ts}

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -31,63 +31,64 @@
  * @param str - The input string or number.
  * @returns True if valid port number, else false.
  */
-export declare function isPort(value: string | number): boolean;
+declare function isPort(value: string | number): boolean;
 /**
  * Checks if a string is a valid email address.
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if valid email, else false.
  */
-export declare function isEmail(str: string): boolean;
+declare function isEmail(str: string): boolean;
 /**
  * Checks if a string is a valid UUID (versions 1-5).
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if valid UUID, else false.
  */
-export declare function isUUID(str: string): boolean;
+declare function isUUID(str: string): boolean;
 /**
  * Checks if a string is a valid URL.
  *
  * @param {string} str - The input string.
+ * @param {string[]} [allowedProtocols=['http', 'https', 'ws', 'wss']] - Allowed URL protocols.
  * @returns {boolean} True if valid URL, else false.
  */
-export declare function isURL(str: string): boolean;
+declare function isURL(str: string, allowedProtocols?: string[]): boolean;
 /**
  * Checks if a string is a valid international phone number (E.164 or common patterns).
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if looks like a phone number.
  */
-export declare function isPhone(str: string): boolean;
+declare function isPhone(str: string): boolean;
 /**
  * Checks if a string is strictly alphanumeric (letters/numbers only).
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if alphanumeric.
  */
-export declare function isAlphanumeric(str: string): boolean;
+declare function isAlphanumeric(str: string): boolean;
 /**
  * Checks if a string or number can be safely parsed to a number.
  *
  * @param {string | number} value - The value to check.
  * @returns {boolean} True if the value is numeric.
  */
-export declare function isNumeric(value: string | number): boolean;
+declare function isNumeric(value: string | number): boolean;
 /**
  * Checks if a string is a valid hex color code (e.g. #FFF or #FFFFFF).
  *
  * @param {string} str - Input string.
  * @returns {boolean}
  */
-export declare function isHexColor(str: string): boolean;
+declare function isHexColor(str: string): boolean;
 /**
  * Checks if a string is a valid date string.
  *
  * @param {string} str - Input string.
  * @returns {boolean}
  */
-export declare function isISODate(str: string): boolean;
+declare function isISODate(str: string): boolean;
 /**
  * Checks if a string matches a specified length range.
  *
@@ -96,7 +97,7 @@ export declare function isISODate(str: string): boolean;
  * @param {number} max - Maximum length (inclusive).
  * @returns {boolean} True if string length is within range.
  */
-export declare function isLengthBetween(str: string, min: number, max: number): boolean;
+declare function isLengthBetween(str: string, min: number, max: number): boolean;
 /**
  * Validates that a number is between specified min and max values (inclusive).
  *
@@ -105,50 +106,56 @@ export declare function isLengthBetween(str: string, min: number, max: number):
  * @param {number} max - Maximum value.
  * @returns {boolean} True if number is within range.
  */
-export declare function isNumberBetween(value: number, min: number, max: number): boolean;
+declare function isNumberBetween(value: number, min: number, max: number): boolean;
 /**
  * Checks if a string contains only alphabetic characters.
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if alphabetic only.
  */
-export declare function isAlpha(str: string): boolean;
+declare function isAlpha(str: string): boolean;
 /**
  * Validates that a string contains at least one uppercase letter,
  * one lowercase letter, one number, and one special character.
  *
+ * - Minimum length of 8 characters.
+ * - At least one uppercase letter (A-Z).
+ * - At least one lowercase letter (a-z).
+ * - At least one digit (0-9).
+ * - At least one special character e.g. !@#$%^&*()_+-=[]{};':"\\|,.<>?/
+ *
  * @param {string} str - The input string.
  * @returns {boolean} True if string meets password complexity requirements.
  */
-export declare function isStrongPassword(str: string): boolean;
+declare function isStrongPassword(str: string): boolean;
 /**
  * Checks if a string is a valid IPv4 address.
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if valid IPv4 address.
  */
-export declare function isIPv4(str: string): boolean;
+declare function isIPv4(str: string): boolean;
 /**
  * Checks if a string is a valid IPv6 address.
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if valid IPv6 address.
  */
-export declare function isIPv6(str: string): boolean;
+declare function isIPv6(str: string): boolean;
 /**
  * Validates a credit card number using the Luhn algorithm.
  *
  * @param {string} str - The credit card number string.
  * @returns {boolean} True if valid credit card number.
  */
-export declare function isCreditCard(str: string): boolean;
+declare function isCreditCard(str: string): boolean;
 /**
  * Checks if a string is a valid JSON.
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if valid JSON.
  */
-export declare function isValidJSON(str: string): boolean;
+declare function isValidJSON(str: string): boolean;
 /**
  * Type guard that checks if a value is an array.
  *
@@ -157,14 +164,14 @@ export declare function isValidJSON(str: string): boolean;
  * @param {(item: unknown) => boolean} [itemGuard] - Optional function to validate each item.
  * @returns {boolean} True if value is an array (with optional item validation).
  */
-export declare function isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[];
+declare function isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[];
 /**
  * Checks if a string is a valid base64 encoded string.
  *
  * @param {string} str - The input string.
  * @returns {boolean} True if valid base64.
  */
-export declare function isBase64(str: string): boolean;
+declare function isBase64(str: string): boolean;
 /**
  * Validates that an object has all required properties.
  *
@@ -172,7 +179,7 @@ export declare function isBase64(str: string): boolean;
  * @param {string[]} requiredProps - Array of required property names.
  * @returns {boolean} True if all required properties exist.
  */
-export declare function hasRequiredProps(obj: Record<string, unknown>, requiredProps: string[]): boolean;
+declare function hasRequiredProps(obj: Record<string, unknown>, requiredProps: string[]): boolean;
 /**
  * Validates a date is within a specified range.
  *
@@ -181,7 +188,7 @@ export declare function hasRequiredProps(obj: Record<string, unknown>, requiredP
  * @param {Date} [maxDate] - Optional maximum date (inclusive).
  * @returns {boolean} True if date is within range.
  */
-export declare function isDateInRange(date: Date, minDate?: Date, maxDate?: Date): boolean;
+declare function isDateInRange(date: Date, minDate?: Date, maxDate?: Date): boolean;
 /**
  * Validates a string matches a specific regular expression pattern.
  *
@@ -189,7 +196,7 @@ export declare function isDateInRange(date: Date, minDate?: Date, maxDate?: Date
  * @param {RegExp} pattern - Regular expression to test against.
  * @returns {boolean} True if string matches pattern.
  */
-export declare function matchesPattern(str: string, pattern: RegExp): boolean;
+declare function matchesPattern(str: string, pattern: RegExp): boolean;
 /**
  * Validates data against multiple constraints.
  *
@@ -197,4 +204,6 @@ export declare function matchesPattern(str: string, pattern: RegExp): boolean;
  * @param {Array<(value: unknown) => boolean>} validators - Array of validation functions.
  * @returns {boolean} True if value passes all validations.
  */
-export declare function validateAll(value: unknown, validators: Array<(value: unknown) => boolean>): boolean;
+declare function validateAll(value: unknown, validators: Array<(value: unknown) => boolean>): boolean;
+
+export { hasRequiredProps, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isEmail, isHexColor, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isPhone, isPort, isStrongPassword, isURL, isUUID, isValidJSON, matchesPattern, validateAll };

package/{validate → validation}/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -22,25 +22,37 @@
  * SOFTWARE.
  */
 
+import net from 'net';
+
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-
-// src/validate/validate.utils.ts
+var PORT_REGEX = /^[0-9]{1,5}$/;
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var PHONE_ALLOWED_CHARS_REGEX = /^[+]?[0-9\s().-]+$/;
+var ALPHANUMERIC_REGEX = /^[A-Za-z0-9]+$/;
+var HEX_COLOR_REGEX = /^#([a-f0-9]{6}|[a-f0-9]{3})$/i;
+var ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/;
+var BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+var DOT_ATOM_REGEX = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
+var QUOTED_LOCAL_REGEX = /^"([\s\x21\x23-\x5B\x5D-\x7E]|\\[\x20-\x7E])*"$/;
+var TLD_REGEX = /^[A-Za-z]{2,63}$/;
 function isPort(value) {
-  const port = typeof value === "string" ? Number(value.trim()) : value;
+  if (typeof value === "number") return Number.isInteger(value) && value > 0 && value <= 65535;
+  if (!value || typeof value !== "string") return false;
+  const str = value.trim();
+  if (!PORT_REGEX.test(str)) return false;
+  const port = Number(str);
   return Number.isInteger(port) && port > 0 && port <= 65535;
 }
 __name(isPort, "isPort");
 function isEmail(str) {
-  if (typeof str !== "string" || str.length > 254) return false;
+  if (!str || typeof str !== "string" || str.length > 254) return false;
   const atIndex = str.indexOf("@");
   if (atIndex === -1 || atIndex !== str.lastIndexOf("@")) return false;
   const local = str.slice(0, atIndex);
   const domain = str.slice(atIndex + 1);
   if (!local || !domain) return false;
-  const dotAtom = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
-  const quotedLocal = /^"([\s\x21\x23-\x5B\x5D-\x7E]|\\[\x20-\x7E])*"$/;
-  if (!dotAtom.test(local) && !quotedLocal.test(local)) return false;
+  if (!DOT_ATOM_REGEX.test(local) && !QUOTED_LOCAL_REGEX.test(local)) return false;
   if (domain.includes("..")) return false;
   const labels = domain.split(".");
   if (labels.some((l) => !l.length)) return false;
@@ -50,61 +62,75 @@ function isEmail(str) {
     if (!labelRegex.test(label)) return false;
     if (label.startsWith("-") || label.endsWith("-")) return false;
   }
-  const tld = labels[labels.length - 1];
-  if (!/^[A-Za-z]{2,63}$/.test(tld)) return false;
+  const tld = labels.at(-1) || "";
+  if (!TLD_REGEX.test(tld)) return false;
   return true;
 }
 __name(isEmail, "isEmail");
 function isUUID(str) {
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(str);
+  return UUID_REGEX.test(str);
 }
 __name(isUUID, "isUUID");
-function isURL(str) {
+function isURL(str, allowedProtocols = [
+  "http",
+  "https",
+  "ws",
+  "wss"
+]) {
+  if (!str || typeof str !== "string") return false;
   try {
-    new URL(str);
-    return true;
+    const url = new URL(str);
+    return allowedProtocols.includes(url.protocol.replace(":", ""));
   } catch {
     return false;
   }
 }
 __name(isURL, "isURL");
 function isPhone(str) {
-  if (typeof str !== "string") return false;
-  const digitsOnly = str.replace(/\D/g, "");
-  if (digitsOnly.length < 6 || digitsOnly.length > 15) return false;
-  return /^[+]?[\d\s().-]+$/.test(str);
+  if (!str || typeof str !== "string") return false;
+  const digits = str.replace(/\D/g, "");
+  if (digits.length < 6 || digits.length > 15) return false;
+  return PHONE_ALLOWED_CHARS_REGEX.test(str);
 }
 __name(isPhone, "isPhone");
 function isAlphanumeric(str) {
-  return /^[a-z0-9]+$/i.test(str);
+  if (!str || typeof str !== "string") return false;
+  return ALPHANUMERIC_REGEX.test(str);
 }
 __name(isAlphanumeric, "isAlphanumeric");
 function isNumeric(value) {
-  if (typeof value === "string" && value.trim() === "") return false;
-  const num = typeof value === "number" ? value : Number(value);
-  return typeof num === "number" && isFinite(num);
+  if (typeof value === "number") return Number.isFinite(value);
+  if (!value || typeof value !== "string") return false;
+  const str = value.trim();
+  if (str === "" || str.length > 16) return false;
+  const num = Number(str);
+  return Number.isFinite(num);
 }
 __name(isNumeric, "isNumeric");
 function isHexColor(str) {
-  return /^#([a-f0-9]{6}|[a-f0-9]{3})$/i.test(str);
+  if (!str || typeof str !== "string") return false;
+  return HEX_COLOR_REGEX.test(str);
 }
 __name(isHexColor, "isHexColor");
 function isISODate(str) {
-  const isoRegex = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/;
-  if (!isoRegex.test(str)) return false;
+  if (!str || typeof str !== "string") return false;
+  if (!ISO_DATE_REGEX.test(str)) return false;
   const date = new Date(str);
-  return !isNaN(date.getTime()) && date.toISOString().startsWith(str.slice(0, 10));
+  return !Number.isNaN(date.getTime());
 }
 __name(isISODate, "isISODate");
 function isLengthBetween(str, min, max) {
+  if (typeof str !== "string") return false;
   return str.length >= min && str.length <= max;
 }
 __name(isLengthBetween, "isLengthBetween");
 function isNumberBetween(value, min, max) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return false;
   return value >= min && value <= max;
 }
 __name(isNumberBetween, "isNumberBetween");
 function isAlpha(str) {
+  if (!str || typeof str !== "string") return false;
   return /^[a-zA-Z]+$/.test(str);
 }
 __name(isAlpha, "isAlpha");
@@ -118,36 +144,43 @@ function isStrongPassword(str) {
 }
 __name(isStrongPassword, "isStrongPassword");
 function isIPv4(str) {
+  if (!str || typeof str !== "string") return false;
   const parts = str.split(".");
   if (parts.length !== 4) return false;
-  return parts.every((part) => {
-    const num = parseInt(part, 10);
-    return part === num.toString() && num >= 0 && num <= 255;
+  return parts.every((p) => {
+    if (p.length > 3 || p.startsWith("0") && p.length > 1) return false;
+    const n = Number(p);
+    return Number.isInteger(n) && n >= 0 && n <= 255;
   });
 }
 __name(isIPv4, "isIPv4");
 function isIPv6(str) {
-  return /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]+|::(ffff(:0{1,4})?:)?((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9]))$/.test(str);
+  if (!str || typeof str !== "string" || str.length > 45) return false;
+  try {
+    return net.isIP(str) === 6;
+  } catch {
+    return false;
+  }
 }
 __name(isIPv6, "isIPv6");
 function isCreditCard(str) {
-  const cardNumber = str.replace(/\D/g, "");
-  if (cardNumber.length < 13 || cardNumber.length > 19) return false;
+  if (!str || typeof str !== "string") return false;
+  const s = str.replace(/\D/g, "");
+  if (s.length < 13 || s.length > 19) return false;
   let sum = 0;
-  let shouldDouble = false;
-  for (let i = cardNumber.length - 1; i >= 0; i--) {
-    let digit = parseInt(cardNumber.charAt(i), 10);
-    if (shouldDouble) {
-      digit *= 2;
-      if (digit > 9) digit -= 9;
+  for (let i = 0, dbl = false; i < s.length; i++, dbl = !dbl) {
+    let d = s.charCodeAt(s.length - 1 - i) - 48;
+    if (dbl) {
+      d *= 2;
+      if (d > 9) d -= 9;
     }
-    sum += digit;
-    shouldDouble = !shouldDouble;
+    sum += d;
   }
   return sum % 10 === 0;
 }
 __name(isCreditCard, "isCreditCard");
 function isValidJSON(str) {
+  if (!str || typeof str !== "string") return false;
   try {
     JSON.parse(str);
     return true;
@@ -162,26 +195,36 @@ function isArray(value, itemGuard) {
 }
 __name(isArray, "isArray");
 function isBase64(str) {
-  return /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(str);
+  if (!str || typeof str !== "string") return false;
+  return BASE64_REGEX.test(str);
 }
 __name(isBase64, "isBase64");
 function hasRequiredProps(obj, requiredProps) {
-  return requiredProps.every((prop) => Object.prototype.hasOwnProperty.call(obj, prop) && obj[prop] !== void 0 && obj[prop] !== null);
+  if (!obj || typeof obj !== "object") return false;
+  return requiredProps.every((prop) => Object.hasOwn(obj, prop) && obj[prop] != null);
 }
 __name(hasRequiredProps, "hasRequiredProps");
 function isDateInRange(date, minDate, maxDate) {
-  if (!(date instanceof Date) || isNaN(date.getTime())) return false;
+  if (!(date instanceof Date) || !Number.isFinite(date.getTime())) return false;
   if (minDate && date < minDate) return false;
   if (maxDate && date > maxDate) return false;
   return true;
 }
 __name(isDateInRange, "isDateInRange");
 function matchesPattern(str, pattern) {
+  if (typeof str !== "string") return false;
   return pattern.test(str);
 }
 __name(matchesPattern, "matchesPattern");
 function validateAll(value, validators) {
-  return validators.every((validator) => validator(value));
+  if (!Array.isArray(validators)) return false;
+  return validators.every((fn) => {
+    try {
+      return fn(value);
+    } catch {
+      return false;
+    }
+  });
 }
 __name(validateAll, "validateAll");
 

package/array/array.utils.d.ts

@@ -1,191 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
- * 
- * 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.
- */
-
-/**
- * Splits an array into chunks of the specified size.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The array to split into chunks.
- * @param {number} size - The number of elements per chunk.
- * @returns {T[][]} A new array containing chunked arrays.
- * @throws {TypeError} If array is not an array.
- * @throws {Error} If chunk size is not a positive integer.
- */
-export declare function chunk<T>(array: readonly T[], size: number): T[][];
-/**
- * Removes duplicate values from an array.
- * Optionally enforces uniqueness by a key function.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T) => unknown} [keyFn] - Optional function to determine uniqueness by key.
- * @returns {T[]} A new array with unique values.
- */
-export declare function unique<T>(array: readonly T[], keyFn?: (item: T) => unknown): T[];
-/**
- * Deeply flattens a nested array to a single-level array.
- *
- * @template T The leaf type of array elements.
- * @param {any[]} array - The (possibly deeply nested) input array.
- * @returns {T[]} A deeply flattened array.
- */
-export declare function flattenDeep<T>(array: unknown[]): T[];
-/**
- * Returns a random element from an array, or undefined if empty.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @returns {T | undefined} A randomly selected item, or undefined if array is empty or not an array.
- */
-export declare function random<T>(array: readonly T[]): T | undefined;
-/**
- * Groups items in an array by a key or key function.
- *
- * @template T The type of array elements.
- * @overload
- * @param {T[]} array - The array to group.
- * @param {keyof T} key - Property key to group by.
- * @returns {Record<string, T[]>}
- * @overload
- * @param {T[]} array - The array to group.
- * @param {(item: T) => string | number | symbol} keyFn - Function to generate group key from item.
- * @returns {Record<K, T[]>}
- * @param {T[]} array - The array to group.
- * @param {keyof T | ((item: T) => string | number | symbol)} keyOrFn - Property key or key-generating function.
- * @returns {Record<string | number | symbol, T[]>} An object mapping group keys to item arrays.
- */
-export declare function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
-export declare function groupBy<T, K extends string | number | symbol>(array: T[], keyFn: (item: T) => K): Record<K, T[]>;
-/**
- * Shuffles an array using the Fisher-Yates algorithm.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @returns {T[]} A new shuffled array.
- * @throws {TypeError} If array is not an array.
- */
-export declare function shuffle<T>(array: T[]): T[];
-/**
- * Returns an array of property values from an array of objects.
- *
- * @template T The type of array elements.
- * @template K The object property to pluck.
- * @param {T[]} array - The input array.
- * @param {K} key - The property name to pluck.
- * @returns {T[K][]} Array of property values.
- */
-export declare function pluck<T, K extends keyof T>(array: readonly T[], key: K): T[K][];
-/**
- * Returns values in array A that are not in array B.
- *
- * @template T The type of array elements.
- * @param {T[]} a - First array.
- * @param {T[]} b - Second array.
- * @returns {T[]} Elements in A that are not in B.
- */
-export declare function difference<T>(a: readonly T[], b: readonly T[]): T[];
-/**
- * Returns common values between arrays A and B.
- *
- * @template T The type of array elements.
- * @param {T[]} a - First array.
- * @param {T[]} b - Second array.
- * @returns {T[]} Elements that exist in both arrays.
- */
-export declare function intersect<T>(a: readonly T[], b: readonly T[]): T[];
-/**
- * Sorts an array of objects by a nested key using Merge Sort (O(n log n)).
- * Missing/undefined keys are sorted to the "end" (asc) or "start" (desc).
- *
- * @template T The type of array elements (objects).
- * @param {T[]} array - Array of objects to sort.
- * @param {string | ((item: T) => any)} key - Dot-notated key (e.g., "profile.age") or function.
- * @param {"asc" | "desc"} [direction="asc"] - Sort direction: 'asc' or 'desc'.
- * @returns {T[]} A new sorted array.
- * @throws {TypeError} If array is not an array.
- */
-export declare function mergeSort<T>(array: T[], key: string | ((item: T) => any), direction?: 'asc' | 'desc'): T[];
-/**
- * Combines multiple arrays into a single array of grouped elements.
- * Output array length equals the length of the shortest input array.
- *
- * @example zip([1, 2], ['a', 'b']) => [[1, 'a'], [2, 'b']]
- * @param {...Array<T>[]} arrays - Two or more arrays to zip together.
- * @returns {Array<T[]>} Array of grouped elements.
- */
-export declare function zip<T>(...arrays: ReadonlyArray<T>[]): T[][];
-/**
- * Splits an array into two arrays based on a predicate function.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T, index: number, array: T[]) => boolean} predicate - Function to test each element.
- * @returns {[T[], T[]]} A tuple of two arrays: [matched, unmatched].
- */
-export declare function partition<T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): [T[], T[]];
-/**
- * Generates an array of numbers within a specified range.
- *
- * @param {number} start - Start of range (inclusive).
- * @param {number} end - End of range (exclusive).
- * @param {number} [step=1] - Step between numbers.
- * @returns {number[]} Array of numbers in range.
- */
-export declare function range(start: number, end: number, step?: number): number[];
-/**
- * Returns the first n elements of an array.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {number} [n=1] - Number of elements to take.
- * @returns {T[]} New array with first n elements.
- */
-export declare function take<T>(array: T[], n?: number): T[];
-/**
- * Takes elements from the array while predicate returns true.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T, index: number) => boolean} predicate - Function to test each element.
- * @returns {T[]} New array with taken elements.
- */
-export declare function takeWhile<T>(array: T[], predicate: (item: T, index: number) => boolean): T[];
-/**
- * Removes all falsy values from an array.
- * False, null, 0, "", undefined, and NaN are falsy.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @returns {NonNullable<T>[]} New array with falsy values removed.
- */
-export declare function compact<T>(array: T[]): NonNullable<T>[];
-/**
- * Counts array elements by a key function.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T) => string | number | symbol} keyFn - Function to generate count key.
- * @returns {Record<string, number>} Object with counts by key.
- */
-export declare function countBy<T>(array: T[], keyFn: (item: T) => string | number | symbol): Record<string, number>;