es-toolkit 1.17.0 → 1.18.0-dev.573

package/dist/array/toFilled.d.mts

@@ -6,8 +6,6 @@
  * @template U - The type of the value to fill the new array with.
  * @param {Array<T>} arr - The array to base the new array on.
  * @param {U} value - The value to fill the new array with.
- * @param {number} [start=0] - The start position. Defaults to 0.
- * @param {number} [end=arr.length] - The end position. Defaults to the array's length.
  * @returns {Array<T | U>} The new array with the filled values.
  *
  * @example
@@ -29,7 +27,66 @@
  * console.log(array); // [1, 2, 3, 4, 5]
  */
 declare function toFilled<T, U>(arr: readonly T[], value: U): Array<T | U>;
+/**
+ * Creates a new array filled with the specified value from the start position up to, but not including, the end position.
+ * This function does not mutate the original array.
+ *
+ * @template T - The type of elements in the original array.
+ * @template U - The type of the value to fill the new array with.
+ * @param {Array<T>} arr - The array to base the new array on.
+ * @param {U} value - The value to fill the new array with.
+ * @param {number} [start=0] - The start position. Defaults to 0.
+ * @returns {Array<T | U>} The new array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * let result = toFilled(array, '*', 2);
+ * console.log(result); // [1, 2, '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', 1, 4);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*');
+ * console.log(result); // ['*', '*', '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', -4, -1);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ */
 declare function toFilled<T, U>(arr: readonly T[], value: U, start: number): Array<T | U>;
+/**
+ * Creates a new array filled with the specified value from the start position up to, but not including, the end position.
+ * This function does not mutate the original array.
+ *
+ * @template T - The type of elements in the original array.
+ * @template U - The type of the value to fill the new array with.
+ * @param {Array<T>} arr - The array to base the new array on.
+ * @param {U} value - The value to fill the new array with.
+ * @param {number} [start=0] - The start position. Defaults to 0.
+ * @param {number} [end=arr.length] - The end position. Defaults to the array's length.
+ * @returns {Array<T | U>} The new array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * let result = toFilled(array, '*', 2);
+ * console.log(result); // [1, 2, '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', 1, 4);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*');
+ * console.log(result); // ['*', '*', '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', -4, -1);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ */
 declare function toFilled<T, U>(arr: readonly T[], value: U, start: number, end: number): Array<T | U>;
 
 export { toFilled };

package/dist/array/toFilled.d.ts

@@ -6,8 +6,6 @@
  * @template U - The type of the value to fill the new array with.
  * @param {Array<T>} arr - The array to base the new array on.
  * @param {U} value - The value to fill the new array with.
- * @param {number} [start=0] - The start position. Defaults to 0.
- * @param {number} [end=arr.length] - The end position. Defaults to the array's length.
  * @returns {Array<T | U>} The new array with the filled values.
  *
  * @example
@@ -29,7 +27,66 @@
  * console.log(array); // [1, 2, 3, 4, 5]
  */
 declare function toFilled<T, U>(arr: readonly T[], value: U): Array<T | U>;
+/**
+ * Creates a new array filled with the specified value from the start position up to, but not including, the end position.
+ * This function does not mutate the original array.
+ *
+ * @template T - The type of elements in the original array.
+ * @template U - The type of the value to fill the new array with.
+ * @param {Array<T>} arr - The array to base the new array on.
+ * @param {U} value - The value to fill the new array with.
+ * @param {number} [start=0] - The start position. Defaults to 0.
+ * @returns {Array<T | U>} The new array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * let result = toFilled(array, '*', 2);
+ * console.log(result); // [1, 2, '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', 1, 4);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*');
+ * console.log(result); // ['*', '*', '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', -4, -1);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ */
 declare function toFilled<T, U>(arr: readonly T[], value: U, start: number): Array<T | U>;
