es-toolkit 1.13.1 → 1.14.0-dev.397

package/dist/compat/object/mapValues.d.mts

@@ -0,0 +1,40 @@
+/**
+ * Creates a new object with the same keys as the given object, but with values generated
+ * by running each own enumerable property of the object through the iteratee function.
+ *
+ * @template T - The type of the object.
+ * @template K - The type of the keys in the object.
+ * @template V - The type of the new values generated by the iteratee function.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {(value: T[K], key: K, object: T) => V} getNewValue - The function invoked per own enumerable property.
+ * @returns {Record<K, V>} - Returns the new mapped object.
+ *
+ * @example
+ * // Example usage:
+ * const obj = { a: 1, b: 2 };
+ * const result = mapValues(obj, (value) => value * 2);
+ * console.log(result); // { a: 2, b: 4 }
+ */
+declare function mapValues<T extends object, K extends keyof T, V>(object: T, getNewValue?: PropertyKey | readonly PropertyKey[] | null | undefined): Record<K, V>;
+/**
+ * Creates a new object with the same keys as the given object, but with values generated
+ * by running each own enumerable property of the object through the iteratee function.
+ *
+ * @template T - The type of the object.
+ * @template K - The type of the keys in the object.
+ * @template V - The type of the new values generated by the iteratee function.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {(value: T[K], key: K, object: T) => V} getNewValue - The function invoked per own enumerable property.
+ * @returns {Record<K, V>} - Returns the new mapped object.
+ *
+ * @example
+ * // Example usage:
+ * const obj = { a: 1, b: 2 };
+ * const result = mapValues(obj, (value) => value * 2);
+ * console.log(result); // { a: 2, b: 4 }
+ */
+declare function mapValues<T extends object, K extends keyof T, V>(object: T, getNewValue: (value: T[K], key: K, object: T) => V): Record<K, V>;
+
+export { mapValues };

package/dist/compat/object/mapValues.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Creates a new object with the same keys as the given object, but with values generated
+ * by running each own enumerable property of the object through the iteratee function.
+ *
+ * @template T - The type of the object.
+ * @template K - The type of the keys in the object.
+ * @template V - The type of the new values generated by the iteratee function.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {(value: T[K], key: K, object: T) => V} getNewValue - The function invoked per own enumerable property.
+ * @returns {Record<K, V>} - Returns the new mapped object.
+ *
+ * @example
+ * // Example usage:
+ * const obj = { a: 1, b: 2 };
+ * const result = mapValues(obj, (value) => value * 2);
+ * console.log(result); // { a: 2, b: 4 }
+ */
+declare function mapValues<T extends object, K extends keyof T, V>(object: T, getNewValue?: PropertyKey | readonly PropertyKey[] | null | undefined): Record<K, V>;
+/**
+ * Creates a new object with the same keys as the given object, but with values generated
+ * by running each own enumerable property of the object through the iteratee function.
+ *
+ * @template T - The type of the object.
+ * @template K - The type of the keys in the object.
+ * @template V - The type of the new values generated by the iteratee function.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {(value: T[K], key: K, object: T) => V} getNewValue - The function invoked per own enumerable property.
+ * @returns {Record<K, V>} - Returns the new mapped object.
+ *
+ * @example
+ * // Example usage:
+ * const obj = { a: 1, b: 2 };
+ * const result = mapValues(obj, (value) => value * 2);
+ * console.log(result); // { a: 2, b: 4 }
+ */
+declare function mapValues<T extends object, K extends keyof T, V>(object: T, getNewValue: (value: T[K], key: K, object: T) => V): Record<K, V>;
+
+export { mapValues };

package/dist/compat/object/mapValues.mjs

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

package/dist/compat/object/property.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Creates a function that returns the value at a given path of an object.
+ *
+ * @param {PropertyKey | readonly PropertyKey[]} path - The path of the property to get.
+ * @returns {(object: unknown) => any} - Returns a new function that takes an object and returns the value at the specified path.
+ *
+ * @example
+ * const getObjectValue = property('a.b.c');
+ * const result = getObjectValue({ a: { b: { c: 3 } } });
+ * console.log(result); // => 3
+ *
+ * @example
+ * const getObjectValue = property(['a', 'b', 'c']);
+ * const result = getObjectValue({ a: { b: { c: 3 } } });
+ * console.log(result); // => 3
+ */
+declare function property(path: PropertyKey | readonly PropertyKey[]): (object: unknown) => any;
+
+export { property };

