es-toolkit 1.13.1 → 1.14.0-dev.397

package/dist/compat/_internal/isArrayMatch.mjs

@@ -0,0 +1,24 @@
+import { isMatch } from '../predicate/isMatch.mjs';
+
+function isArrayMatch(target, source) {
+    if (source.length === 0) {
+        return true;
+    }
+    if (!Array.isArray(target)) {
+        return false;
+    }
+    const countedIndex = new Set();
+    for (let i = 0; i < source.length; i++) {
+        const sourceItem = source[i];
+        const index = target.findIndex((targetItem, index) => {
+            return isMatch(targetItem, sourceItem) && !countedIndex.has(index);
+        });
+        if (index === -1) {
+            return false;
+        }
+        countedIndex.add(index);
+    }
+    return true;
+}
+
+export { isArrayMatch };

package/dist/compat/_internal/isDeepKey.mjs

@@ -0,0 +1,15 @@
+const IS_PLAIN = /^\w*$/;
+const IS_DEEP = /\.|\[(?:[^[\]]*|(["'])(?:(?!\1)[^\\]|\\.)*?\1)\]/;
+function isDeepKey(key) {
+    switch (typeof key) {
+        case 'number':
+        case 'symbol': {
+            return false;
+        }
+        case 'string': {
+            return !IS_PLAIN.test(key) && IS_DEEP.test(key);
+        }
+    }
+}
+
+export { isDeepKey };

package/dist/compat/_internal/isIndex.mjs

@@ -0,0 +1,16 @@
+const IS_UNSIGNED_INTEGER = /^(?:0|[1-9]\d*)$/;
+function isIndex(value) {
+    switch (typeof value) {
+        case 'number': {
+            return Number.isInteger(value) && value >= 0 && value < Number.MAX_SAFE_INTEGER;
+        }
+        case 'symbol': {
+            return false;
+        }
+        case 'string': {
+            return IS_UNSIGNED_INTEGER.test(value);
+        }
+    }
+}
+
+export { isIndex };

package/dist/compat/_internal/isMapMatch.mjs

@@ -0,0 +1,18 @@
+import { isMatch } from '../predicate/isMatch.mjs';
+
+function isMapMatch(target, source) {
+    if (source.size === 0) {
+        return true;
+    }
+    if (!(target instanceof Map)) {
+        return false;
+    }
+    for (const [key, value] of source.entries()) {
+        if (!isMatch(target.get(key), value)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+export { isMapMatch };

package/dist/compat/_internal/isSetMatch.mjs

@@ -0,0 +1,13 @@
+import { isArrayMatch } from './isArrayMatch.mjs';
+
+function isSetMatch(target, source) {
+    if (source.size === 0) {
+        return true;
+    }
+    if (!(target instanceof Set)) {
+        return false;
+    }
+    return isArrayMatch([...target], [...source]);
+}
+
+export { isSetMatch };

package/dist/compat/_internal/tags.mjs

@@ -0,0 +1,28 @@
+const regexpTag = '[object RegExp]';
+const stringTag = '[object String]';
+const numberTag = '[object Number]';
+const booleanTag = '[object Boolean]';
+const argumentsTag = '[object Arguments]';
+const symbolTag = '[object Symbol]';
+const dateTag = '[object Date]';
+const mapTag = '[object Map]';
+const setTag = '[object Set]';
+const arrayTag = '[object Array]';
+const functionTag = '[object Function]';
+const arrayBufferTag = '[object ArrayBuffer]';
+const objectTag = '[object Object]';
+const errorTag = '[object Error]';
+const dataViewTag = '[object DataView]';
+const uint8ArrayTag = '[object Uint8Array]';
+const uint8ClampedArrayTag = '[object Uint8ClampedArray]';
+const uint16ArrayTag = '[object Uint16Array]';
+const uint32ArrayTag = '[object Uint32Array]';
+const bigUint64ArrayTag = '[object BigUint64Array]';
+const int8ArrayTag = '[object Int8Array]';
+const int16ArrayTag = '[object Int16Array]';
+const int32ArrayTag = '[object Int32Array]';
+const bigInt64ArrayTag = '[object BigInt64Array]';
+const float32ArrayTag = '[object Float32Array]';
+const float64ArrayTag = '[object Float64Array]';
+
+export { argumentsTag, arrayBufferTag, arrayTag, bigInt64ArrayTag, bigUint64ArrayTag, booleanTag, dataViewTag, dateTag, errorTag, float32ArrayTag, float64ArrayTag, functionTag, int16ArrayTag, int32ArrayTag, int8ArrayTag, mapTag, numberTag, objectTag, regexpTag, setTag, stringTag, symbolTag, uint16ArrayTag, uint32ArrayTag, uint8ArrayTag, uint8ClampedArrayTag };

package/dist/compat/_internal/toPath.mjs

@@ -0,0 +1,40 @@
+function toPath(deepKey) {
+    const ESCAPE_REGEXP = /\\(\\)?/g;
+    const PROPERTY_REGEXP = RegExp('[^.[\\]]+' +
+        '|' +
+        '\\[(?:' +
+        '([^"\'][^[]*)' +
+        '|' +
+        '(["\'])((?:(?!\\2)[^\\\\]|\\\\.)*?)\\2' +
+        ')\\]' +
+        '|' +
+        '(?=(?:\\.|\\[\\])(?:\\.|\\[\\]|$))', 'g');
+    const result = [];
+    if (deepKey[0] === '.') {
+        result.push('');
+    }
+    let match;
+    let lastIndex = 0;
+    while ((match = PROPERTY_REGEXP.exec(deepKey)) !== null) {
+        let key = match[0];
+        const expr = match[1];
+        const quote = match[2];
+        const substr = match[3];
+        if (quote) {
+            key = substr.replace(ESCAPE_REGEXP, '$1');
+        }
+        else if (expr) {
+            key = expr;
+        }
+        result.push(key);
+        if (PROPERTY_REGEXP.lastIndex === lastIndex) {
+            PROPERTY_REGEXP.lastIndex++;
+        }
+        else {
+            lastIndex = PROPERTY_REGEXP.lastIndex;
+        }
+    }
+    return result;
+}
+
+export { toPath };

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

@@ -0,0 +1,26 @@
+/**
+ * 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']]
+ */
+declare function chunk<T>(arr: readonly T[], size?: number): T[][];
+
+export { chunk };

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

@@ -0,0 +1,26 @@
+/**
+ * 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']]
+ */
+declare function chunk<T>(arr: readonly T[], size?: number): T[][];
+
+export { chunk };

package/dist/compat/array/chunk.mjs

@@ -0,0 +1,11 @@
+import { chunk as chunk$1 } from '../../array/chunk.mjs';
+
+function chunk(arr, size = 1) {
+    size = Math.max(Math.floor(size), 0);
+    if (size === 0) {
+        return [];
+    }
+    return chunk$1(arr, size);
+}
+
+export { chunk };

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

@@ -0,0 +1,30 @@
+/**
+ * Concatenates multiple arrays and values into a single array.
+ *
+ * @template T The type of elements in the array.
+ * @param {...(T | T[])} values - The values and/or arrays to concatenate.
+ * @returns {T[]} A new array containing all the input values.
+ *
+ * @example
+ * // Concatenate individual values
+ * concat(1, 2, 3);
+ * // returns [1, 2, 3]
+ *
+ * @example
+ * // Concatenate arrays of values
+ * concat([1, 2], [3, 4]);
+ * // returns [1, 2, 3, 4]
+ *
+ * @example
+ * // Concatenate a mix of individual values and arrays
+ * concat(1, [2, 3], 4);
+ * // returns [1, 2, 3, 4]
+ *
+ * @example
+ * // Concatenate nested arrays
+ * concat([1, [2, 3]], 4);
+ * // returns [1, [2, 3], 4]
+ */
+declare function concat<T>(...values: Array<T | readonly T[]>): T[];
+
+export { concat };

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

@@ -0,0 +1,30 @@
+/**
+ * Concatenates multiple arrays and values into a single array.
+ *
+ * @template T The type of elements in the array.
+ * @param {...(T | T[])} values - The values and/or arrays to concatenate.
+ * @returns {T[]} A new array containing all the input values.
+ *
+ * @example
+ * // Concatenate individual values
+ * concat(1, 2, 3);
+ * // returns [1, 2, 3]
+ *
+ * @example
+ * // Concatenate arrays of values
+ * concat([1, 2], [3, 4]);
+ * // returns [1, 2, 3, 4]
+ *
+ * @example
+ * // Concatenate a mix of individual values and arrays
+ * concat(1, [2, 3], 4);
+ * // returns [1, 2, 3, 4]
+ *
+ * @example
+ * // Concatenate nested arrays
+ * concat([1, [2, 3]], 4);
+ * // returns [1, [2, 3], 4]
+ */
+declare function concat<T>(...values: Array<T | readonly T[]>): T[];
+
+export { concat };

package/dist/compat/array/concat.mjs

@@ -0,0 +1,7 @@
+import { flatten } from '../../array/flatten.mjs';
+
+function concat(...values) {
+    return flatten(values);
+}
+
+export { concat };

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

@@ -0,0 +1,3 @@
+declare function difference<T>(arr: readonly T[], ...values: Array<readonly T[]>): T[];
+
+export { difference };

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

@@ -0,0 +1,3 @@
+declare function difference<T>(arr: readonly T[], ...values: Array<readonly T[]>): T[];
+
+export { difference };

package/dist/compat/array/difference.mjs

@@ -0,0 +1,10 @@
+import { difference as difference$1 } from '../../array/difference.mjs';
+import { flatten } from '../../array/flatten.mjs';
+
+function difference(arr, ...values) {
+    const arr1 = arr;
+    const arr2 = flatten(values);
+    return difference$1(arr1, arr2);
+}
+
+export { difference };

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

@@ -0,0 +1,33 @@
+/**
+ * Fills elements of an array with a specified value from the start position up to, but not including, the end position.
+ *
+ * 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.
+ * @param {V} [end=arr.length] - The end position. Defaults to the array's length.
+ * @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[];
+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

@@ -0,0 +1,33 @@
+/**
+ * Fills elements of an array with a specified value from the start position up to, but not including, the end position.
+ *
+ * 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.
+ * @param {V} [end=arr.length] - The end position. Defaults to the array's length.
+ * @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[];
+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.mjs

@@ -0,0 +1,15 @@
+import { fill as fill$1 } from '../../array/fill.mjs';
+
+function fill(array, value, start = 0, end = array.length) {
+    start = Math.floor(start);
+    end = Math.floor(end);
+    if (!start) {
+        start = 0;
+    }
+    if (!end) {
+        end = 0;
+    }
+    return fill$1(array, value, start, end);
+}
+
+export { fill };

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

@@ -0,0 +1,19 @@
+/**
+ * Flattens an array up to the specified depth.
+ *
+ * @template T - The type of elements within the array.
+ * @template D - The depth to which the array should be flattened.
+ * @param {T[] | object} value - The object to flatten.
+ * @param {D} depth - The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.
+ * @returns {Array<FlatArray<T[], D>> | []} A new array that has been flattened.
+ *
+ * @example
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);
+ * // Returns: [1, 2, 3, 4, [5, 6]]
+ *
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flatten<T, D extends number = 1>(value: T[] | object, depth?: D): Array<FlatArray<T[], D>> | [];
+
+export { flatten };

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

@@ -0,0 +1,19 @@
+/**
+ * Flattens an array up to the specified depth.
+ *
+ * @template T - The type of elements within the array.
+ * @template D - The depth to which the array should be flattened.
+ * @param {T[] | object} value - The object to flatten.
+ * @param {D} depth - The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.
+ * @returns {Array<FlatArray<T[], D>> | []} A new array that has been flattened.
+ *
+ * @example
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);
+ * // Returns: [1, 2, 3, 4, [5, 6]]
+ *
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flatten<T, D extends number = 1>(value: T[] | object, depth?: D): Array<FlatArray<T[], D>> | [];
+
+export { flatten };

package/dist/compat/array/flatten.mjs

@@ -0,0 +1,29 @@
+function flatten(value, depth = 1) {
+    const result = [];
+    const flooredDepth = Math.floor(depth);
+    if (!Array.isArray(value)) {
+        return result;
+    }
+    const recursive = (arr, currentDepth) => {
+        for (const item of arr) {
+            if (currentDepth < flooredDepth &&
+                (Array.isArray(item) ||
+                    Boolean(item?.[Symbol.isConcatSpreadable]) ||
+                    (item !== null && typeof item === 'object' && Object.prototype.toString.call(item) === '[object Arguments]'))) {
+                if (Array.isArray(item)) {
+                    recursive(item, currentDepth + 1);
+                }
+                else {
+                    recursive(Array.from(item), currentDepth + 1);
+                }
+            }
+            else {
+                result.push(item);
+            }
+        }
+    };
+    recursive(value, 0);
+    return result;
+}
+
+export { flatten };

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

@@ -0,0 +1,25 @@
+/**
+ * Utility type for recursively unpacking nested array types to extract the type of the innermost element
+ *
+ * @example
+ * ExtractNestedArrayType<(number | (number | number[])[])[]>
+ * // number
+ *
+ * ExtractNestedArrayType<(boolean | (string | number[])[])[]>
+ * // string | number | boolean
+ */
+type ExtractNestedArrayType<T> = T extends ReadonlyArray<infer U> ? ExtractNestedArrayType<U> : T;
+/**
+ * Flattens all depths of a nested array.
+ *
+ * @template T - The type of elements within the array.
+ * @param {T[] | object} value - The value to flatten.
+ * @returns {Array<ExtractNestedArrayType<T>> | []} A new array that has been flattened.
+ *
+ * @example
+ * const value = flattenDeep([1, [2, [3]], [4, [5, 6]]]);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flattenDeep<T>(value: readonly T[] | object): Array<ExtractNestedArrayType<T>> | [];
+
+export { flattenDeep };

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

@@ -0,0 +1,25 @@
+/**
+ * Utility type for recursively unpacking nested array types to extract the type of the innermost element
+ *
+ * @example
+ * ExtractNestedArrayType<(number | (number | number[])[])[]>
+ * // number
+ *
+ * ExtractNestedArrayType<(boolean | (string | number[])[])[]>
+ * // string | number | boolean
+ */
+type ExtractNestedArrayType<T> = T extends ReadonlyArray<infer U> ? ExtractNestedArrayType<U> : T;
+/**
+ * Flattens all depths of a nested array.
+ *
+ * @template T - The type of elements within the array.
+ * @param {T[] | object} value - The value to flatten.
+ * @returns {Array<ExtractNestedArrayType<T>> | []} A new array that has been flattened.
+ *
+ * @example
+ * const value = flattenDeep([1, [2, [3]], [4, [5, 6]]]);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flattenDeep<T>(value: readonly T[] | object): Array<ExtractNestedArrayType<T>> | [];
+
+export { flattenDeep };

package/dist/compat/array/flattenDeep.mjs

@@ -0,0 +1,7 @@
+import { flatten } from './flatten.mjs';
+
+function flattenDeep(value) {
+    return flatten(value, Infinity);
+}
+
+export { flattenDeep };

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

@@ -0,0 +1,19 @@
+/**
+ * Flattens an array up to the specified depth.
+ *
+ * @template T - The type of elements within the array.
+ * @template D - The depth to which the array should be flattened.
+ * @param {T[] | object} value - The value to flatten.
+ * @param {D} depth - The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.
+ * @returns {Array<FlatArray<T[], D>> | []} A new array that has been flattened.
+ *
+ * @example
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);
+ * // Returns: [1, 2, 3, 4, [5, 6]]
+ *
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flattenDepth<T, D extends number = 1>(value: T[] | object, depth?: D): Array<FlatArray<T[], D>> | [];
+
+export { flattenDepth };

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

@@ -0,0 +1,19 @@
+/**
+ * Flattens an array up to the specified depth.
+ *
+ * @template T - The type of elements within the array.
+ * @template D - The depth to which the array should be flattened.
+ * @param {T[] | object} value - The value to flatten.
+ * @param {D} depth - The depth level specifying how deep a nested array structure should be flattened. Defaults to 1.
+ * @returns {Array<FlatArray<T[], D>> | []} A new array that has been flattened.
+ *
+ * @example
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 1);
+ * // Returns: [1, 2, 3, 4, [5, 6]]
+ *
+ * const arr = flatten([1, [2, 3], [4, [5, 6]]], 2);
+ * // Returns: [1, 2, 3, 4, 5, 6]
+ */
+declare function flattenDepth<T, D extends number = 1>(value: T[] | object, depth?: D): Array<FlatArray<T[], D>> | [];
+
+export { flattenDepth };

package/dist/compat/array/flattenDepth.mjs

@@ -0,0 +1,7 @@
+import { flatten } from './flatten.mjs';
+
+function flattenDepth(value, depth = 1) {
+    return flatten(value, depth);
+}
+
+export { flattenDepth };

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

@@ -0,0 +1,39 @@
+/**
+ * Returns the length of an array, string, or object.
+ *
+ * This function takes an array, string, or object and returns its length.
+ * For arrays and strings, it returns the number of elements or characters, respectively.
+ * For objects, it returns the number of enumerable properties.
+ *
+ * @template T - The type of the input value.
+ * @param {T[] | object | string | Map<unknown, T> | Set<T> | null | undefined } target - The value whose size is to be determined. It can be an array, string, or object.
+ * @returns {number} The size of the input value.
+ *
+ * @example
+ * const arr = [1, 2, 3];
+ * const arrSize = size(arr);
+ * // arrSize will be 3
+ *
+ * const str = 'hello';
+ * const strSize = size(str);
+ * // strSize will be 5
+ *
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const objSize = size(obj);
+ * // objSize will be 3
+ *
+ * const emptyArr = [];
+ * const emptyArrSize = size(emptyArr);
+ * // emptyArrSize will be 0
+ *
+ * const emptyStr = '';
+ * const emptyStrSize = size(emptyStr);
+ * // emptyStrSize will be 0
+ *
+ * const emptyObj = {};
+ * const emptyObjSize = size(emptyObj);
+ * // emptyObjSize will be 0
+ */
+declare function size<T>(target: T[] | object | string | Map<unknown, T> | Set<T> | null | undefined): number;
+
+export { size };