+/**
+ * Creates a new array filled with the specified value from the start position up to, but not including, the end position.
+ * This function does not mutate the original array.
+ *
+ * @template T - The type of elements in the original array.
+ * @template U - The type of the value to fill the new array with.
+ * @param {Array<T>} arr - The array to base the new array on.
+ * @param {U} value - The value to fill the new array with.
+ * @param {number} [start=0] - The start position. Defaults to 0.
+ * @param {number} [end=arr.length] - The end position. Defaults to the array's length.
+ * @returns {Array<T | U>} The new array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3, 4, 5];
+ * let result = toFilled(array, '*', 2);
+ * console.log(result); // [1, 2, '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', 1, 4);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*');
+ * console.log(result); // ['*', '*', '*', '*', '*']
+ * console.log(array); // [1, 2, 3, 4, 5]
+ *
+ * result = toFilled(array, '*', -4, -1);
+ * console.log(result); // [1, '*', '*', '*', 5]
+ * console.log(array); // [1, 2, 3, 4, 5]
+ */
 declare function toFilled<T, U>(arr: readonly T[], value: U, start: number, end: number): Array<T | U>;
 
 export { toFilled };

package/dist/array/zip.d.mts

@@ -6,23 +6,81 @@
  * 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.
- * @param arr1
- * @returns {T[][]} A new array of tuples containing the corresponding elements from the input arrays.
+ * @template T
+ * @param {T[]} arr1 - The first array to zip.
+ * @returns {Array<[T]>} A new array of tuples containing the corresponding elements from the input arrays.
+ *
+ * @example
+ * const arr1 = [1, 2, 3];
+ * const result = zip(arr1);
+ * // result will be [[1], [2], [3]]
+ */
+declare function zip<T>(arr1: readonly T[]): Array<[T]>;
+/**
+ * Combines multiple arrays into a single array of tuples.
+ *
+ * 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.
+ *
+ * @template T, U
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @returns {Array<[T, U]>} 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']]
+ */
+declare function zip<T, U>(arr1: readonly T[], arr2: readonly U[]): Array<[T, U]>;
+/**
+ * Combines multiple arrays into a single array of tuples.
+ *
+ * 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.
+ *
+ * @template T, U, V
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @returns {Array<[T, U, V]>} 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 arr3 = [true, false];
- * const result2 = zip(arr1, arr2, arr3);
- * // result2 will be [[1, 'a', true], [2, 'b', false], [3, 'c', undefined]]
+ * const result = zip(arr1, arr2, arr3);
+ * // result will be [[1, 'a', true], [2, 'b', false], [3, 'c', undefined]]
  */
-declare function zip<T>(arr1: readonly T[]): Array<[T]>;
-declare function zip<T, U>(arr1: readonly T[], arr2: readonly U[]): Array<[T, U]>;
 declare function zip<T, U, V>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[]): Array<[T, U, V]>;
+/**
+ * Combines multiple arrays into a single array of tuples.
+ *
+ * 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.
+ *
+ * @template T, U, V, W
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @param {W[]} arr4 - The fourth array to zip.
+ * @returns {Array<[T, U, V, W]>} 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 arr3 = [true, false];
+ * const arr4 = [null, null, null];
+ * const result = zip(arr1, arr2, arr3, arr4);
+ * // result will be [[1, 'a', true, null], [2, 'b', false, null], [3, 'c', undefined, null]]
+ */
 declare function zip<T, U, V, W>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[], arr4: readonly W[]): Array<[T, U, V, W]>;
 
 export { zip };

package/dist/array/zip.d.ts

@@ -6,23 +6,81 @@
  * 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.