package/dist/compat/object/property.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Creates a function that returns the value at a given path of an object.
+ *
+ * @param {PropertyKey | readonly PropertyKey[]} path - The path of the property to get.
+ * @returns {(object: unknown) => any} - Returns a new function that takes an object and returns the value at the specified path.
+ *
+ * @example
+ * const getObjectValue = property('a.b.c');
+ * const result = getObjectValue({ a: { b: { c: 3 } } });
+ * console.log(result); // => 3
+ *
+ * @example
+ * const getObjectValue = property(['a', 'b', 'c']);
+ * const result = getObjectValue({ a: { b: { c: 3 } } });
+ * console.log(result); // => 3
+ */
+declare function property(path: PropertyKey | readonly PropertyKey[]): (object: unknown) => any;
+
+export { property };

package/dist/compat/object/property.mjs

@@ -0,0 +1,9 @@
+import { get } from './get.mjs';
+
+function property(path) {
+    return function (object) {
+        return get(object, path);
+    };
+}
+
+export { property };

package/dist/compat/object/set.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Sets the value at the specified path of the given object. If any part of the path does not exist, it will be created.
+ *
+ * @template T - The type of the object.
+ * @param {Settable} obj - The object to modify.
+ * @param {Path} path - The path of the property to set.
+ * @param {any} value - The value to set.
+ * @returns {T} - The modified object.
+ *
+ * @example
+ * // Set a value in a nested object
+ * const obj = { a: { b: { c: 3 } } };
+ * set(obj, 'a.b.c', 4);
+ * console.log(obj.a.b.c); // 4
+ *
+ * @example
+ * // Set a value in an array
+ * const arr = [1, 2, 3];
+ * set(arr, 1, 4);
+ * console.log(arr[1]); // 4
+ *
+ * @example
+ * // Create non-existent path and set value
+ * const obj = {};
+ * set(obj, 'a.b.c', 4);
+ * console.log(obj); // { a: { b: { c: 4 } } }
+ */
+declare function set<T>(obj: object, path: PropertyKey | readonly PropertyKey[], value: unknown): T;
+
+export { set };

package/dist/compat/object/set.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Sets the value at the specified path of the given object. If any part of the path does not exist, it will be created.
+ *
+ * @template T - The type of the object.
+ * @param {Settable} obj - The object to modify.
+ * @param {Path} path - The path of the property to set.
+ * @param {any} value - The value to set.
+ * @returns {T} - The modified object.
+ *
+ * @example
+ * // Set a value in a nested object
+ * const obj = { a: { b: { c: 3 } } };
+ * set(obj, 'a.b.c', 4);
+ * console.log(obj.a.b.c); // 4
+ *
+ * @example
+ * // Set a value in an array
+ * const arr = [1, 2, 3];
+ * set(arr, 1, 4);
+ * console.log(arr[1]); // 4
+ *
+ * @example
+ * // Create non-existent path and set value
+ * const obj = {};
+ * set(obj, 'a.b.c', 4);
+ * console.log(obj); // { a: { b: { c: 4 } } }
+ */
+declare function set<T>(obj: object, path: PropertyKey | readonly PropertyKey[], value: unknown): T;
+
+export { set };

package/dist/compat/object/set.mjs

@@ -0,0 +1,24 @@
+import { isIndex } from '../_internal/isIndex.mjs';
+import { toPath } from '../_internal/toPath.mjs';
+
+function set(obj, path, value) {
+    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];
+        const nextKey = resolvedPath[i + 1];
+        if (current[key] == null) {
+            current[key] = isIndex(nextKey) ? [] : {};
+        }
+        current = current[key];
+    }
+    const lastKey = resolvedPath[resolvedPath.length - 1];
+    current[lastKey] = value;
+    return obj;
+}
+
+export { set };

