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

package/dist/compat/array/difference.d.mts

@@ -1,3 +1,25 @@
+/**
+ * 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.
+ */
 declare function difference<T>(arr: readonly T[], ...values: Array<readonly T[]>): T[];
 
 export { difference };

package/dist/compat/array/difference.d.ts

@@ -1,3 +1,25 @@
+/**
+ * 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.
+ */
 declare function difference<T>(arr: readonly T[], ...values: Array<readonly T[]>): T[];
 
 export { difference };

package/dist/compat/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, S, V
+ * @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 to the end.
+ *
+ * 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, S, V
+ * @param {Array<T | U>} array - The array to fill.
+ * @param {U} value - The value to fill the array with.
+ * @param {S} [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, S>(array: Array<T | U>, value: U, start: S): 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, S>(array: Array<T | U>, value: U, start: S): Array<T | U>;
 declare function fill<T, U, S, V>(array: Array<T | U>, value: U, start: S, end: V): Array<T | U>;
 
 export { fill };

package/dist/compat/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, S, V
+ * @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 to the end.
+ *
+ * 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, S, V
+ * @param {Array<T | U>} array - The array to fill.
+ * @param {U} value - The value to fill the array with.
+ * @param {S} [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, S>(array: Array<T | U>, value: U, start: S): 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, S>(array: Array<T | U>, value: U, start: S): Array<T | U>;
 declare function fill<T, U, S, V>(array: Array<T | U>, value: U, start: S, end: V): Array<T | U>;
 
 export { fill };

package/dist/compat/array/find.mjs

@@ -8,7 +8,7 @@ function find(source, doesMatch) {
         values = Object.values(source);
     }
     switch (typeof doesMatch) {
-        case 'function': {
+        case "function": {
             if (!Array.isArray(source)) {
                 const entries = Object.entries(source);
                 for (let i = 0; i < entries.length; i++) {
@@ -23,7 +23,7 @@ function find(source, doesMatch) {
             }
             return values.find(doesMatch);
         }
-        case 'object': {
+        case "object": {
             if (Array.isArray(doesMatch) && doesMatch.length === 2) {
                 const key = doesMatch[0];
                 const value = doesMatch[1];
@@ -33,7 +33,7 @@ function find(source, doesMatch) {
                 return values.find(matches(doesMatch));
             }
         }
-        case 'string': {
+        case "string": {
             return values.find(property(doesMatch));
         }
     }

package/dist/compat/array/findIndex.mjs

@@ -4,10 +4,10 @@ import { matchesProperty } from '../predicate/matchesProperty.mjs';
 
 function findIndex(source, doesMatch) {
     switch (typeof doesMatch) {
-        case 'function': {
+        case "function": {
             return source.findIndex(doesMatch);
         }
-        case 'object': {
+        case "object": {
             if (Array.isArray(doesMatch) && doesMatch.length === 2) {
                 const key = doesMatch[0];
                 const value = doesMatch[1];
@@ -17,7 +17,7 @@ function findIndex(source, doesMatch) {
                 return source.findIndex(matches(doesMatch));
             }
         }
-        case 'string': {
+        case "string": {
             return source.findIndex(property(doesMatch));
         }
     }

package/dist/compat/index.js

@@ -2,11 +2,11 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const initial = require('../_chunk/initial-crEecP.js');
+const initial = require('../_chunk/initial-CMlK06.js');
 const promise_index = require('../_chunk/index-BGZDR9.js');
-const rest$1 = require('../_chunk/rest-Bzm2XK.js');
+const rest$1 = require('../_chunk/rest-CXB7TJ.js');
 const math_index = require('../math/index.js');
-const randomInt = require('../_chunk/randomInt-CF7bZK.js');
+const randomInt = require('../_chunk/randomInt-DJFj2K.js');
 const toMerged = require('../_chunk/toMerged-DN1PPP.js');
 const isWeakSet$1 = require('../_chunk/isWeakSet-CogETi.js');
 const isTypedArray$1 = require('../_chunk/isTypedArray-Dsrnb1.js');
@@ -114,7 +114,7 @@ function get(object, path, defaultValue) {
     if (Array.isArray(path)) {
         resolvedPath = path;
     }
-    else if (typeof path === 'string' && isDeepKey(path) && object?.[path] == null) {
+    else if (typeof path === "string" && isDeepKey(path) && object?.[path] == null) {
         resolvedPath = toPath(path);
     }
     else {
@@ -192,7 +192,7 @@ function isMatch(target, source) {
         return true;
     }
     switch (typeof source) {
-        case 'object': {
+        case "object": {
             if (source == null) {
                 return true;
             }
@@ -226,7 +226,7 @@ function isMatch(target, source) {
             }
             return true;
         }
-        case 'function': {
+        case "function": {
             if (Object.keys(source).length > 0) {
                 return isMatch(target, { ...source });
             }
@@ -294,7 +294,7 @@ function has(object, path) {
     if (Array.isArray(path)) {
         resolvedPath = path;
     }
-    else if (typeof path === 'string' && isDeepKey(path) && object?.[path] == null) {
+    else if (typeof path === "string" && isDeepKey(path) && object?.[path] == null) {
         resolvedPath = toPath(path);
     }
     else {
@@ -307,7 +307,8 @@ function has(object, path) {
     for (let i = 0; i < resolvedPath.length; i++) {
         const key = resolvedPath[i];
         if (current == null || !Object.prototype.hasOwnProperty.call(current, key)) {
-            const isSparseIndex = (Array.isArray(current) || isArguments(current)) && isIndex(key) && key < current.length;
+            const isSparseIndex = (Array.isArray(current) || isArguments(current)) &&
+                isIndex(key) && key < current.length;
             if (!isSparseIndex) {
                 return false;
             }
@@ -338,7 +339,7 @@ function find(source, doesMatch) {
         values = Object.values(source);
     }
     switch (typeof doesMatch) {
-        case 'function': {
+        case "function": {
             if (!Array.isArray(source)) {
                 const entries = Object.entries(source);
                 for (let i = 0; i < entries.length; i++) {
@@ -353,7 +354,7 @@ function find(source, doesMatch) {
             }
             return values.find(doesMatch);
         }
-        case 'object': {
+        case "object": {
             if (Array.isArray(doesMatch) && doesMatch.length === 2) {
                 const key = doesMatch[0];
                 const value = doesMatch[1];
@@ -363,7 +364,7 @@ function find(source, doesMatch) {
                 return values.find(matches(doesMatch));
             }
         }
-        case 'string': {
+        case "string": {
             return values.find(property(doesMatch));
         }
     }
@@ -371,10 +372,10 @@ function find(source, doesMatch) {
 
 function findIndex(source, doesMatch) {
     switch (typeof doesMatch) {
-        case 'function': {
+        case "function": {
             return source.findIndex(doesMatch);
         }
-        case 'object': {
+        case "object": {
             if (Array.isArray(doesMatch) && doesMatch.length === 2) {
                 const key = doesMatch[0];
                 const value = doesMatch[1];
@@ -384,7 +385,7 @@ function findIndex(source, doesMatch) {
                 return source.findIndex(matches(doesMatch));
             }
         }
-        case 'string': {
+        case "string": {
             return source.findIndex(property(doesMatch));
         }
     }
@@ -558,7 +559,11 @@ function size(target) {
 }
 
 function set(obj, path, value) {
-    const resolvedPath = Array.isArray(path) ? path : typeof path === 'string' ? toPath(path) : [path];
+    const resolvedPath = Array.isArray(path)
+        ? path
+        : typeof path === "string"
+            ? toPath(path)
+            : [path];
     let current = obj;
     for (let i = 0; i < resolvedPath.length - 1; i++) {
         const key = resolvedPath[i];
@@ -668,30 +673,32 @@ function identity(x) {
 }
 
 function mapKeys(object, getNewKey) {
-    getNewKey = getNewKey ?? identity;
+    getNewKey = getNewKey ??
+        identity;
     switch (typeof getNewKey) {
-        case 'string':
-        case 'symbol':
-        case 'number':
-        case 'object': {
+        case "string":
+        case "symbol":
+        case "number":
+        case "object": {
             return toMerged.mapKeys(object, property(getNewKey));
         }
-        case 'function': {
+        case "function": {
             return toMerged.mapKeys(object, getNewKey);
         }
     }
 }
 
 function mapValues(object, getNewValue) {
-    getNewValue = getNewValue ?? identity;
+    getNewValue = getNewValue ??
+        identity;
     switch (typeof getNewValue) {
-        case 'string':
-        case 'symbol':
-        case 'number':
-        case 'object': {
+        case "string":
+        case "symbol":
+        case "number":
+        case "object": {
             return toMerged.mapValues(object, property(getNewValue));
         }
-        case 'function': {
+        case "function": {
             return toMerged.mapValues(object, getNewValue);
         }
     }
@@ -740,7 +747,7 @@ function mergeWith(object, ...otherArgs) {
     return result;
 }
 function mergeWithDeep(target, source, merge, stack) {
-    if (source == null || typeof source !== 'object') {
+    if (source == null || typeof source !== "object") {
         return target;
     }
     if (stack.has(source)) {
@@ -764,11 +771,13 @@ function mergeWithDeep(target, source, merge, stack) {
         if (isArguments(targetValue)) {
             targetValue = { ...targetValue };
         }
-        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(sourceValue)) {
+        if (typeof Buffer !== "undefined" && Buffer.isBuffer(sourceValue)) {
             sourceValue = cloneDeep(sourceValue);
         }
         if (Array.isArray(sourceValue)) {
-            targetValue = typeof targetValue === 'object' ? Array.from(targetValue ?? []) : [];
+            targetValue = typeof targetValue === "object"
+                ? Array.from(targetValue ?? [])
+                : [];
         }
         const merged = merge(targetValue, sourceValue, key, target, source, stack);
         if (merged != null) {
@@ -848,13 +857,13 @@ function isWeakSet(value) {
     return isWeakSet$1.isWeakSet(value);
 }
 
-const startsWith = (str, target, position = 0) => {
+function startsWith(str, target, position = 0) {
     return str.startsWith(target, position);
-};
+}
 
-const endsWith = (str, target, position = str.length) => {
+function endsWith(str, target, position = str.length) {
     return str.endsWith(target, position);
-};
+}
 
 function padStart(str, length = 0, chars = ' ') {
     return str.padStart(length, chars);

package/dist/compat/math/max.d.mts

@@ -1,19 +1,30 @@
 /**
  * Finds the element in an array that has the maximum value.
  *
- * @template T - The type of elements in the array.
- * @param {T[]} items The array of elements to search.
- * @returns {T | undefined} The element with the maximum value.
+ * @param {[T, ...T[]]} items - The array of elements to search.
+ * @returns {T | undefined} - The element with the maximum value, or undefined if the array is empty.
  * @example
  * // Returns 9
- * max([3, 1, 4, 1, 5, 9])
+ * max([3, 1, 4, 1, 5, 9]);
  *
  * @example
  * // Returns 8
- * max([0, -3, 2, 8, 7])
+ * max([0, -3, 2, 8, 7]);
  */
 declare function max<T>(items: readonly [T, ...T[]]): T;
+/**
+ * Finds the element in an array that has the maximum value.
+ * Returns undefined when no arguments are provided.
+ * @returns {undefined}
+ */
 declare function max(): undefined;
+/**
+ * Finds the element in an array that has the maximum value.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} [items] - The array of elements to search. Defaults to an empty array.
+ * @returns {T | undefined} - The element with the maximum value, or undefined if the array is empty.
+ */
 declare function max<T>(items?: readonly T[]): T | undefined;
 
 export { max };

package/dist/compat/math/max.d.ts

@@ -1,19 +1,30 @@
 /**
  * Finds the element in an array that has the maximum value.
  *
- * @template T - The type of elements in the array.
- * @param {T[]} items The array of elements to search.
- * @returns {T | undefined} The element with the maximum value.
+ * @param {[T, ...T[]]} items - The array of elements to search.
+ * @returns {T | undefined} - The element with the maximum value, or undefined if the array is empty.
  * @example
  * // Returns 9
- * max([3, 1, 4, 1, 5, 9])
+ * max([3, 1, 4, 1, 5, 9]);
  *
  * @example
  * // Returns 8
- * max([0, -3, 2, 8, 7])
+ * max([0, -3, 2, 8, 7]);
  */
 declare function max<T>(items: readonly [T, ...T[]]): T;
+/**
+ * Finds the element in an array that has the maximum value.
+ * Returns undefined when no arguments are provided.
+ * @returns {undefined}
+ */
 declare function max(): undefined;
+/**
+ * Finds the element in an array that has the maximum value.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} [items] - The array of elements to search. Defaults to an empty array.
+ * @returns {T | undefined} - The element with the maximum value, or undefined if the array is empty.
+ */
 declare function max<T>(items?: readonly T[]): T | undefined;
 
 export { max };

package/dist/compat/math/min.d.mts

@@ -2,18 +2,30 @@
  * Finds the element in an array that has the minimum value.
  *
  * @template T - The type of elements in the array.
- * @param {T[]} items The array of elements to search.
- * @returns {T | undefined} The element with the minimum value.
+ * @param {[T, ...T[]]} items - The array of elements to search.
+ * @returns {T | undefined} - The element with the minimum value, or undefined if the array is empty.
  * @example
  * // Returns 1
- * min([3, 1, 4, 1, 5, 9])
+ * min([3, 1, 4, 1, 5, 9]);
  *
  * @example
  * // Returns -3
- * min([0, -3, 2, 8, 7])
+ * min([0, -3, 2, 8, 7]);
  */
 declare function min<T>(items: readonly [T, ...T[]]): T;
+/**
+ * Finds the element in an array that has the minimum value.
+ * Returns undefined when no arguments are provided.
+ * @returns {undefined}
+ */
 declare function min(): undefined;
+/**
+ * Finds the element in an array that has the minimum value.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} [items] - The array of elements to search. Defaults to an empty array.
+ * @returns {T | undefined} - The element with the minimum value, or undefined if the array is empty.
+ */
 declare function min<T>(items?: readonly T[]): T | undefined;
 
 export { min };

package/dist/compat/math/min.d.ts

@@ -2,18 +2,30 @@
  * Finds the element in an array that has the minimum value.
  *
  * @template T - The type of elements in the array.
- * @param {T[]} items The array of elements to search.
- * @returns {T | undefined} The element with the minimum value.
+ * @param {[T, ...T[]]} items - The array of elements to search.
+ * @returns {T | undefined} - The element with the minimum value, or undefined if the array is empty.
  * @example
  * // Returns 1
- * min([3, 1, 4, 1, 5, 9])
+ * min([3, 1, 4, 1, 5, 9]);
  *
  * @example
  * // Returns -3
- * min([0, -3, 2, 8, 7])
+ * min([0, -3, 2, 8, 7]);
  */
 declare function min<T>(items: readonly [T, ...T[]]): T;
+/**
+ * Finds the element in an array that has the minimum value.
+ * Returns undefined when no arguments are provided.
+ * @returns {undefined}
+ */
 declare function min(): undefined;
+/**
+ * Finds the element in an array that has the minimum value.
+ *
+ * @template T - The type of elements in the array.
+ * @param {T[]} [items] - The array of elements to search. Defaults to an empty array.
+ * @returns {T | undefined} - The element with the minimum value, or undefined if the array is empty.
+ */
 declare function min<T>(items?: readonly T[]): T | undefined;
 
 export { min };

package/dist/compat/object/get.mjs

@@ -7,7 +7,7 @@ function get(object, path, defaultValue) {
     if (Array.isArray(path)) {
         resolvedPath = path;
     }
-    else if (typeof path === 'string' && isDeepKey(path) && object?.[path] == null) {
+    else if (typeof path === "string" && isDeepKey(path) && object?.[path] == null) {
         resolvedPath = toPath(path);
     }
     else {

package/dist/compat/object/has.mjs

@@ -8,7 +8,7 @@ function has(object, path) {
     if (Array.isArray(path)) {
         resolvedPath = path;
     }
-    else if (typeof path === 'string' && isDeepKey(path) && object?.[path] == null) {
+    else if (typeof path === "string" && isDeepKey(path) && object?.[path] == null) {
         resolvedPath = toPath(path);
     }
     else {
@@ -21,7 +21,8 @@ function has(object, path) {
     for (let i = 0; i < resolvedPath.length; i++) {
         const key = resolvedPath[i];
         if (current == null || !Object.prototype.hasOwnProperty.call(current, key)) {
-            const isSparseIndex = (Array.isArray(current) || isArguments(current)) && isIndex(key) && key < current.length;
+            const isSparseIndex = (Array.isArray(current) || isArguments(current)) &&
+                isIndex(key) && key < current.length;
             if (!isSparseIndex) {
                 return false;
             }

package/dist/compat/object/mapKeys.mjs

@@ -3,15 +3,16 @@ import { identity } from '../_internal/identity.mjs';
 import { property } from './property.mjs';
 
 function mapKeys(object, getNewKey) {
-    getNewKey = getNewKey ?? identity;
+    getNewKey = getNewKey ??
+        identity;
     switch (typeof getNewKey) {
-        case 'string':
-        case 'symbol':
-        case 'number':
-        case 'object': {
+        case "string":
+        case "symbol":
+        case "number":
+        case "object": {
             return mapKeys$1(object, property(getNewKey));
         }
-        case 'function': {
+        case "function": {
             return mapKeys$1(object, getNewKey);
         }
     }

package/dist/compat/object/mapValues.mjs

@@ -3,15 +3,16 @@ import { identity } from '../_internal/identity.mjs';
 import { property } from './property.mjs';
 
 function mapValues(object, getNewValue) {
-    getNewValue = getNewValue ?? identity;
+    getNewValue = getNewValue ??
+        identity;
     switch (typeof getNewValue) {
-        case 'string':
-        case 'symbol':
-        case 'number':
-        case 'object': {
+        case "string":
+        case "symbol":
+        case "number":
+        case "object": {
             return mapValues$1(object, property(getNewValue));
         }
-        case 'function': {
+        case "function": {
             return mapValues$1(object, getNewValue);
         }
     }