- * @param arr1
- * @returns {T[][]} A new array of tuples containing the corresponding elements from the input arrays.
+ * @template T
+ * @param {T[]} arr1 - The first array to zip.
+ * @returns {Array<[T]>} A new array of tuples containing the corresponding elements from the input arrays.
+ *
+ * @example
+ * const arr1 = [1, 2, 3];
+ * const result = zip(arr1);
+ * // result will be [[1], [2], [3]]
+ */
+declare function zip<T>(arr1: readonly T[]): Array<[T]>;
+/**
+ * Combines multiple arrays into a single array of tuples.
+ *
+ * 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.
+ *
+ * @template T, U
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @returns {Array<[T, U]>} 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']]
+ */
+declare function zip<T, U>(arr1: readonly T[], arr2: readonly U[]): Array<[T, U]>;
+/**
+ * Combines multiple arrays into a single array of tuples.
+ *
+ * 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.
+ *
+ * @template T, U, V
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @returns {Array<[T, U, V]>} 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 arr3 = [true, false];
- * const result2 = zip(arr1, arr2, arr3);
- * // result2 will be [[1, 'a', true], [2, 'b', false], [3, 'c', undefined]]
+ * const result = zip(arr1, arr2, arr3);
+ * // result will be [[1, 'a', true], [2, 'b', false], [3, 'c', undefined]]
  */
-declare function zip<T>(arr1: readonly T[]): Array<[T]>;
-declare function zip<T, U>(arr1: readonly T[], arr2: readonly U[]): Array<[T, U]>;
 declare function zip<T, U, V>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[]): Array<[T, U, V]>;
+/**
+ * Combines multiple arrays into a single array of tuples.
+ *
+ * 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.
+ *
+ * @template T, U, V, W
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @param {W[]} arr4 - The fourth array to zip.
+ * @returns {Array<[T, U, V, W]>} 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 arr3 = [true, false];
+ * const arr4 = [null, null, null];
+ * const result = zip(arr1, arr2, arr3, arr4);
+ * // result will be [[1, 'a', true, null], [2, 'b', false, null], [3, 'c', undefined, null]]
+ */
 declare function zip<T, U, V, W>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[], arr4: readonly W[]): Array<[T, U, V, W]>;
 
 export { zip };

package/dist/array/zipObject.d.mts

@@ -10,7 +10,7 @@
  * @template V - The type of elements in the array.
  * @param {P[]} keys - An array of property names.
  * @param {V[]} values - An array of values corresponding to the property names.
- * @returns {{ [K in P]: V }} A new object composed of the given property names and values.
+ * @returns {Record<P, V>} - A new object composed of the given property names and values.
  *
  * @example
  * const keys = ['a', 'b', 'c'];
@@ -28,8 +28,6 @@
  * const result2 = zipObject(keys2, values2);
  * // result2 will be { a: 1, b: 2 }
  */
-declare function zipObject<P extends PropertyKey, V>(keys: P[], values: V[]): {
-    [K in P]: V;
-};
+declare function zipObject<P extends PropertyKey, V>(keys: P[], values: V[]): Record<P, V>;
 
 export { zipObject };

package/dist/array/zipObject.d.ts

@@ -10,7 +10,7 @@
  * @template V - The type of elements in the array.
  * @param {P[]} keys - An array of property names.
  * @param {V[]} values - An array of values corresponding to the property names.
- * @returns {{ [K in P]: V }} A new object composed of the given property names and values.
+ * @returns {Record<P, V>} - A new object composed of the given property names and values.
  *
  * @example
  * const keys = ['a', 'b', 'c'];
@@ -28,8 +28,6 @@
  * const result2 = zipObject(keys2, values2);
  * // result2 will be { a: 1, b: 2 }
  */
-declare function zipObject<P extends PropertyKey, V>(keys: P[], values: V[]): {
-    [K in P]: V;
-};
+declare function zipObject<P extends PropertyKey, V>(keys: P[], values: V[]): Record<P, V>;
 
 export { zipObject };

package/dist/array/zipWith.d.mts

@@ -5,14 +5,8 @@
  * is the result of applying the combiner function to the corresponding elements of the input arrays.
  *
  * @template T - The type of elements in the first array.
- * @template U - The type of elements in the second array (optional).
- * @template V - The type of elements in the third array (optional).
- * @template W - The type of elements in the fourth array (optional).
  * @template R - The type of elements in the resulting array.
  * @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 {(...items: T[]) => R} 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.
  *
@@ -32,8 +26,47 @@
  * // result will be [`135`, `246`]
  */
 declare function zipWith<T, R>(arr1: readonly T[], combine: (item: T) => R): R[];