package/dist/compat/predicate/isArguments.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Checks if the given value is an arguments object.
+ *
+ * This function tests whether the provided value is an arguments object or not.
+ * It returns `true` if the value is an arguments object, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to an arguments object.
+ *
+ * @param {unknown} value - The value to test if it is an arguments object.
+ * @returns {value is IArguments} `true` if the value is an arguments, `false` otherwise.
+ *
+ * @example
+ * const args = (function() { return arguments; })();
+ * const strictArgs = (function() { 'use strict'; return arguments; })();
+ * const value = [1, 2, 3];
+ *
+ * console.log(isArguments(args)); // true
+ * console.log(isArguments(strictArgs)); // true
+ * console.log(isArguments(value)); // false
+ */
+declare function isArguments(value?: unknown): value is IArguments;
+
+export { isArguments };

package/dist/compat/predicate/isArguments.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Checks if the given value is an arguments object.
+ *
+ * This function tests whether the provided value is an arguments object or not.
+ * It returns `true` if the value is an arguments object, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to an arguments object.
+ *
+ * @param {unknown} value - The value to test if it is an arguments object.
+ * @returns {value is IArguments} `true` if the value is an arguments, `false` otherwise.
+ *
+ * @example
+ * const args = (function() { return arguments; })();
+ * const strictArgs = (function() { 'use strict'; return arguments; })();
+ * const value = [1, 2, 3];
+ *
+ * console.log(isArguments(args)); // true
+ * console.log(isArguments(strictArgs)); // true
+ * console.log(isArguments(value)); // false
+ */
+declare function isArguments(value?: unknown): value is IArguments;
+
+export { isArguments };

package/dist/compat/predicate/isArguments.mjs

@@ -0,0 +1,7 @@
+import { getTag } from '../_internal/getTag.mjs';
+
+function isArguments(value) {
+    return value !== null && typeof value === 'object' && getTag(value) === '[object Arguments]';
+}
+
+export { isArguments };

package/dist/compat/predicate/isArray.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Checks if the given value is an array.
+ *
+ * This function tests whether the provided value is an array or not.
+ * It returns `true` if the value is an array, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to an array.
+ *
+ * @param {unknown} value - The value to test if it is an array.
+ * @returns {value is any[]} `true` if the value is an array, `false` otherwise.
+ *
+ * @example
+ * const value1 = [1, 2, 3];
+ * const value2 = 'abc';
+ * const value3 = () => {};
+ *
+ * console.log(isArray(value1)); // true
+ * console.log(isArray(value2)); // false
+ * console.log(isArray(value3)); // false
+ */
+declare function isArray(value?: unknown): value is any[];
+
+export { isArray };

package/dist/compat/predicate/isArray.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Checks if the given value is an array.
+ *
+ * This function tests whether the provided value is an array or not.
+ * It returns `true` if the value is an array, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to an array.
+ *
+ * @param {unknown} value - The value to test if it is an array.
+ * @returns {value is any[]} `true` if the value is an array, `false` otherwise.
+ *
+ * @example
+ * const value1 = [1, 2, 3];
+ * const value2 = 'abc';
+ * const value3 = () => {};
+ *
+ * console.log(isArray(value1)); // true
+ * console.log(isArray(value2)); // false
+ * console.log(isArray(value3)); // false
+ */
+declare function isArray(value?: unknown): value is any[];
+
+export { isArray };

package/dist/compat/predicate/isArray.mjs

@@ -0,0 +1,5 @@
+function isArray(value) {
+    return Array.isArray(value);
+}
+
+export { isArray };

package/dist/compat/predicate/isArrayLike.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Checks if `value` is array-like.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is ArrayLike<unknown>} Returns `true` if `value` is array-like, else `false`.
+ *
+ * @example
+ * isArrayLike([1, 2, 3]); // true
+ * isArrayLike('abc'); // true
+ * isArrayLike({ 0: 'a', length: 1 }); // true
+ * isArrayLike({}); // false
+ * isArrayLike(null); // false
+ * isArrayLike(undefined); // false
+ */
+declare function isArrayLike(value: unknown): value is ArrayLike<unknown>;
+
+export { isArrayLike };

package/dist/compat/predicate/isArrayLike.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Checks if `value` is array-like.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is ArrayLike<unknown>} Returns `true` if `value` is array-like, else `false`.
+ *
+ * @example
+ * isArrayLike([1, 2, 3]); // true
+ * isArrayLike('abc'); // true
+ * isArrayLike({ 0: 'a', length: 1 }); // true
+ * isArrayLike({}); // false
+ * isArrayLike(null); // false
+ * isArrayLike(undefined); // false
+ */
+declare function isArrayLike(value: unknown): value is ArrayLike<unknown>;
+
+export { isArrayLike };

