es-toolkit 1.17.0-dev.533 → 1.17.0-dev.536

package/dist/_chunk/{initial-crEecP.js → initial-CMlK06.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-const randomInt = require('./randomInt-CF7bZK.js');
+const randomInt = require('./randomInt-DJFj2K.js');
 
 function at(arr, indices) {
     const result = [];
@@ -172,7 +172,7 @@ function intersectionWith(firstArr, secondArr, areItemsEqual) {
     });
 }
 
-function join(array, separator = ',') {
+function join(array, separator = ",") {
     return array.join(separator);
 }
 
@@ -389,7 +389,7 @@ function xorWith(arr1, arr2, areElementsEqual) {
 
 function zip(...arrs) {
     const result = [];
-    const maxIndex = Math.max(...arrs.map(x => x.length));
+    const maxIndex = Math.max(...arrs.map((x) => x.length));
     for (let i = 0; i < maxIndex; i++) {
         const element = [];
         for (const arr of arrs) {
@@ -412,9 +412,9 @@ function zipWith(arr1, ...rest) {
     const arrs = [arr1, ...rest.slice(0, -1)];
     const combine = rest[rest.length - 1];
     const result = [];
-    const maxIndex = Math.max(...arrs.map(arr => arr.length));
+    const maxIndex = Math.max(...arrs.map((arr) => arr.length));
     for (let i = 0; i < maxIndex; i++) {
-        const elements = arrs.map(arr => arr[i]);
+        const elements = arrs.map((arr) => arr[i]);
         result.push(combine(...elements));
     }
     return result;

package/dist/_chunk/{randomInt-CF7bZK.js → randomInt-DJFj2K.js}

@@ -6,7 +6,7 @@ function random(minimum, maximum) {
         minimum = 0;
     }
     if (minimum >= maximum) {
-        throw new Error('Invalid input: The maximum value must be greater than the minimum value.');
+        throw new Error("Invalid input: The maximum value must be greater than the minimum value.");
     }
     return Math.random() * (maximum - minimum) + minimum;
 }

package/dist/_chunk/{rest-Bzm2XK.js → rest-CXB7TJ.js}

@@ -1,8 +1,8 @@
 'use strict';
 
-const before = (n, func) => {
+function before(n, func) {
     if (!Number.isInteger(n) || n < 0) {
-        throw new Error('n must be a non-negative integer.');
+        throw new Error("n must be a non-negative integer.");
     }
     let counter = 0;
     return ((...args) => {
@@ -11,9 +11,9 @@ const before = (n, func) => {
         }
         return undefined;
     });
-};
+}
 
-const after = (n, func) => {
+function after(n, func) {
     if (!Number.isInteger(n) || n < 0) {
         throw new Error(`n must be a non-negative integer.`);
     }
@@ -24,7 +24,7 @@ const after = (n, func) => {
         }
         return undefined;
     });
-};
+}
 
 function debounce(func, debounceMs, { signal } = {}) {
     let timeoutId = null;
@@ -49,7 +49,7 @@ function debounce(func, debounceMs, { signal } = {}) {
             timeoutId = null;
         }
     };
-    signal?.addEventListener('abort', onAbort, { once: true });
+    signal?.addEventListener("abort", onAbort, { once: true });
     return debounced;
 }
 

package/dist/array/fill.d.mts

@@ -1,3 +1,58 @@
+/**
+ * Fills the whole array with a specified value.
+ *
+ * This function mutates the original array and replaces its elements with the provided value, starting from the specified
+ * start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the
+ * entire array.
+ *
+ * @template T, U
+ * @param {Array<T | U>} array - The array to fill.
+ * @param {U} value - The value to fill the array with.
+ * @returns {Array<T | U>} The array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * const result = fill(array, 'a');
+ * // => ['a', 'a', 'a']
+ *
+ * const result = fill(Array(3), 2);
+ * // => [2, 2, 2]
+ *
+ * const result = fill([4, 6, 8, 10], '*', 1, 3);
+ * // => [4, '*', '*', 10]
+ *
+ * const result = fill(array, '*', -2, -1);
+ * // => [1, '*', 3]
+ */
+declare function fill<T>(array: unknown[], value: T): T[];
+/**
+ * Fills elements of an array with a specified value from the start position up to the end of the array.
+ *
+ * This function mutates the original array and replaces its elements with the provided value, starting from the specified
+ * start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the
+ * entire array.
+ *
+ * @template T, U
+ * @param {Array<T | U>} array - The array to fill.
+ * @param {U} value - The value to fill the array with.
+ * @param {number} [start=0] - The start position. Defaults to 0.
+ * @returns {Array<T | U>} The array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * const result = fill(array, 'a');
+ * // => ['a', 'a', 'a']
+ *
+ * const result = fill(Array(3), 2);
+ * // => [2, 2, 2]
+ *
+ * const result = fill([4, 6, 8, 10], '*', 1, 3);
+ * // => [4, '*', '*', 10]
+ *
+ * const result = fill(array, '*', -2, -1);
+ * // => [1, '*', 3]
+ */
+declare function fill<T, U>(array: Array<T | U>, value: U, start: number): Array<T | U>;
 /**
  * Fills elements of an array with a specified value from the start position up to, but not including, the end position.
  *
@@ -26,8 +81,6 @@
  * const result = fill(array, '*', -2, -1);
  * // => [1, '*', 3]
  */
-declare function fill<T>(array: unknown[], value: T): T[];
-declare function fill<T, U>(array: Array<T | U>, value: U, start: number): Array<T | U>;
 declare function fill<T, U>(array: Array<T | U>, value: U, start: number, end: number): Array<T | U>;
 
 export { fill };

package/dist/array/fill.d.ts

@@ -1,3 +1,58 @@
+/**
+ * Fills the whole array with a specified value.
+ *
+ * This function mutates the original array and replaces its elements with the provided value, starting from the specified
+ * start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the
+ * entire array.
+ *
+ * @template T, U
+ * @param {Array<T | U>} array - The array to fill.
+ * @param {U} value - The value to fill the array with.
+ * @returns {Array<T | U>} The array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * const result = fill(array, 'a');
+ * // => ['a', 'a', 'a']
+ *
+ * const result = fill(Array(3), 2);
+ * // => [2, 2, 2]
+ *
+ * const result = fill([4, 6, 8, 10], '*', 1, 3);
+ * // => [4, '*', '*', 10]
+ *
+ * const result = fill(array, '*', -2, -1);
+ * // => [1, '*', 3]
+ */
+declare function fill<T>(array: unknown[], value: T): T[];
+/**
+ * Fills elements of an array with a specified value from the start position up to the end of the array.
+ *
+ * This function mutates the original array and replaces its elements with the provided value, starting from the specified
+ * start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the
+ * entire array.
+ *
+ * @template T, U
+ * @param {Array<T | U>} array - The array to fill.
+ * @param {U} value - The value to fill the array with.
+ * @param {number} [start=0] - The start position. Defaults to 0.
+ * @returns {Array<T | U>} The array with the filled values.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * const result = fill(array, 'a');
+ * // => ['a', 'a', 'a']
+ *
+ * const result = fill(Array(3), 2);
+ * // => [2, 2, 2]
+ *
+ * const result = fill([4, 6, 8, 10], '*', 1, 3);
+ * // => [4, '*', '*', 10]
+ *
+ * const result = fill(array, '*', -2, -1);
+ * // => [1, '*', 3]
+ */
+declare function fill<T, U>(array: Array<T | U>, value: U, start: number): Array<T | U>;
 /**
  * Fills elements of an array with a specified value from the start position up to, but not including, the end position.
  *
@@ -26,8 +81,6 @@
  * const result = fill(array, '*', -2, -1);
  * // => [1, '*', 3]
  */
-declare function fill<T>(array: unknown[], value: T): T[];
-declare function fill<T, U>(array: Array<T | U>, value: U, start: number): Array<T | U>;
 declare function fill<T, U>(array: Array<T | U>, value: U, start: number, end: number): Array<T | U>;
 
 export { fill };

package/dist/array/head.d.mts

@@ -5,19 +5,30 @@
  * If the array is empty, the function returns `undefined`.
  *
  * @template T - The type of elements in the array.
- * @param {T[]} arr - The array from which to get the first element.
- * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ * @param {[T, ...T[]]} arr - A non-empty array from which to get the first element.
+ * @returns {T} The first element of the array.
  *
  * @example
  * const arr = [1, 2, 3];
  * const firstElement = head(arr);
  * // firstElement will be 1
+ */
+declare function head<T>(arr: readonly [T, ...T[]]): T;
+/**
+ * Returns the first element of an array or `undefined` if the array is empty.
+ *
+ * This function takes an array and returns the first element of the array.
+ * If the array is empty, the function returns `undefined`.
  *
+ * @template T - The type of elements in the array.
+ * @param {T[]} arr - The array from which to get the first element.
+ * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ *
+ * @example
  * const emptyArr: number[] = [];
  * const noElement = head(emptyArr);
  * // noElement will be undefined
  */
-declare function head<T>(arr: readonly [T, ...T[]]): T;
 declare function head<T>(arr: readonly T[]): T | undefined;
 
 export { head };

package/dist/array/head.d.ts

@@ -5,19 +5,30 @@
  * If the array is empty, the function returns `undefined`.
  *
  * @template T - The type of elements in the array.
- * @param {T[]} arr - The array from which to get the first element.
- * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ * @param {[T, ...T[]]} arr - A non-empty array from which to get the first element.
+ * @returns {T} The first element of the array.
  *
  * @example
  * const arr = [1, 2, 3];
  * const firstElement = head(arr);
  * // firstElement will be 1
+ */
+declare function head<T>(arr: readonly [T, ...T[]]): T;
+/**
+ * Returns the first element of an array or `undefined` if the array is empty.
+ *
+ * This function takes an array and returns the first element of the array.
+ * If the array is empty, the function returns `undefined`.
  *
+ * @template T - The type of elements in the array.
+ * @param {T[]} arr - The array from which to get the first element.
+ * @returns {T | undefined} The first element of the array, or `undefined` if the array is empty.
+ *
+ * @example
  * const emptyArr: number[] = [];
  * const noElement = head(emptyArr);
  * // noElement will be undefined
  */
-declare function head<T>(arr: readonly [T, ...T[]]): T;
 declare function head<T>(arr: readonly T[]): T | undefined;
 
 export { head };

package/dist/array/index.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const initial = require('../_chunk/initial-crEecP.js');
+const initial = require('../_chunk/initial-CMlK06.js');
 
 function compareValues(a, b, order) {
     if (a < b) {

package/dist/array/join.d.mts

@@ -1,19 +1,15 @@
 /**
- *
- * Join elements of an array into a string.
+ * Joins elements of an array into a string.
  *
  * @template T - The type of elements in the array.
- * @param {readonly T[]} array - The array to join.
+ * @param {T[]} array - The array to join.
  * @param {string} separator - The separator used to join the elements, default is common separator `,`.
  * @returns {string} - Returns a string containing all elements of the array joined by the specified separator.
  *
  * @example
- * ```typescript
- * const arr = ["a","b","c"];
+ * const arr = ["a", "b", "c"];
  * const result = join(arr, "~");
  * console.log(result); // Output: "a~b~c"
- * ```
- *
  */
 declare function join<T>(array: readonly T[], separator?: string): string;
 

package/dist/array/join.d.ts

@@ -1,19 +1,15 @@
 /**
- *
- * Join elements of an array into a string.
+ * Joins elements of an array into a string.
  *
  * @template T - The type of elements in the array.
- * @param {readonly T[]} array - The array to join.
+ * @param {T[]} array - The array to join.
  * @param {string} separator - The separator used to join the elements, default is common separator `,`.
  * @returns {string} - Returns a string containing all elements of the array joined by the specified separator.
  *
  * @example
- * ```typescript
- * const arr = ["a","b","c"];
+ * const arr = ["a", "b", "c"];
  * const result = join(arr, "~");
  * console.log(result); // Output: "a~b~c"
- * ```
- *
  */
 declare function join<T>(array: readonly T[], separator?: string): string;
 

package/dist/array/join.mjs

@@ -1,4 +1,4 @@
-function join(array, separator = ',') {
+function join(array, separator = ",") {
     return array.join(separator);
 }
 

package/dist/array/last.d.mts

@@ -1,3 +1,26 @@
+/**
+ * Returns the last element of an array.
+ *
+ * This function takes an array and returns the last element of the array.
+ * If the array is empty, the function returns `undefined`.
+ *
+ * Unlike some implementations, this function is optimized for performance
+ * by directly accessing the last index of the array.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[...T[], T]} arr - The array from which to get the last element.
+ * @returns {T} The last element of the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const arr = [1, 2, 3];
+ * const lastElement = last(arr);
+ * // lastElement will be 3
+ *
+ * const emptyArr: number[] = [];
+ * const noElement = last(emptyArr);
+ * // noElement will be undefined
+ */
+declare function last<T>(arr: readonly [...T[], T]): T;
 /**
  * Returns the last element of an array.
  *
@@ -20,7 +43,6 @@
  * const noElement = last(emptyArr);
  * // noElement will be undefined
  */
-declare function last<T>(arr: readonly [...T[], T]): T;
 declare function last<T>(arr: readonly T[]): T | undefined;
 
 export { last };

package/dist/array/last.d.ts

@@ -1,3 +1,26 @@
+/**
+ * Returns the last element of an array.
+ *
+ * This function takes an array and returns the last element of the array.
+ * If the array is empty, the function returns `undefined`.
+ *
+ * Unlike some implementations, this function is optimized for performance
+ * by directly accessing the last index of the array.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[...T[], T]} arr - The array from which to get the last element.
+ * @returns {T} The last element of the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const arr = [1, 2, 3];
+ * const lastElement = last(arr);
+ * // lastElement will be 3
+ *
+ * const emptyArr: number[] = [];
+ * const noElement = last(emptyArr);
+ * // noElement will be undefined
+ */
+declare function last<T>(arr: readonly [...T[], T]): T;
 /**
  * Returns the last element of an array.
  *
@@ -20,7 +43,6 @@
  * const noElement = last(emptyArr);
  * // noElement will be undefined
  */
-declare function last<T>(arr: readonly [...T[], T]): T;
 declare function last<T>(arr: readonly T[]): T | undefined;
 
 export { last };

package/dist/array/maxBy.d.mts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the maximum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} The element with the maximum value as determined by the `getValue` function.
+ * @example
+ * maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 3 }
+ * maxBy([], x => x.a); // Returns: undefined
+ */
+declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the maximum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 3 }
  * maxBy([], x => x.a); // Returns: undefined
  */
-declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function maxBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { maxBy };

package/dist/array/maxBy.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the maximum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} The element with the maximum value as determined by the `getValue` function.
+ * @example
+ * maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 3 }
+ * maxBy([], x => x.a); // Returns: undefined
+ */
+declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the maximum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * maxBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 3 }
  * maxBy([], x => x.a); // Returns: undefined
  */