+/**
+ * Combines two arrays into a single array using a custom combiner function.
+ *
+ * @template T - The type of elements in the first array.
+ * @template U - The type of elements in the second array.
+ * @template R - The type of elements in the resulting array.
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {(item1: T, item2: U) => R} 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.
+ */
 declare function zipWith<T, U, R>(arr1: readonly T[], arr2: readonly U[], combine: (item1: T, item2: U) => R): R[];
+/**
+ * Combines three arrays into a single array using a custom combiner function.
+ *
+ * @template T - The type of elements in the first array.
+ * @template U - The type of elements in the second array.
+ * @template V - The type of elements in the third array.
+ * @template R - The type of elements in the resulting array.
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @param {(item1: T, item2: U, item3: V) => R} 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.
+ */
 declare function zipWith<T, U, V, R>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[], combine: (item1: T, item2: U, item3: V) => R): R[];
+/**
+ * Combines four arrays into a single array using a custom combiner function.
+ *
+ * @template T - The type of elements in the first array.
+ * @template U - The type of elements in the second array.
+ * @template V - The type of elements in the third array.
+ * @template W - The type of elements in the fourth array.
+ * @template R - The type of elements in the resulting array.
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @param {W[]} arr4 - The fourth array to zip.
+ * @param {(item1: T, item2: U, item3: V, item4: W) => R} 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.
+ */
 declare function zipWith<T, U, V, W, R>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[], arr4: readonly W[], combine: (item1: T, item2: U, item3: V, item4: W) => R): R[];
 
 export { zipWith };

package/dist/array/zipWith.d.ts

@@ -5,14 +5,8 @@
  * is the result of applying the combiner function to the corresponding elements of the input arrays.
  *
  * @template T - The type of elements in the first array.
- * @template U - The type of elements in the second array (optional).
- * @template V - The type of elements in the third array (optional).
- * @template W - The type of elements in the fourth array (optional).
  * @template R - The type of elements in the resulting array.
  * @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 {(...items: T[]) => R} 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.
  *
@@ -32,8 +26,47 @@
  * // result will be [`135`, `246`]
  */
 declare function zipWith<T, R>(arr1: readonly T[], combine: (item: T) => R): R[];
+/**
+ * Combines two arrays into a single array using a custom combiner function.
+ *
+ * @template T - The type of elements in the first array.
+ * @template U - The type of elements in the second array.
+ * @template R - The type of elements in the resulting array.
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {(item1: T, item2: U) => R} 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.
+ */
 declare function zipWith<T, U, R>(arr1: readonly T[], arr2: readonly U[], combine: (item1: T, item2: U) => R): R[];
+/**
+ * Combines three arrays into a single array using a custom combiner function.
+ *
+ * @template T - The type of elements in the first array.
+ * @template U - The type of elements in the second array.
+ * @template V - The type of elements in the third array.
+ * @template R - The type of elements in the resulting array.
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @param {(item1: T, item2: U, item3: V) => R} 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.
+ */
 declare function zipWith<T, U, V, R>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[], combine: (item1: T, item2: U, item3: V) => R): R[];
+/**
+ * Combines four arrays into a single array using a custom combiner function.
+ *
+ * @template T - The type of elements in the first array.
+ * @template U - The type of elements in the second array.
+ * @template V - The type of elements in the third array.
+ * @template W - The type of elements in the fourth array.
+ * @template R - The type of elements in the resulting array.
+ * @param {T[]} arr1 - The first array to zip.
+ * @param {U[]} arr2 - The second array to zip.
+ * @param {V[]} arr3 - The third array to zip.
+ * @param {W[]} arr4 - The fourth array to zip.
+ * @param {(item1: T, item2: U, item3: V, item4: W) => R} 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.
+ */
 declare function zipWith<T, U, V, W, R>(arr1: readonly T[], arr2: readonly U[], arr3: readonly V[], arr4: readonly W[], combine: (item1: T, item2: U, item3: V, item4: W) => R): R[];
 
 export { zipWith };