package/dist/compat/predicate/isArrayLike.mjs

@@ -0,0 +1,8 @@
+import { isLength } from '../../predicate/isLength.mjs';
+
+function isArrayLike(value) {
+    return value != null && typeof value !== "function" &&
+        isLength(value.length);
+}
+
+export { isArrayLike };

package/dist/compat/predicate/isBoolean.d.mts

@@ -0,0 +1,25 @@
+/**
+ * Checks if the given value is boolean.
+ *
+ * This function tests whether the provided value is strictly `boolean`.
+ * It returns `true` if the value is `boolean`, and `false` otherwise.
+ *
+ *  This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `boolean`.
+ *
+ * @param {unknown} x - The Value to test if it is boolean.
+ * @returns {x is boolean} True if the value is booelan, false otherwise.
+ *
+ * @example
+ *
+ * const value1 = true;
+ * const value2 = 0;
+ * const value3 = 'abc';
+ *
+ * console.log(isBoolean(value1)); // true
+ * console.log(isBoolean(value2)); // false
+ * console.log(isBoolean(value3)); // false
+ *
+ */
+declare function isBoolean(x: unknown): x is boolean;
+
+export { isBoolean };

package/dist/compat/predicate/isBoolean.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Checks if the given value is boolean.
+ *
+ * This function tests whether the provided value is strictly `boolean`.
+ * It returns `true` if the value is `boolean`, and `false` otherwise.
+ *
+ *  This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `boolean`.
+ *
+ * @param {unknown} x - The Value to test if it is boolean.
+ * @returns {x is boolean} True if the value is booelan, false otherwise.
+ *
+ * @example
+ *
+ * const value1 = true;
+ * const value2 = 0;
+ * const value3 = 'abc';
+ *
+ * console.log(isBoolean(value1)); // true
+ * console.log(isBoolean(value2)); // false
+ * console.log(isBoolean(value3)); // false
+ *
+ */
+declare function isBoolean(x: unknown): x is boolean;
+
+export { isBoolean };

package/dist/compat/predicate/isBoolean.mjs

@@ -0,0 +1,13 @@
+import { getTag } from '../_internal/getTag.mjs';
+
+function isBoolean(x) {
+    if (x === true || x === false) {
+        return true;
+    }
+    if (typeof x === 'object' && x != null && getTag(x) === '[object Boolean]') {
+        return true;
+    }
+    return false;
+}
+
+export { isBoolean };

package/dist/compat/predicate/isMatch.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Checks if the target matches the source by comparing their structures and values.
+ * This function supports deep comparison for objects, arrays, maps, and sets.
+ *
+ * @param {unknown} target - The target value to match against.
+ * @param {unknown} source - The source value to match with.
+ * @returns {boolean} - Returns `true` if the target matches the source, otherwise `false`.
+ *
+ * @example
+ * // Basic usage
+ * isMatch({ a: 1, b: 2 }, { a: 1 }); // true
+ *
+ * @example
+ * // Matching arrays
+ * isMatch([1, 2, 3], [1, 2, 3]); // true
+ *
+ * @example
+ * // Matching maps
+ * const targetMap = new Map([['key1', 'value1'], ['key2', 'value2']]);
+ * const sourceMap = new Map([['key1', 'value1']]);
+ * isMatch(targetMap, sourceMap); // true
+ *
+ * @example
+ * // Matching sets
+ * const targetSet = new Set([1, 2, 3]);
+ * const sourceSet = new Set([1, 2]);
+ * isMatch(targetSet, sourceSet); // true
+ */
+declare function isMatch(target: unknown, source: unknown): boolean;
+
+export { isMatch };

