refactor: update comments and improve code

Author: cyber-hari

src/index.ts

@@ -1,5 +1,5 @@
 export * from "./utils/array.utils";
-export * from "./utils/async.utils.ts";
+export * from "./utils/async.utils";
 export * from "./utils/cache.utils";
 export * from "./utils/context-store.utils";
 export * from "./utils/crypto.utils";
@@ -8,11 +8,12 @@ export * from "./utils/env.utils";
 export * from "./utils/exception.utils";
 export * from "./utils/fs.utils";
 export * from "./utils/http-status-codes";
+export * from "./utils/id.utils";
 export * from "./utils/logger.utils";
 export * from "./utils/obj.utils";
 export * from "./utils/response.utils";
 export * from "./utils/string.utils";
 export * from "./utils/url.utils";
-export * from "./utils/env.utils";
+export * from "./utils/validate.utils";
 
 export * from "./types/api-response";

src/utils/array.utils.ts

@@ -3,35 +3,53 @@ import { getValueByPath } from "./obj.utils";
 /**
  * Splits an array into chunks of the specified size.
  *
- * @param arr - The array to chunk.
- * @param size - The number of elements per chunk.
- * @returns A new array of chunked arrays.
+ * @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 const chunk = <T>(arr: T[], size: number): T[][] => {
-  if (!Array.isArray(arr)) return [];
-  if (size <= 0) throw new Error("Chunk size must be greater than zero");
-  return Array.from({ length: Math.ceil(arr.length / size) }, (_, i) =>
-    arr.slice(i * size, i * size + size),
+export const chunk = <T>(array: T[], size: number): T[][] => {
+  if (!Array.isArray(array)) throw new TypeError("Expected an array");
+  if (!array.length) return [];
+  if (!Number.isInteger(size) || size <= 0)
+    throw new Error("Chunk size must be a positive integer");
+  return Array.from({ length: Math.ceil(array.length / size) }, (_, i) =>
+    array.slice(i * size, i * size + size),
   );
 };
 
 /**
  * Removes duplicate values from an array.
+ * Optionally enforces uniqueness by a key function.
  *
- * @param array - The input array.
- * @returns A new array with unique values.
+ * @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 function unique<T>(array: T[]): T[] {
-  return Array.from(new Set(array));
+export function unique<T>(array: T[], keyFn?: (item: T) => unknown): T[] {
+  if (!Array.isArray(array) || array.length === 0) return [];
+  if (!keyFn) return Array.from(new Set(array));
+  const seen = new Set<unknown>();
+  return array.filter((item) => {
+    const key = keyFn(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
 }
 
 /**
- * Deeply flattens a nested array of arbitrary depth.
+ * Deeply flattens a nested array to a single-level array.
  *
- * @param array - The input nested array.
- * @returns A deeply flattened 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 function flattenDeep<T>(array: any[]): T[] {
+  if (!Array.isArray(array)) return [];
   return array.reduce<T[]>((acc, val) => {
     if (Array.isArray(val)) {
       acc.push(...flattenDeep<T>(val));
@@ -43,45 +61,70 @@ export function flattenDeep<T>(array: any[]): T[] {
 }
 
 /**
- * Returns a random element from an array.
+ * Returns a random element from an array, or undefined if empty.
  *
- * @param array - The input array.
- * @returns A randomly selected item, 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 function random<T>(array: T[]): T | undefined {
-  if (array.length === 0) return undefined;
+  if (!Array.isArray(array) || array.length === 0) return undefined;
   return array[Math.floor(Math.random() * array.length)];
 }
 
+/* eslint-disable no-redeclare */
 /**
- * Groups items in an array by a key selector.
+ * Groups items in an array by a key or key function.
  *
- * @param array - The input array.
- * @param keyFn - A function that returns the key for each item.
- * @returns An object mapping keys to grouped arrays.
+ * @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 function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
 export function groupBy<T, K extends string | number | symbol>(
   array: T[],
   keyFn: (item: T) => K,
-): Record<K, T[]> {
+): Record<K, T[]>;
+export function groupBy<T>(
+  array: T[],
+  keyOrFn: keyof T | ((item: T) => string | number | symbol),
+): Record<string | number | symbol, T[]> {
+  if (!Array.isArray(array) || array.length === 0) return {};
+  const keyFn =
+    typeof keyOrFn === "function"
+      ? keyOrFn
+      : (item: T) => item[keyOrFn as keyof T];
   return array.reduce(
     (acc, item) => {
-      const key = keyFn(item);
+      const key = keyFn(item) as string | number | symbol;
       if (!acc[key]) acc[key] = [];
       acc[key].push(item);
       return acc;
     },
-    {} as Record<K, T[]>,
+    {} as Record<string | number | symbol, T[]>,
   );
 }
+/* eslint-enable no-redeclare */
 
 /**
  * Shuffles an array using the Fisher-Yates algorithm.
  *
- * @param array - The input array.
- * @returns A new shuffled array.
+ * @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 function shuffle<T>(array: T[]): T[] {
+  if (!Array.isArray(array)) throw new TypeError("Expected an array");
   const copy = array.slice();
   for (let i = copy.length - 1; i > 0; i--) {
     const j = Math.floor(Math.random() * (i + 1));
@@ -91,81 +134,98 @@ export function shuffle<T>(array: T[]): T[] {
 }
 
 /**
- * Returns values in A that are not in B.
+ * Returns an array of property values from an array of objects.
  *
- * @param a - First array.
- * @param b - Second array.
- * @returns Elements in A that are not in B.
+ * @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 function pluck<T, K extends keyof T>(array: T[], key: K): T[K][] {
+  if (!Array.isArray(array)) return [];
+  return array.map((item) => item[key]);
+}
+
+/**
+ * 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 function difference<T>(a: T[], b: T[]): T[] {
+  if (!Array.isArray(a) || !Array.isArray(b)) return [];
   const setB = new Set(b);
   return a.filter((item) => !setB.has(item));
 }
 
 /**
- * Returns common values between A and B.
+ * Returns common values between arrays A and B.
  *
- * @param a - First array.
- * @param b - Second array.
- * @returns Elements that exist in both arrays.
+ * @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 function intersect<T>(a: T[], b: T[]): T[] {
+  if (!Array.isArray(a) || !Array.isArray(b)) return [];
   const setB = new Set(b);
   return a.filter((item) => setB.has(item));
 }
 
 /**
  * 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 - Object type of the array elements.
- * @param array - Array of objects to sort.
- * @param key - Dot-notated key to sort by (e.g. 'profile.age').
- * @param direction - Sort direction: 'asc' or 'desc'.
- * @returns A new sorted array.
+ * @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 function mergeSort<T extends object>(
+export function mergeSort<T>(
   array: T[],
-  key: string,
+  key: string | ((item: T) => any),
   direction: "asc" | "desc" = "asc",
 ): T[] {
+  if (!Array.isArray(array)) throw new TypeError("Expected array");
   if (array.length <= 1) return array.slice();
 
-  const compare = (a: T, b: T) => {
-    const aVal = getValueByPath(a, key);
-    const bVal = getValueByPath(b, key);
+  const keyFn =
+    typeof key === "function"
+      ? key
+      : (item: T) => getValueByPath(item as object, key);
 
+  const compare = (a: T, b: T) => {
+    const aVal = keyFn(a);
+    const bVal = keyFn(b);
+    // Sorts undefined/null last for "asc", first for "desc"
     if (aVal === bVal) return 0;
-    if (aVal == null) return 1;
-    if (bVal == null) return -1;
-
+    if (aVal == null) return direction === "asc" ? 1 : -1;
+    if (bVal == null) return direction === "asc" ? -1 : 1;
     return direction === "asc" ? (aVal < bVal ? -1 : 1) : aVal > bVal ? -1 : 1;
   };
 
   const merge = (left: T[], right: T[]): T[] => {
     const result: T[] = [];
     let i = 0,
       j = 0;
-
     while (i < left.length && j < right.length) {
-      if (compare(left[i], right[j]) <= 0) {
-        result.push(left[i++]);
-      } else {
-        result.push(right[j++]);
-      }
+      if (compare(left[i], right[j]) <= 0) result.push(left[i++]);
+      else result.push(right[j++]);
     }
-
     return result.concat(left.slice(i)).concat(right.slice(j));
   };
 
   const sort = (arr: T[]): T[] => {
     if (arr.length <= 1) return arr;
-
     const mid = Math.floor(arr.length / 2);
     const left = sort(arr.slice(0, mid));
     const right = sort(arr.slice(mid));
-
     return merge(left, right);
   };
-
   return sort(array);
 }