es-toolkit 0.0.1 → 1.0.0-dev.24

package/dist/index.js

@@ -2,6 +2,219 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+/**
+ * Splits an array into smaller arrays of a specified length.
+ *
+ * This function takes an input array and divides it into multiple smaller arrays,
+ * each of a specified length. If the input array cannot be evenly divided,
+ * the final sub-array will contain the remaining elements.
+ *
+ * @template T The type of elements in the array.
+ * @param {T[]} arr - The array to be chunked into smaller arrays.
+ * @param {number} size - The size of each smaller array. Must be a positive integer.
+ * @returns {T[][]} A two-dimensional array where each sub-array has a maximum length of `size`.
+ * @throws {Error} Throws an error if `size` is not a positive integer.
+ *
+ * @example
+ * // Splits an array of numbers into sub-arrays of length 2
+ * chunk([1, 2, 3, 4, 5], 2);
+ * // Returns: [[1, 2], [3, 4], [5]]
+ *
+ * @example
+ * // Splits an array of strings into sub-arrays of length 3
+ * chunk(['a', 'b', 'c', 'd', 'e', 'f', 'g'], 3);
+ * // Returns: [['a', 'b', 'c'], ['d', 'e', 'f'], ['g']]
+ */
+function chunk(arr, size) {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new Error('Size must be an integer greater than zero.');
+  }
+  var chunkLength = Math.ceil(arr.length / size);
+  var result = Array(chunkLength);
+  for (var index = 0; index < chunkLength; index++) {
+    var start = index * size;
+    var end = start + size;
+    result[index] = arr.slice(start, end);
+  }
+  return result;
+}
+
+/**
+ * Computes the difference between two arrays.
+ * 
+ * This function takes two arrays and returns a new array containing the elements 
+ * that are present in the first array but not in the second array. It effectively 
+ * filters out any elements from the first array that also appear in the second array.
+ *
+ * @template T
+ * @param {T[]} firstArr - The array from which to derive the difference. This is the primary array 
+ * from which elements will be compared and filtered.
+ * @param {T[]} secondArr - The array containing elements to be excluded from the first array. 
+ * Each element in this array will be checked against the first array, and if a match is found, 
+ * that element will be excluded from the result.
+ * @returns {T[]} A new array containing the elements that are present in the first array but not 
+ * in the second array.
+ *
+ * @example
+ *  * const array1 = [1, 2, 3, 4, 5];
+ * const array2 = [2, 4];
+ * const result = difference(array1, array2);
+ * // result will be [1, 3, 5] since 2 and 4 are in both arrays and are excluded from the result.
+ */
+function difference(firstArr, secondArr) {
+  return firstArr.filter(function (item) {
+    return !secondArr.includes(item);
+  });
+}
+
+/**
+ * Computes the difference between two arrays after mapping their elements through a provided function.
+ * 
+ * This function takes two arrays and a mapper function. It returns a new array containing the elements 
+ * that are present in the first array but not in the second array, based on the identity calculated 
+ * by the mapper function. 
+ * 
+ * Essentially, it filters out any elements from the first array that, when 
+ * mapped, match an element in the mapped version of the second array.
+ *
+ * @template T, U
+ * @param {T[]} firstArr - The primary array from which to derive the difference. 
+ * @param {T[]} secondArr - The array containing elements to be excluded from the first array.
+ * @param {(value: T) => U} mapper - The function to map the elements of both arrays. This function 
+ * is applied to each element in both arrays, and the comparison is made based on the mapped values.
+ * @returns {T[]} A new array containing the elements from the first array that do not have a corresponding 
+ * mapped identity in the second array.
+ *
+ * @example
+ *  * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const mapper = item => item.id;
+ * const result = differenceBy(array1, array2, mapper);
+ * // result will be [{ id: 1 }, { id: 3 }] since the elements with id 2 are in both arrays and are excluded from the result.
+ */
+function differenceBy(firstArr, secondArr, mapper) {
+  var mappedSecondArr = secondArr.map(function (item) {
+    return mapper(item);
+  });
+  return firstArr.filter(function (item) {
+    return !mappedSecondArr.includes(mapper(item));
+  });
+}
+
+/**
+ * Computes the difference between two arrays based on a custom equality function.
+ * 
+ * This function takes two arrays and a custom comparison function. It returns a new array containing 
+ * the elements that are present in the first array but not in the second array. The comparison to determine 
+ * if elements are equal is made using the provided custom function.
+ *
+ * @template T
+ * @param {T[]} firstArr - The array from which to get the difference.
+ * @param {T[]} secondArr - The array containing elements to exclude from the first array. 
+ * @param {(x: T, y: T) => boolean} areItemsEqual - A function to determine if two items are equal.
+ * @returns {T[]} A new array containing the elements from the first array that do not match any elements in the second array 
+ * according to the custom equality function.
+ *
+ * @example
+ *  * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const areItemsEqual = (a, b) => a.id === b.id;
+ * const result = differenceWith(array1, array2, areItemsEqual);
+ * // result will be [{ id: 1 }, { id: 3 }] since the elements with id 2 are considered equal and are excluded from the result.
+ */
+function differenceWith(firstArr, secondArr, areItemsEqual) {
+  return firstArr.filter(function (firstItem) {
+    return secondArr.every(function (secondItem) {
+      return !areItemsEqual(firstItem, secondItem);
+    });
+  });
+}
+
+/**
+ * Removes a specified number of elements from the beginning of an array and returns the rest.
+ * 
+ * This function takes an array and a number, and returns a new array with the specified number 
+ * of elements removed from the start.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {number} itemsCount - The number of elements to drop from the beginning of the array.
+ * @returns {T[]} A new array with the specified number of elements removed from the start.
+ * 
+ * @example
+ *  * const array = [1, 2, 3, 4, 5];
+ * const result = drop(array, 2);
+ * // result will be [3, 4, 5] since the first two elements are dropped.
+ */
+function drop(arr, itemsCount) {
+  return arr.slice(itemsCount);
+}
+
+/**
+ * Removes a specified number of elements from the end of an array and returns the rest.
+ * 
+ * This function takes an array and a number, and returns a new array with the specified number 
+ * of elements removed from the end.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {number} itemsCount - The number of elements to drop from the end of the array.
+ * @returns {T[]} A new array with the specified number of elements removed from the end.
+ *
+ * @example
+ *  * const array = [1, 2, 3, 4, 5];
+ * const result = dropRight(array, 2);
+ * // result will be [1, 2, 3] since the last two elements are dropped.
+ */
+function dropRight(arr, itemsCount) {
+  return arr.slice(0, -itemsCount);
+}
+
+/**
+ * Removes elements from the beginning of an array until the predicate returns false.
+ * 
+ * This function iterates over an array and drops elements from the start until the provided 
+ * predicate function returns false. It then returns a new array with the remaining elements.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {(item: T) => boolean} canContinueDropping - A predicate function that determines 
+ * whether to continue dropping elements. The function is called with each element, and dropping 
+ * continues as long as it returns true.
+ * @returns {T[]} A new array with the elements remaining after the predicate returns false.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const result = dropWhile(array, x => x < 3);
+ * // result will be [3, 4, 5] since elements less than 3 are dropped.
+ */
+function dropWhile(arr, canContinueDropping) {
+  var dropEndIndex = arr.findIndex(function (item) {
+    return !canContinueDropping(item);
+  });
+  return arr.slice(dropEndIndex);
+}
+
+/**
+ * Removes elements from the end of an array until the predicate returns false.
+ * 
+ * This function iterates over an array from the end and drops elements until the provided 
+ * predicate function returns false. It then returns a new array with the remaining elements.
+ *
+ * @param {T[]} arr - The array from which to drop elements.
+ * @param {function(item: T): boolean} canContinueDropping - A predicate function that determines 
+ * whether to continue dropping elements. The function is called with each element from the end, 
+ * and dropping continues as long as it returns true.
+ * @returns {T[]} A new array with the elements remaining after the predicate returns false.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const result = dropRightWhile(array, x => x > 3);
+ * // result will be [1, 2, 3] since elements greater than 3 are dropped from the end.
+ */
+function dropRightWhile(arr, canContinueDropping) {
+  var reversed = arr.slice().reverse();
+  var dropped = dropWhile(reversed, canContinueDropping);
+  return dropped.slice().reverse();
+}
+
 function _iterableToArrayLimit(r, l) {
   var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"];
   if (null != t) {
@@ -165,28 +378,47 @@ function _createForOfIteratorHelper(o, allowArrayLike) {
 }
 
 /**
- * @name chunk
- * Separate an array into smaller arrays of length `size`.
- * If the array cannot be separated in equal size, the final sub-array will have the remaining elements.
- * @param arr The array to chunk
- * @param size The size of smaller arrays
+ * Groups the elements of an array based on a provided key-generating function.
+ * 
+ * This function takes an array and a function that generates a key from each element. It returns 
+ * an object where the keys are the generated keys and the values are arrays of elements that share 
+ * the same key.
+ *
+ * @param {T[]} arr - The array to group.
+ * @param {(item: T) => K} getKeyFromItem - A function that generates a key from an element.
+ * @returns {Record<K, T[]>} An object where each key is associated with an array of elements that 
+ * share that key.
+ *
+ * @example
+ * const array = [
+ *   { category: 'fruit', name: 'apple' },
+ *   { category: 'fruit', name: 'banana' },
+ *   { category: 'vegetable', name: 'carrot' }
+ * ];
+ * const result = groupBy(array, item => item.category);
+ * // result will be:
+ * // {
+ * //   fruit: [
+ * //     { category: 'fruit', name: 'apple' },
+ * //     { category: 'fruit', name: 'banana' }
+ * //   ],
+ * //   vegetable: [
+ * //     { category: 'vegetable', name: 'carrot' }
+ * //   ]
+ * // }
  */
-function chunk(arr, size) {
-  if (!Number.isInteger(size) || size <= 0) {
-    throw new Error("Size must be an integer greater than zero.");
-  }
-  var result = [];
-  var _iterator = _createForOfIteratorHelper(arr.entries()),
+function groupBy(arr, getKeyFromItem) {
+  var result = {};
+  var _iterator = _createForOfIteratorHelper(arr),
     _step;
   try {
     for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var _step$value = _slicedToArray(_step.value, 2),
-        index = _step$value[0],
-        item = _step$value[1];
-      if (index % size === 0) {
-        result.push([]);
+      var item = _step.value;
+      var key = getKeyFromItem(item);
+      if (result[key] == null) {
+        result[key] = [];
       }
-      result[result.length - 1].push(item);
+      result[key].push(item);
     }
   } catch (err) {
     _iterator.e(err);
@@ -197,106 +429,21 @@ function chunk(arr, size) {
 }
 
 /**
- * @name difference
- * Returns the difference of two arrays.
- * @param firstArr The array to get the difference from
- * @param secondArr The elements to exclude from `firstArr`
- */
-function difference(firstArr, secondArr) {
-  return firstArr.filter(function (item) {
-    return !secondArr.includes(item);
-  });
-}
-
-/**
- * @name differenceBy
- * Returns the difference of two arrays. The identity of two elements is calculated after the elements are mapped with `mapper`.
- * @param firstArr The array to get the difference from
- * @param secondArr The elements to exclude from `firstArr`
- * @param mapper The function to map the elements when calculating the difference
- */
-function differenceBy(firstArr, secondArr, mapper) {
-  var mappedSecondArr = secondArr.map(function (item) {
-    return mapper(item);
-  });
-  return firstArr.filter(function (item) {
-    return !mappedSecondArr.includes(mapper(item));
-  });
-}
-
-/**
- * @name differenceWith
- * Returns the difference of two arrays. The identity of two elements is calculated with the function `areItemsEqual`.
- * @param firstArr The array to get the difference from
- * @param secondArr The elements to exclude from `firstArr`
- * @param areItemsEqual The function to determine whether two items are equal
- */
-function differenceWith(firstArr, secondArr, areItemsEqual) {
-  return firstArr.filter(function (firstItem) {
-    return secondArr.every(function (secondItem) {
-      return !areItemsEqual(firstItem, secondItem);
-    });
-  });
-}
-
-/**
- * @name drop
- * Drop some elements from an array from the beginning. This function returns a new array.
- * @param arr The element to drop items from the beginning
- * @param itemsCount The amount of elements to drop
- */
-function drop(arr, itemsCount) {
-  return arr.slice(itemsCount);
-}
-
-/**
- * @name dropRight
- * Drop some elements from an array from the end. This function returns a new array.
- * @param arr The element to drop items from the end
- * @param itemsCount The amount of elements to drop
- */
-function dropRight(arr, itemsCount) {
-  return arr.slice(0, -itemsCount);
-}
-
-/**
- * @name dropWhile
- * Drop some elements from an array from the beginning, until `predicate` returns false.
- * @param arr The element to drop items from the beginning
- * @param canContinueDropping The predicate to check if the function can continue dropping elements.
- */
-function dropWhile(arr, canContinueDropping) {
-  var dropEndIndex = arr.findIndex(function (item) {
-    return !canContinueDropping(item);
-  });
-  return arr.slice(dropEndIndex);
-}
-
-/**
- * @name dropRightWhile
- * Drop some elements from an array from the end, until `predicate` returns false.
- * @param arr The element to drop items from the end
- * @param canContinueDropping The predicate to check if the function can continue dropping elements.
- */
-function dropRightWhile(arr, canContinueDropping) {
-  var reversed = arr.slice().reverse();
-  var dropped = dropWhile(reversed, canContinueDropping);
-  return dropped.slice().reverse();
-}
-
-function groupBy() {
-  throw new Error('Not implemented');
-}
-
-/**
- * @name intersection
- * @description
  * Returns the intersection of two arrays.
- * @param firstArr The first array to get the intersection
- * @param secondArr The second array to get the intersection
+ * 
+ * This function takes two arrays and returns a new array containing the elements that are 
+ * present in both arrays. It effectively filters out any elements from the first array that 
+ * are not found in the second array.
+ *
+ * @param {T[]} firstArr - The first array to compare.
+ * @param {T[]} secondArr - The second array to compare.
+ * @returns {T[]} A new array containing the elements that are present in both arrays.
+ *
  * @example
- * intersection([1, 2], [1, 3]) === [1]
- * intersection([1, 2, 3], [2, 3, 4]) === [2, 3]
+ * const array1 = [1, 2, 3, 4, 5];
+ * const array2 = [3, 4, 5, 6, 7];
+ * const result = intersection(array1, array2);
+ * // result will be [3, 4, 5] since these elements are in both arrays.
  */
 function intersection(firstArr, secondArr) {
   return firstArr.filter(function (item) {
@@ -305,15 +452,24 @@ function intersection(firstArr, secondArr) {
 }
 
 /**
- * @name intersectionBy
- * @description
- * Returns the intersection of two arrays. The identity of two elements is calculated after the elements are mapped with `mapper`.
- * @param firstArr The first array to get the intersection
- * @param secondArr The second array to get the intersection
- * @param mapper The function to map the elements when calculating the intersection
+ * Returns the intersection of two arrays based on a mapping function.
+ * 
+ * This function takes two arrays and a mapping function. It returns a new array containing 
+ * the elements from the first array that, when mapped using the provided function, have matching 
+ * mapped elements in the second array. It effectively filters out any elements from the first array 
+ * that do not have corresponding mapped values in the second array.
+ *
+ * @param {T[]} firstArr - The first array to compare.
+ * @param {T[]} secondArr - The second array to compare.
+ * @param {(item: T) => U} mapper - A function to map the elements of both arrays for comparison.
+ * @returns {T[]} A new array containing the elements from the first array that have corresponding mapped values in the second array.
+ *
  * @example
- * intersectionBy([1.2, 2.1], [1.4, 3.1], Math.floor) === [1.2]
- * intersectionBy([{ foo: 1 }, { foo: 2 }], [{ foo: 1 }, { foo: 3 }], x => x.foo) === [{ foo: 1 }]
+ * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const mapper = item => item.id;
+ * const result = intersectionBy(array1, array2, mapper);
+ * // result will be [{ id: 2 }] since only this element has a matching id in both arrays.
  */
 function intersectionBy(firstArr, secondArr, mapper) {
   var mappedSecondArr = secondArr.map(function (x) {
@@ -325,15 +481,25 @@ function intersectionBy(firstArr, secondArr, mapper) {
 }
 
 /**
- * @name intersectionWith
- * @description
- * Returns the intersection of two arrays. The identity of two elements is compared with `areItemsEqual`.
- * @param firstArr The first array to get the intersection
- * @param secondArr The second array to get the intersection
- * @param areItemsEqual The function to compare the identity of two elements
+ * Returns the intersection of two arrays based on a custom equality function.
+ * 
+ * This function takes two arrays and a custom equality function. It returns a new array containing 
+ * the elements from the first array that have matching elements in the second array, as determined 
+ * by the custom equality function. It effectively filters out any elements from the first array that 
+ * do not have corresponding matches in the second array according to the equality function.
+ *
+ * @param {T[]} firstArr - The first array to compare.
+ * @param {T[]} secondArr - The second array to compare.
+ * @param {(x: T, y: T) => boolean} areItemsEqual - A custom function to determine if two elements are equal. 
+ * This function takes two arguments, one from each array, and returns `true` if the elements are considered equal, and `false` otherwise.
+ * @returns {T[]} A new array containing the elements from the first array that have corresponding matches in the second array according to the custom equality function.
+ *
  * @example
- * intersectionWith([1.2, 2.1], [1.4, 3.1], (x, y) => Math.floor(x) === Math.floor(y)) === [1.2]
- * intersectionWith([{ foo: 1 }, { foo: 2 }], [{ foo: 1 }, { foo: 3 }], (x, y) => x.foo === y.foo) === [{ foo: 1 }]
+ *  * const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }];
+ * const array2 = [{ id: 2 }, { id: 4 }];
+ * const areItemsEqual = (a, b) => a.id === b.id;
+ * const result = intersectionWith(array1, array2, areItemsEqual);
+ * // result will be [{ id: 2 }] since this element has a matching id in both arrays.
  */
 function intersectionWith(firstArr, secondArr, areItemsEqual) {
   return firstArr.filter(function (firstItem) {
@@ -344,11 +510,25 @@ function intersectionWith(firstArr, secondArr, areItemsEqual) {
 }
 
 /**
- * @name partition
- * @description
- * Creates two arrays: the first array includes items for which isInTruthy returns true, and the second array includes items for which isInTruthy returns false.
- * @param arr The array to split into two arrays
- * @param isInTruthy The predicate to tell whether an item is included in the first array
+ * Splits an array into two groups based on a predicate function.
+ * 
+ * This function takes an array and a predicate function. It returns a tuple of two arrays: 
+ * the first array contains elements for which the predicate function returns true, and 
+ * the second array contains elements for which the predicate function returns false.
+ *
+ * @param {T[]} arr - The array to partition.
+ * @param {(value: T) => boolean} isInTruthy - A predicate function that determines 
+ * whether an element should be placed in the truthy array. The function is called with each 
+ * element of the array.
+ * @returns {[T[], T[]]} A tuple containing two arrays: the first array contains elements for 
+ * which the predicate returned true, and the second array contains elements for which the 
+ * predicate returned false.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const isEven = x => x % 2 === 0;
+ * const [even, odd] = partition(array, isEven);
+ * // even will be [2, 4], and odd will be [1, 3, 5]
  */
 function partition(arr, isInTruthy) {
   var truthy = [];
@@ -373,10 +553,17 @@ function partition(arr, isInTruthy) {
 }
 
 /**
- * @name sample
- * @description
  * Returns a random element from an array.
- * @param arr The element to get a random element
+ * 
+ * This function takes an array and returns a single element selected randomly from the array.
+ *
+ * @param {T[]} arr - The array to sample from.
+ * @returns {T} A random element from the array.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const randomElement = sample(array);
+ * // randomElement will be one of the elements from the array, selected randomly.
  */
 function sample(arr) {
   var randomIndex = Math.floor(Math.random() * arr.length);
@@ -384,17 +571,24 @@ function sample(arr) {
 }
 
 /**
- * @name shuffle
- * @description
- * Randomize the order of an array.
- * @param arr The array to shuffle
+ * Randomizes the order of elements in an array using the Fisher-Yates algorithm.
+ * 
+ * This function takes an array and returns a new array with its elements shuffled in a random order.
+ *
+ * @param {T[]} arr - The array to shuffle.
+ * @returns {T[]} A new array with its elements shuffled in random order.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * const shuffledArray = shuffle(array);
+ * // shuffledArray will be a new array with elements of array in random order, e.g., [3, 1, 4, 5, 2]
  */
 function shuffle(arr) {
   /**
    * https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm
    */
   for (var i = arr.length - 1; i >= 1; i--) {
-    var j = Math.floor(Math.random() * i);
+    var j = Math.floor(Math.random() * (i + 1));
     var _ref = [arr[j], arr[i]];
     arr[i] = _ref[0];
     arr[j] = _ref[1];
@@ -431,8 +625,6 @@ function take(arr, count) {
 /**
  * Returns a new array containing the last `count` elements from the input array `arr`.
  * If `count` is greater than the length of `arr`, the entire array is returned.
- *
- * @template T - Type of elements in the input array.
  * 
  * @param {T[]} arr - The array to take elements from.
  * @param {number} count - The number of elements to take.
@@ -522,43 +714,61 @@ function takeWhile(arr, shouldContinueTaking) {
 }
 
 /**
- * @name uniq
- * @description
- * `uniq` removes duplicated elements from the array given as an argument.
+ * Creates a duplicate-free version of an array.
+ * 
+ * This function takes an array and returns a new array containing only the unique values 
+ * from the original array, preserving the order of first occurrence.
  *
- * It filters out elements with the same value, so duplicates of data types like Objects are not checked.
+ * @param {T[]} arr - The array to process.
+ * @returns {T[]} A new array with only unique values from the original array.
  *
  * @example
- * ```ts
- * uniq([1, 1, 2, 3, 5, 5, 7, 'foo', 'bar', 'bar']);
- * // [1, 2, 3, 5, 7, 'foo', 'bar']
- * ```
+ *  * const array = [1, 2, 2, 3, 4, 4, 5];
+ * const result = uniq(array);
+ * // result will be [1, 2, 3, 4, 5]
  */
 function uniq(arr) {
-  return Array.from(new Set(arr));
+  var result = [];
+  var _iterator = _createForOfIteratorHelper(arr),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var item = _step.value;
+      if (result.includes(item)) {
+        continue;
+      }
+      result.push(item);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return result;
 }
 
 /**
- * `union` function returns the union of the arrays passed as arguments.
+ * Creates an array of unique values from all given arrays.
+ * 
+ * This function takes two arrays, merges them into a single array, and returns a new array 
+ * containing only the unique values from the merged array.
+ *
+ * @param {T[]} arr1 - The first array to merge and filter for unique values.
+ * @param {T[]} arr2 - The second array to merge and filter for unique values.
+ * @returns {T[]} A new array of unique values.
  *
  * @example
- * ```ts
- * union([2], [1, 2]);
- * // [2, 1]
- * ```
+ * const array1 = [1, 2, 3];
+ * const array2 = [3, 4, 5];
+ * const result = union(array1, array2);
+ * // result will be [1, 2, 3, 4, 5]
  */
-function union() {
-  for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
-    args[_key] = arguments[_key];
-  }
-  return uniq(args.flat());
+function union(arr1, arr2) {
+  return uniq(arr1.concat(arr2));
 }
 
 /**
  * Creates an array of unique values, in order, from all given arrays using a provided mapping function to determine equality.
- *
- * @template T - Type of elements in the input arrays.
- * @template U - Type of the values returned by the mapping function.
  * 
  * @param {T[]} arr1 - The first array.
  * @param {T[]} arr2 - The second array.
@@ -626,20 +836,26 @@ function uniqWith(arr, areItemsEqual) {
 }
 
 /**
- * `unionWith` function returns the union of multiple arrays passed as arguments. During this process, it removes any duplicated elements.
+ * Creates an array of unique values from two given arrays based on a custom equality function.
+ * 
+ * This function takes two arrays and a custom equality function, merges the arrays, and returns 
+ * a new array containing only the unique values as determined by the custom equality function.
+ *
+ * @param {T[]} arr1 - The first array to merge and filter for unique values.
+ * @param {T[]} arr2 - The second array to merge and filter for unique values.
+ * @param {(item1: T, item2: T) => boolean} areItemsEqual - A custom function to determine if two elements are equal. 
+ * It takes two arguments and returns `true` if the elements are considered equal, and `false` otherwise.
+ * @returns {T[]} A new array of unique values based on the custom equality function.
  *
  * @example
- * ```ts
- * unionWith(
- *   [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }],
- *   [{ 'x': 1, 'y': 1 }, { 'x': 1, 'y': 2 }],
- *   (x, y) => x === y
- * );
- * // [{ 'x': 1, 'y': 2 }, { 'x': 2, 'y': 1 }, { 'x': 1, 'y': 1 }]
- * ```
+ * const array1 = [{ id: 1 }, { id: 2 }];
+ * const array2 = [{ id: 2 }, { id: 3 }];
+ * const areItemsEqual = (a, b) => a.id === b.id;
+ * const result = unionWith(array1, array2, areItemsEqual);
+ * // result will be [{ id: 1 }, { id: 2 }, { id: 3 }] since { id: 2 } is considered equal in both arrays
  */
 function unionWith(arr1, arr2, areItemsEqual) {
-  return uniqWith([].concat(_toConsumableArray(arr1), _toConsumableArray(arr2)), areItemsEqual);
+  return uniqWith(arr1.concat(arr2), areItemsEqual);
 }
 
 /**
@@ -662,8 +878,6 @@ function uniqBy(arr, converter) {
 /**
  * Computes the symmetric difference between two arrays. The symmetric difference is the set of elements
  * which are in either of the arrays, but not in their intersection.
- *
- * @template T - Type of elements in the input arrays.
  * 
  * @param {T[]} arr1 - The first array.
  * @param {T[]} arr2 - The second array.
@@ -731,13 +945,25 @@ function xorWith(arr1, arr2, areElementsEqual) {
 }
 
 /**
- * Merges multiple arrays element-wise. Returns an array where each element is an array containing
- * elements from the input arrays at the corresponding index.
+ * Combines multiple arrays into a single array of tuples.
  * 
- * @param {T[]} arr1 - The first array to be zipped.
- * @param {T[]} arr2 - The second array to be zipped.
- * @param {T[]} arr3 - The third array to be zipped.
- * @param {T[]} arr4 - The fourth array to be zipped.
+ * This function takes multiple arrays and returns a new array where each element is a tuple 
+ * containing the corresponding elements from the input arrays. If the input arrays are of 
+ * different lengths, the resulting array will have the length of the longest input array, 
+ * with undefined values for missing elements.
+ *
+ * @param {...T[][]} arrs - The arrays to zip together.
+ * @returns {T[][]} A new array of tuples containing the corresponding elements from the input arrays.
+ *
+ * @example
+ * const arr1 = [1, 2, 3];
+ * const arr2 = ['a', 'b', 'c'];
+ * const result = zip(arr1, arr2);
+ * // result will be [[1, 'a'], [2, 'b'], [3, 'c']]
+ *
+ * const arr3 = [true, false];
+ * const result2 = zip(arr1, arr2, arr3);
+ * // result2 will be [[1, 'a', true], [2, 'b', false], [3, 'c', undefined]]
  */
 
 function zip() {
@@ -768,9 +994,32 @@ function zip() {
 }
 
 /**
- * Combines multiple arrays element-wise using a provided combining function. 
- * Returns an array where each element is the result of applying the combining function 
- * to the corresponding elements from the input arrays.
+ * Combines multiple arrays into a single array using a custom combiner function.
+ * 
+ * This function takes multiple arrays and a combiner function, and returns a new array where each element 
+ * is the result of applying the combiner function to the corresponding elements of the input arrays.
+ *
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} [arr2] - The second array to zip (optional).
+ * @param {V[]} [arr3] - The third array to zip (optional).
+ * @param {W[]} [arr4] - The fourth array to zip (optional).
+ * @param {function} combine - The combiner function that takes corresponding elements from each array and returns a single value.
+ * @returns {R[]} A new array where each element is the result of applying the combiner function to the corresponding elements of the input arrays.
+ *
+ * @example
+ * // Example usage with two arrays:
+ * const arr1 = [1, 2, 3];
+ * const arr2 = [4, 5, 6];
+ * const result = zipWith(arr1, arr2, (a, b) => a + b);
+ * // result will be [5, 7, 9]
+ *
+ * @example
+ * // Example usage with three arrays:
+ * const arr1 = [1, 2];
+ * const arr2 = [3, 4];
+ * const arr3 = [5, 6];
+ * const result = zipWith(arr1, arr2, arr3, (a, b, c) => `${a}${b}${c}`);
+ * // result will be [`135`, `246`]
  */
 
 function zipWith(arr1) {
@@ -796,12 +1045,12 @@ function zipWith(arr1) {
 }
 
 /**
- * Creates a debounced function that delays invoking the provided function until after `waitMs` milliseconds
+ * Creates a debounced function that delays invoking the provided function until after `debounceMs` milliseconds
  * have elapsed since the last time the debounced function was invoked. The debounced function also has a `cancel`
  * method to cancel any pending execution.
  *
  * @param {() => void} func - The function to debounce.
- * @param {number} waitMs - The number of milliseconds to delay.
+ * @param {number} debounceMs - The number of milliseconds to delay.
  * @returns {{ (): void; cancel: () => void }} A new debounced function with a `cancel` method.
  *
  * @example
@@ -815,7 +1064,7 @@ function zipWith(arr1) {
  * // Will not log anything as the previous call is canceled
  * debouncedFunction.cancel();
  */
-function debounce(func, waitMs) {
+function debounce(func, debounceMs) {
   var timeoutId = null;
   var debounced = function debounced() {
     if (timeoutId != null) {
@@ -823,7 +1072,7 @@ function debounce(func, waitMs) {
     }
     timeoutId = setTimeout(function () {
       func();
-    }, waitMs);
+    }, debounceMs);
   };
   debounced.cancel = function () {
     if (timeoutId != null) {
@@ -837,7 +1086,6 @@ function debounce(func, waitMs) {
  * Creates a function that is restricted to invoking the provided function `func` once.
  * Repeated calls to the function will return the value from the first invocation.
  *
- * @template F - The type of the function to be invoked once.
  * @param {F} func - The function to restrict.
  * @returns {F} A new function that invokes `func` once and caches the result.
  *
@@ -902,15 +1150,23 @@ function throttle(func, throttleMs) {
 }
 
 /**
- * @name clamp
- * @description Checks if `value` is within the bounds, if not return the closest bound (bound1: min, bound2: max)
- * function clamp(value: number, bound1: number, bound2?: number): number
+ * Clamps a number within the inclusive lower and upper bounds.
+ *
+ * This function takes a number and two bounds, and returns the number clamped within the specified bounds.
+ * If only one bound is provided, it returns the minimum of the value and the bound.
+ *
+ * @param {number} value - The number to clamp.
+ * @param {number} minimum - The minimum bound to clamp the number.
+ * @param {number} maximum - The maximum bound to clamp the number.
+ * @returns {number} The clamped number within the specified bounds.
+ *
  * @example
- * clamp(3, 1) // 3
- * clamp(3, 1, 5) // 3
- * clamp(3, 5) // 5
- * clamp(7, 3, 5) // 5
+ *  * const result1 = clamp(10, 5); // result1 will be 5, as 10 is clamped to the bound 5
+ * const result2 = clamp(10, 5, 15); // result2 will be 10, as it is within the bounds 5 and 15
+ * const result3 = clamp(2, 5, 15); // result3 will be 5, as 2 is clamped to the lower bound 5
+ * const result4 = clamp(20, 5, 15); // result4 will be 15, as 20 is clamped to the upper bound 15
  */
+
 function clamp(value, bound1, bound2) {
   if (bound2 == null) {
     return Math.min(value, bound1);
@@ -919,16 +1175,19 @@ function clamp(value, bound1, bound2) {
 }
 
 /**
- * @name round
- * @description Rounds given number to given precision
- * ```typescript
- * function round(value: number, precision: number = 0): number
- * ```
+ * Rounds a number to a specified precision.
  * 
+ * This function takes a number and an optional precision value, and returns the number rounded 
+ * to the specified number of decimal places.
+ *
+ * @param {number} value - The number to round.
+ * @param {number} [precision=0] - The number of decimal places to round to. Defaults to 0.
+ * @returns {number} The rounded number.
+ *
  * @example
- * round(1.2) === 1
- * round(3.9) === 4
- * round(8.5) === 9
+ *  * const result1 = round(1.2345); // result1 will be 1
+ * const result2 = round(1.2345, 2); // result2 will be 1.23
+ * const result3 = round(1.2345, 3); // result3 will be 1.235
  */
 function round(value) {
   var precision = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
@@ -937,31 +1196,49 @@ function round(value) {
 }
 
 /**
- * @name sum
- * @description Return the sum of given values.
- * ```typescript
- * function sum(...nums: number[] | number[][]): number;
- * ```
+ * Calculates the sum of an array of numbers.
+ * 
+ * This function takes an array of numbers and returns the sum of all the elements in the array.
+ *
+ * @param {number[]} nums - An array of numbers to be summed.
+ * @returns {number} The sum of all the numbers in the array.
  *
  * @example
- * sum(1, 2, 3) === 6
- * sum(...[1, 2, 3]) === 6
- * sum([1, 2, 3]) === 6
+ *  * const numbers = [1, 2, 3, 4, 5];
+ * const result = sum(numbers);
+ * // result will be 15
  */
-function sum() {
-  for (var _len = arguments.length, nums = new Array(_len), _key = 0; _key < _len; _key++) {
-    nums[_key] = arguments[_key];
+function sum(nums) {
+  var result = 0;
+  var _iterator = _createForOfIteratorHelper(nums),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var num = _step.value;
+      result += num;
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
   }
-  return nums.flat().reduce(function (acc, curr) {
-    return acc + curr;
-  }, 0);
+  return result;
 }
 
 /**
- * @name omit
- * Omit properties from an object.
- * @param obj The object to omit properties from
- * @param keys The keys to omit from an object
+ * Creates a new object with specified keys omitted.
+ *
+ * This function takes an object and an array of keys, and returns a new object that 
+ * excludes the properties corresponding to the specified keys.
+ *
+ * @param {T} obj - The object to omit keys from.
+ * @param {K[]} keys - An array of keys to be omitted from the object.
+ * @returns {Omit<T, K>} A new object with the specified keys omitted.
+ *
+ * @example
+ *  * const obj = { a: 1, b: 2, c: 3 };
+ * const result = omit(obj, ['b', 'c']);
+ * // result will be { a: 1 }
  */
 function omit(obj, keys) {
   var result = _objectSpread2({}, obj);
@@ -980,15 +1257,52 @@ function omit(obj, keys) {
   return result;
 }
 
-function omitBy() {
-  throw new Error('Not implemented');
+/**
+ * Creates a new object composed of the properties that do not satisfy the predicate function.
+ *
+ * This function takes an object and a predicate function, and returns a new object that 
+ * includes only the properties for which the predicate function returns false.
+ *
+ * @param {T} obj - The object to omit properties from.
+ * @param {(value: T[string], key: string) => boolean} shouldOmit - A predicate function that determines 
+ * whether a property should be omitted. It takes the property's key and value as arguments and returns `true` 
+ * if the property should be omitted, and `false` otherwise.
+ * @returns {Partial<T>} A new object with the properties that do not satisfy the predicate function.
+ *
+ * @example
+ * const obj = { a: 1, b: 'omit', c: 3 };
+ * const shouldOmit = (key, value) => typeof value === 'string';
+ * const result = omitBy(obj, shouldOmit);
+ * // result will be { a: 1, c: 3 }
+ */
+function omitBy(obj, shouldOmit) {
+  var result = {};
+  for (var _i = 0, _Object$entries = Object.entries(obj); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      value = _Object$entries$_i[1];
+    if (shouldOmit(value, key)) {
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
 }
 
 /**
- * @name pick
- * Pick properties from an given object.
- * @param obj The object to pick properties from
- * @param keys The keys to pick from an object
+ * Creates a new object composed of the picked object properties.
+ *
+ * This function takes an object and an array of keys, and returns a new object that 
+ * includes only the properties corresponding to the specified keys.
+ *
+ * @param {T} obj - The object to pick keys from.
+ * @param {K[]} keys - An array of keys to be picked from the object.
+ * @returns {Pick<T, K>} A new object with the specified keys picked.
+ *
+ * @example
+ *  * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, ['a', 'c']);
+ * // result will be { a: 1, c: 3 }
  */
 function pick(obj, keys) {
   var result = {};
@@ -1007,56 +1321,145 @@ function pick(obj, keys) {
   return result;
 }
 
-function pickBy() {
-  throw new Error('Not implemented');
+/**
+ * Creates a new object composed of the properties that satisfy the predicate function.
+ *
+ * This function takes an object and a predicate function, and returns a new object that 
+ * includes only the properties for which the predicate function returns true.
+ *
+ * @param {T} obj - The object to pick properties from.
+ * @param {(value: T[keyof T], key: string) => boolean} shouldPick - A predicate function that determines 
+ * whether a property should be picked. It takes the property's key and value as arguments and returns `true` 
+ * if the property should be picked, and `false` otherwise.
+ * @returns {Partial<T>} A new object with the properties that satisfy the predicate function.
+ *
+ * @example
+ * const obj = { a: 1, b: 'pick', c: 3 };
+ * const shouldPick = (value) => typeof value === 'string';
+ * const result = pickBy(obj, shouldPick);
+ * // result will be { b: 'pick' }
+ */
+function pickBy(obj, shouldPick) {
+  var result = {};
+  for (var _i = 0, _Object$entries = Object.entries(obj); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      value = _Object$entries$_i[1];
+    if (!shouldPick(value, key)) {
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
 }
 
 /**
- * @name isNil
- * Checks if the given value is null or undefined.
- * @param x The value to test if it is null or undefined
+ * Checks if a given value is null or undefined.
+ * 
+ * This function tests whether the provided value is either `null` or `undefined`. 
+ * It returns `true` if the value is `null` or `undefined`, and `false` otherwise.
+ * 
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null` or `undefined`.
+ *
+ * @param {unknown} x - The value to test for null or undefined.
+ * @returns {boolean} `true` if the value is null or undefined, `false` otherwise.
+ *
+ * @example
+ *  * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ * const result1 = isNil(value1); // true
+ * const result2 = isNil(value2); // true
+ * const result3 = isNil(value3); // false
  */
 function isNil(x) {
   return x == null || x == undefined;
 }
 
 /**
- * @name isNotNil
  * Checks if the given value is not null nor undefined.
- * The main use of this function is to used with TypeScript as a type predicate.
- * @param x The value to test if it is not null nor undefined
+ * 
+ * The main use of this function is to be used with TypeScript as a type predicate.
+ *
+ * @param {T | null | undefined} x - The value to test if it is not null nor undefined.
+ * @returns {x is T} True if the value is not null nor undefined, false otherwise.
+ *
  * @example
  * // Here the type of `arr` is (number | undefined)[]
  * const arr = [1, undefined, 3];
  * // Here the type of `result` is number[]
  * const result = arr.filter(isNotNil);
+ * // result will be [1, 3]
  */
 function isNotNil(x) {
   return x != null && x != undefined;
 }
 
 /**
- * @name isNull
  * Checks if the given value is null.
- * @param x The value to test if it is null
+ *
+ * This function tests whether the provided value is strictly equal to `null`. 
+ * It returns `true` if the value is `null`, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null`.
+ * 
+ * @param {unknown} x - The value to test if it is null.
+ * @returns {x is null} True if the value is null, false otherwise.
+ *
+ * @example
+ *  * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ * 
+ * console.log(isNull(value1)); // true
+ * console.log(isNull(value2)); // false
+ * console.log(isNull(value3)); // false
  */
 function isNull(x) {
   return x === null;
 }
 
 /**
- * @name isUndefined
  * Checks if the given value is undefined.
- * @param x The value to test if it is undefined
+ *
+ * This function tests whether the provided value is strictly equal to `undefined`. 
+ * It returns `true` if the value is `undefined`, and `false` otherwise.
+ * 
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `undefined`.
+ *
+ * @param {unknown} x - The value to test if it is undefined.
+ * @returns {x is undefined} true if the value is undefined, false otherwise.
+ *
+ * @example
+ *  * const value1 = undefined;
+ * const value2 = null;
+ * const value3 = 42;
+ * 
+ * console.log(isUndefined(value1)); // true
+ * console.log(isUndefined(value2)); // false
+ * console.log(isUndefined(value3)); // false
  */
 function isUndefined(x) {
   return x === undefined;
 }
 
 /**
- * @name delay
- * Pause the execution of a function for given milliseconds.
- * @param ms The amount of time to delay the function.
+ * Delays the execution of code for a specified number of milliseconds.
+ * 
+ * This function returns a Promise that resolves after the specified delay, allowing you to use it 
+ * with async/await to pause execution.
+ *
+ * @param {number} ms - The number of milliseconds to delay.
+ * @returns {Promise<void>} A Promise that resolves after the specified delay.
+ *
+ * @example
+ * async function foo() {
+ *   console.log('Start');
+ *   await delay(1000); // Delays execution for 1 second
+ *   console.log('End');
+ * }
+ * 
+ * foo();
  */
 function delay(ms) {
   return new Promise(function (resolve) {