es-toolkit 0.0.1 → 1.0.0-dev.24

package/dist/array/intersection.d.ts

@@ -1,11 +1,18 @@
 /**
- * @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.
  */
 export declare function intersection<T>(firstArr: T[], secondArr: T[]): T[];

package/dist/array/intersectionBy.d.ts

@@ -1,12 +1,21 @@
 /**
- * @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.
  */
 export declare function intersectionBy<T, U>(firstArr: T[], secondArr: T[], mapper: (item: T) => U): T[];

package/dist/array/intersectionWith.d.ts

@@ -1,12 +1,22 @@
 /**
- * @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.
  */
 export declare function intersectionWith<T>(firstArr: T[], secondArr: T[], areItemsEqual: (x: T, y: T) => boolean): T[];

package/dist/array/partition.d.ts

@@ -1,8 +1,22 @@
 /**
- * @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]
  */
 export declare function partition<T>(arr: T[], isInTruthy: (value: T) => boolean): [truthy: T[], falsy: T[]];

package/dist/array/sample.d.ts

@@ -1,7 +1,14 @@
 /**
- * @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.
  */
 export declare function sample<T>(arr: T[]): T;

package/dist/array/shuffle.d.ts

@@ -1,7 +1,14 @@
 /**
- * @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]
  */
 export declare function shuffle<T>(arr: T[]): T[];

package/dist/array/takeRight.d.ts

@@ -2,8 +2,6 @@
  * 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.
  * @returns {T[]} A new array containing the last `count` elements from `arr`.

package/dist/array/union.d.ts

@@ -1,10 +1,17 @@
 /**
- * `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]
  */
-export declare function union<T>(...args: T[][]): T[];
+export declare function union<T>(arr1: T[], arr2: T[]): T[];

package/dist/array/unionBy.d.ts

@@ -1,9 +1,6 @@
 /**
  * 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.
  * @param {function(item: T): U} mapper - The function to map array elements to comparison values.

package/dist/array/unionWith.d.ts

@@ -1,14 +1,20 @@
 /**
- * `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
  */
 export declare function unionWith<T>(arr1: T[], arr2: T[], areItemsEqual: (item1: T, item2: T) => boolean): T[];

package/dist/array/uniq.d.ts

@@ -1,14 +1,15 @@
 /**
- * @name uniq
- * @description
- * `uniq` removes duplicated elements from the array given as an argument.
+ * Creates a duplicate-free version of an array.
  *
- * It filters out elements with the same value, so duplicates of data types like Objects are not checked.
+ * 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.
+ *
+ * @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]
  */
 export declare function uniq<T>(arr: T[]): T[];

package/dist/array/xor.d.ts

@@ -2,8 +2,6 @@
  * 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.
  * @returns {T[]} An array containing the elements that are present in either `arr1` or `arr2` but not in both.

package/dist/array/zip.d.ts

@@ -1,11 +1,23 @@
 /**
- * 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]]
  */
 export declare function zip<T>(arr1: T[]): [T][];
 export declare function zip<T, U>(arr1: T[], arr2: U[]): [T, U][];

package/dist/array/zipWith.d.ts

@@ -1,7 +1,30 @@
 /**
- * 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`]
  */
 export declare function zipWith<T, R>(arr1: T[], combine: (item: T) => R): R[];
 export declare function zipWith<T, U, R>(arr1: T[], arr2: U[], combine: (item1: T, item2: U) => R): R[];

package/dist/function/debounce.d.ts

@@ -1,10 +1,10 @@
 /**
- * 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
@@ -18,7 +18,7 @@
  * // Will not log anything as the previous call is canceled
  * debouncedFunction.cancel();
  */
-export declare function debounce(func: () => void, waitMs: number): {
+export declare function debounce(func: () => void, debounceMs: number): {
     (): void;
-    cancel(): void;
+    cancel: () => void;
 };

package/dist/function/index.js

@@ -3,12 +3,12 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 /**
- * 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
@@ -22,7 +22,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
  * // 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) {
@@ -30,7 +30,7 @@ function debounce(func, waitMs) {
     }
     timeoutId = setTimeout(function () {
       func();
-    }, waitMs);
+    }, debounceMs);
   };
   debounced.cancel = function () {
     if (timeoutId != null) {
@@ -44,7 +44,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.
  *

package/dist/function/once.d.ts

@@ -2,7 +2,6 @@
  * 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.
  *