package/dist/compat/predicate/isMatch.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Checks if the target matches the source by comparing their structures and values.
+ * This function supports deep comparison for objects, arrays, maps, and sets.
+ *
+ * @param {unknown} target - The target value to match against.
+ * @param {unknown} source - The source value to match with.
+ * @returns {boolean} - Returns `true` if the target matches the source, otherwise `false`.
+ *
+ * @example
+ * // Basic usage
+ * isMatch({ a: 1, b: 2 }, { a: 1 }); // true
+ *
+ * @example
+ * // Matching arrays
+ * isMatch([1, 2, 3], [1, 2, 3]); // true
+ *
+ * @example
+ * // Matching maps
+ * const targetMap = new Map([['key1', 'value1'], ['key2', 'value2']]);
+ * const sourceMap = new Map([['key1', 'value1']]);
+ * isMatch(targetMap, sourceMap); // true
+ *
+ * @example
+ * // Matching sets
+ * const targetSet = new Set([1, 2, 3]);
+ * const sourceSet = new Set([1, 2]);
+ * isMatch(targetSet, sourceSet); // true
+ */
+declare function isMatch(target: unknown, source: unknown): boolean;
+
+export { isMatch };

package/dist/compat/predicate/isMatch.mjs

@@ -0,0 +1,57 @@
+import { isPrimitive } from '../../predicate/isPrimitive.mjs';
+import { isArrayMatch } from '../_internal/isArrayMatch.mjs';
+import { isMapMatch } from '../_internal/isMapMatch.mjs';
+import { isSetMatch } from '../_internal/isSetMatch.mjs';
+
+function isMatch(target, source) {
+    if (source === target) {
+        return true;
+    }
+    switch (typeof source) {
+        case 'object': {
+            if (source == null) {
+                return true;
+            }
+            const keys = Object.keys(source);
+            if (target == null) {
+                if (keys.length === 0) {
+                    return true;
+                }
+                return false;
+            }
+            if (Array.isArray(source)) {
+                return isArrayMatch(target, source);
+            }
+            if (source instanceof Map) {
+                return isMapMatch(target, source);
+            }
+            if (source instanceof Set) {
+                return isSetMatch(target, source);
+            }
+            for (let i = 0; i < keys.length; i++) {
+                const key = keys[i];
+                if (!isPrimitive(target) && !(key in target)) {
+                    return false;
+                }
+                if (source[key] === undefined && target[key] !== undefined) {
+                    return false;
+                }
+                if (!isMatch(target[key], source[key])) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        case 'function': {
+            if (Object.keys(source).length > 0) {
+                return isMatch(target, { ...source });
+            }
+            return false;
+        }
+        default: {
+            return !source;
+        }
+    }
+}
+
+export { isMatch };

package/dist/compat/predicate/isObjectLike.d.mts

@@ -0,0 +1,26 @@
+/**
+ * Checks if the given value is object-like.
+ *
+ * A value is object-like if its type is object and it is not null.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to an object-like value.
+ *
+ * @template T - The type of value.
+ * @param {T} value - The value to test if it is an object-like.
+ * @returns {value is Extract<T, object>} `true` if the value is an object-like, `false` otherwise.
+ *
+ * @example
+ * const value1 = { a: 1 };
+ * const value2 = [1, 2, 3];
+ * const value3 = 'abc';
+ * const value4 = () => {};
+ * const value5 = null;
+ *
+ * console.log(isObjectLike(value1)); // true
+ * console.log(isObjectLike(value2)); // true
+ * console.log(isObjectLike(value3)); // false
+ * console.log(isObjectLike(value4)); // false
+ */
+declare function isObjectLike(value: unknown): value is object;
+
+export { isObjectLike };

package/dist/compat/predicate/isObjectLike.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Checks if the given value is object-like.
+ *
+ * A value is object-like if its type is object and it is not null.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to an object-like value.
+ *
+ * @template T - The type of value.
+ * @param {T} value - The value to test if it is an object-like.
+ * @returns {value is Extract<T, object>} `true` if the value is an object-like, `false` otherwise.
+ *
+ * @example
+ * const value1 = { a: 1 };
+ * const value2 = [1, 2, 3];
+ * const value3 = 'abc';
+ * const value4 = () => {};
+ * const value5 = null;
+ *
+ * console.log(isObjectLike(value1)); // true
+ * console.log(isObjectLike(value2)); // true
+ * console.log(isObjectLike(value3)); // false
+ * console.log(isObjectLike(value4)); // false
+ */
+declare function isObjectLike(value: unknown): value is object;
+
+export { isObjectLike };

package/dist/compat/predicate/isObjectLike.mjs

@@ -0,0 +1,5 @@
+function isObjectLike(value) {
+    return typeof value === 'object' && value !== null;
+}
+
+export { isObjectLike };