-declare function maxBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function maxBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { maxBy };

package/dist/array/minBy.d.mts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the minimum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} The element with the minimum value as determined by the `getValue` function.
+ * @example
+ * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 1 }
+ * minBy([], x => x.a); // Returns: undefined
+ */
+declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the minimum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 1 }
  * minBy([], x => x.a); // Returns: undefined
  */
-declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function minBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { minBy };

package/dist/array/minBy.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Finds the element in an array that has the minimum value when applying
+ * the `getValue` function to each element.
+ *
+ * @template T - The type of elements in the array.
+ * @param {[T, ...T[]]} items The nonempty array of elements to search.
+ * @param {(element: T) => number} getValue A function that selects a numeric value from each element.
+ * @returns {T} The element with the minimum value as determined by the `getValue` function.
+ * @example
+ * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 1 }
+ * minBy([], x => x.a); // Returns: undefined
+ */
+declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 /**
  * Finds the element in an array that has the minimum value when applying
  * the `getValue` function to each element.
@@ -10,7 +23,6 @@
  * minBy([{ a: 1 }, { a: 2 }, { a: 3 }], x => x.a); // Returns: { a: 1 }
  * minBy([], x => x.a); // Returns: undefined
  */
-declare function minBy<T>(items: readonly [T, ...T[]], getValue: (element: T) => number): T;
 declare function minBy<T>(items: readonly T[], getValue: (element: T) => number): T | undefined;
 
 export { minBy };

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 };