es-toolkit 1.18.0 → 1.19.0

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

@@ -0,0 +1,34 @@
+/**
+ * Creates a new object with specified keys omitted.
+ *
+ * This function takes an object and an array of keys, and returns a new object that
+ * excludes the properties corresponding to the specified keys.
+ *
+ * @template T - The type of object.
+ * @template K - The type of keys in object.
+ * @param {T} obj - The object to omit keys from.
+ * @param {K[]} keys - An array of keys to be omitted from the object.
+ * @returns {Omit<T, K>} A new object with the specified keys omitted.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = omit(obj, ['b', 'c']);
+ * // result will be { a: 1 }
+ */
+declare function omit<T extends Record<string, any>, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K>;
+/**
+ * Creates a new object with specified keys omitted.
+ *
+ * This function takes an object and a variable number of keys, and returns a new object that
+ * excludes the properties corresponding to the specified keys.
+ *
+ * Deep keys can be specified for keys.
+ *
+ * @template T - The type of object.
+ * @param {T} obj - The object to omit keys from.
+ * @param {...(PropertyKey | PropertyKey[] | PropertyKey[][]} keys - A variable number of keys to be omitted from the object.
+ * @returns {Partial<T>} A new object with the specified keys omitted.
+ */
+declare function omit<T extends {}>(obj: T | null | undefined, ...keys: Array<PropertyKey | readonly PropertyKey[] | ReadonlyArray<readonly PropertyKey[]>>): Partial<T>;
+
+export { omit };

package/dist/compat/object/omit.mjs

@@ -0,0 +1,33 @@
+import { cloneDeep } from '../../object/cloneDeep.mjs';
+import { unset } from './unset.mjs';
+
+function omit(obj, ...keysArr) {
+    if (obj == null) {
+        return {};
+    }
+    const result = cloneDeep(obj);
+    for (let i = 0; i < keysArr.length; i++) {
+        let keys = keysArr[i];
+        switch (typeof keys) {
+            case 'object': {
+                if (!Array.isArray(keys)) {
+                    keys = Array.from(keys);
+                }
+                for (let j = 0; j < keys.length; j++) {
+                    const key = keys[j];
+                    unset(result, key);
+                }
+                break;
+            }
+            case 'string':
+            case 'symbol':
+            case 'number': {
+                unset(result, keys);
+                break;
+            }
+        }
+    }
+    return result;
+}
+
+export { omit };

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

@@ -0,0 +1,47 @@
+/**
+ * Creates a new object composed of the picked object properties.
+ *
+ * This function takes an object and an array of keys, and returns a new object that
+ * includes only the properties corresponding to the specified keys.
+ *
+ * @template T - The type of object.
+ * @template K - The type of keys in object.
+ * @param {T} obj - The object to pick keys from.
+ * @param {K[]} keys - An array of keys to be picked from the object.
+ * @returns {Pick<T, K>} A new object with the specified keys picked.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, ['a', 'c']);
+ * // result will be { a: 1, c: 3 }
+ */
+declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * Creates a new object composed of the picked object properties.
+ *
+ * This function takes an object and an array of keys, and returns a new object that
+ * includes only the properties corresponding to the specified keys.
+ *
+ * @template T - The type of object.
+ * @param {T | null | undefined} obj - The object to pick keys from.
+ * @param {...any} keys
+ * @param {PropertyKey | PropertyKey[] | ProperyKey[][]}} keys - An array of keys to be picked from the object. received keysgoes through a flattening process before being used.
+ * @returns {Partial<T, K>} A new object with the specified keys picked.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, ['a', 'c']);
+ * // result will be { a: 1, c: 3 }
+ *
+ * // each path can be passed individually as an argument
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, 'a', 'c');
+ *
+ * // pick a key over a path
+ * const obj = { 'a.b': 1, a: { b: 2 } };
+ * const result = pick(obj, 'a.b');
+ * // result will be { 'a.b': 1 }
+ */
+declare function pick<T extends {}>(obj: T | null | undefined, ...keys: Array<PropertyKey | readonly PropertyKey[] | ReadonlyArray<readonly PropertyKey[]>>): Partial<T>;
+
+export { pick };

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

@@ -0,0 +1,47 @@
+/**
+ * Creates a new object composed of the picked object properties.
+ *
+ * This function takes an object and an array of keys, and returns a new object that
+ * includes only the properties corresponding to the specified keys.
+ *
+ * @template T - The type of object.
+ * @template K - The type of keys in object.
+ * @param {T} obj - The object to pick keys from.
+ * @param {K[]} keys - An array of keys to be picked from the object.
+ * @returns {Pick<T, K>} A new object with the specified keys picked.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, ['a', 'c']);
+ * // result will be { a: 1, c: 3 }
+ */
+declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * Creates a new object composed of the picked object properties.
+ *
+ * This function takes an object and an array of keys, and returns a new object that
+ * includes only the properties corresponding to the specified keys.
+ *
+ * @template T - The type of object.
+ * @param {T | null | undefined} obj - The object to pick keys from.
+ * @param {...any} keys
+ * @param {PropertyKey | PropertyKey[] | ProperyKey[][]}} keys - An array of keys to be picked from the object. received keysgoes through a flattening process before being used.
+ * @returns {Partial<T, K>} A new object with the specified keys picked.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, ['a', 'c']);
+ * // result will be { a: 1, c: 3 }
+ *
+ * // each path can be passed individually as an argument
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pick(obj, 'a', 'c');
+ *
+ * // pick a key over a path
+ * const obj = { 'a.b': 1, a: { b: 2 } };
+ * const result = pick(obj, 'a.b');
+ * // result will be { 'a.b': 1 }
+ */
+declare function pick<T extends {}>(obj: T | null | undefined, ...keys: Array<PropertyKey | readonly PropertyKey[] | ReadonlyArray<readonly PropertyKey[]>>): Partial<T>;
+
+export { pick };

package/dist/compat/object/pick.mjs

@@ -0,0 +1,38 @@
+import { isNil } from '../predicate/isNil.mjs';
+import { get } from './get.mjs';
+import { set } from './set.mjs';
+
+function pick(obj, ...keysArr) {
+    if (isNil(obj)) {
+        return {};
+    }
+    const result = {};
+    for (let keys of keysArr) {
+        switch (typeof keys) {
+            case 'object': {
+                if (!Array.isArray(keys)) {
+                    keys = Array.from(keys);
+                }
+                break;
+            }
+            case 'string':
+            case 'symbol':
+            case 'number': {
+                keys = [keys];
+                break;
+            }
+        }
+        for (const key of keys) {
+            const value = get(obj, key);
+            if (typeof key === 'string' && Object.prototype.hasOwnProperty.call(obj, key)) {
+                result[key] = value;
+            }
+            else {
+                set(result, key, value);
+            }
+        }
+    }
+    return result;
+}
+
+export { pick };

package/dist/compat/object/set.mjs

@@ -1,5 +1,5 @@
 import { isIndex } from '../_internal/isIndex.mjs';
-import { toPath } from '../_internal/toPath.mjs';
+import { toPath } from '../util/toPath.mjs';
 
 function set(obj, path, value) {
     const resolvedPath = Array.isArray(path) ? path : typeof path === 'string' ? toPath(path) : [path];

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

@@ -0,0 +1,20 @@
+/**
+ * Removes the property at the given path of the object.
+ *
+ * @param {unknown} obj - The object to modify.
+ * @param {PropertyKey | readonly PropertyKey[]} path - The path of the property to unset.
+ * @returns {boolean} - Returns true if the property is deleted, else false.
+ *
+ * @example
+ * const obj = { a: { b: { c: 42 } } };
+ * unset(obj, 'a.b.c'); // true
+ * console.log(obj); // { a: { b: {} } }
+ *
+ * @example
+ * const obj = { a: { b: { c: 42 } } };
+ * unset(obj, ['a', 'b', 'c']); // true
+ * console.log(obj); // { a: { b: {} } }
+ */
+declare function unset(obj: any, path: PropertyKey | readonly PropertyKey[]): boolean;
+
+export { unset };

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

@@ -0,0 +1,20 @@
+/**
+ * Removes the property at the given path of the object.
+ *
+ * @param {unknown} obj - The object to modify.
+ * @param {PropertyKey | readonly PropertyKey[]} path - The path of the property to unset.
+ * @returns {boolean} - Returns true if the property is deleted, else false.
+ *
+ * @example
+ * const obj = { a: { b: { c: 42 } } };
+ * unset(obj, 'a.b.c'); // true
+ * console.log(obj); // { a: { b: {} } }
+ *
+ * @example
+ * const obj = { a: { b: { c: 42 } } };
+ * unset(obj, ['a', 'b', 'c']); // true
+ * console.log(obj); // { a: { b: {} } }
+ */
+declare function unset(obj: any, path: PropertyKey | readonly PropertyKey[]): boolean;
+
+export { unset };

package/dist/compat/object/unset.mjs

@@ -0,0 +1,68 @@
+import { isDeepKey } from '../_internal/isDeepKey.mjs';
+import { toKey } from '../_internal/toKey.mjs';
+import { toPath } from '../util/toPath.mjs';
+import { get } from './get.mjs';
+
+function unset(obj, path) {
+    if (obj == null) {
+        return true;
+    }
+    switch (typeof path) {
+        case 'symbol':
+        case 'number':
+        case 'object': {
+            if (Array.isArray(path)) {
+                return unsetWithPath(obj, path);
+            }
+            if (typeof path === 'number') {
+                path = toKey(path);
+            }
+            else if (typeof path === 'object') {
+                if (Object.is(path?.valueOf(), -0)) {
+                    path = '-0';
+                }
+                else {
+                    path = String(path);
+                }
+            }
+            if (obj?.[path] === undefined) {
+                return true;
+            }
+            try {
+                delete obj[path];
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        case 'string': {
+            if (obj?.[path] === undefined && isDeepKey(path)) {
+                return unsetWithPath(obj, toPath(path));
+            }
+            try {
+                delete obj[path];
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+}
+function unsetWithPath(obj, path) {
+    const parent = get(obj, path.slice(0, -1), obj);
+    const lastKey = path[path.length - 1];
+    if (parent?.[lastKey] === undefined) {
+        return true;
+    }
+    try {
+        delete parent[lastKey];
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+export { unset };

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

@@ -0,0 +1,17 @@
+/**
+ * Checks if `value` is an integer.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `number`.
+ *
+ * @param {unknown} value - The value to check
+ * @returns {boolean} `true` if `value` is integer, otherwise `false`.
+ *
+ * @example
+ * isInteger(3); // Returns: true
+ * isInteger(Infinity); // Returns: false
+ * isInteger('3'); // Returns: false
+ * isInteger([]); // Returns: false
+ */
+declare function isInteger(value?: unknown): value is number;
+
+export { isInteger };

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

@@ -0,0 +1,17 @@
+/**
+ * Checks if `value` is an integer.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `number`.
+ *
+ * @param {unknown} value - The value to check
+ * @returns {boolean} `true` if `value` is integer, otherwise `false`.
+ *
+ * @example
+ * isInteger(3); // Returns: true
+ * isInteger(Infinity); // Returns: false
+ * isInteger('3'); // Returns: false
+ * isInteger([]); // Returns: false
+ */
+declare function isInteger(value?: unknown): value is number;
+
+export { isInteger };

package/dist/compat/predicate/isInteger.mjs

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

package/dist/compat/predicate/isMatch.mjs

@@ -1,7 +1,4 @@
 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) {
@@ -53,5 +50,48 @@ function isMatch(target, source) {
         }
     }
 }
+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;
+}
+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;
+}
+function isSetMatch(target, source) {
+    if (source.size === 0) {
+        return true;
+    }
+    if (!(target instanceof Set)) {
+        return false;
+    }
+    return isArrayMatch([...target], [...source]);
+}
 
-export { isMatch };
+export { isArrayMatch, isMapMatch, isMatch, isSetMatch };

package/dist/compat/predicate/isNil.mjs

@@ -0,0 +1,5 @@
+function isNil(x) {
+    return x == null;
+}
+
+export { isNil };

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

@@ -16,10 +16,10 @@
  * const value3 = () => {};
  * const value4 = null;
  *
- * console.log(isArray(value1)); // true
- * console.log(isArray(value2)); // true
- * console.log(isArray(value3)); // true
- * console.log(isArray(value4)); // false
+ * console.log(isObject(value1)); // true
+ * console.log(isObject(value2)); // true
+ * console.log(isObject(value3)); // true
+ * console.log(isObject(value4)); // false
  */
 declare function isObject(value: unknown): value is object;
 

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

@@ -16,10 +16,10 @@
  * const value3 = () => {};
  * const value4 = null;
  *
- * console.log(isArray(value1)); // true
- * console.log(isArray(value2)); // true
- * console.log(isArray(value3)); // true
- * console.log(isArray(value4)); // false
+ * console.log(isObject(value1)); // true
+ * console.log(isObject(value2)); // true
+ * console.log(isObject(value3)); // true
+ * console.log(isObject(value4)); // false
  */
 declare function isObject(value: unknown): value is object;
 

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if `value` is a safe integer (between -(2^53 – 1) and (2^53 – 1), inclusive).
+ *
+ * A safe integer is an integer that can be precisely represented as a `number` in JavaScript,
+ * without any other integer being rounded to it.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `number`.
+ *
+ * @param {unknown} value - The value to check
+ * @returns {boolean} `true` if `value` is an integer and between the safe values, otherwise `false`
+ *
+ * @example
+ * isSafeInteger(3); // Returns: true
+ * isSafeInteger(Number.MIN_SAFE_INTEGER - 1); // Returns: false
+ * isSafeInteger(1n); // Returns: false
+ * isSafeInteger('1'); // Returns: false
+ */
+declare function isSafeInteger(value?: unknown): value is number;
+
+export { isSafeInteger };

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if `value` is a safe integer (between -(2^53 – 1) and (2^53 – 1), inclusive).
+ *
+ * A safe integer is an integer that can be precisely represented as a `number` in JavaScript,
+ * without any other integer being rounded to it.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `number`.
+ *
+ * @param {unknown} value - The value to check
+ * @returns {boolean} `true` if `value` is an integer and between the safe values, otherwise `false`
+ *
+ * @example
+ * isSafeInteger(3); // Returns: true
+ * isSafeInteger(Number.MIN_SAFE_INTEGER - 1); // Returns: false
+ * isSafeInteger(1n); // Returns: false
+ * isSafeInteger('1'); // Returns: false
+ */
+declare function isSafeInteger(value?: unknown): value is number;
+
+export { isSafeInteger };

package/dist/compat/predicate/isSafeInteger.mjs

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

package/dist/compat/predicate/matchesProperty.mjs

@@ -5,7 +5,18 @@ import { has } from '../object/has.mjs';
 import { isMatch } from './isMatch.mjs';
 
 function matchesProperty(property, source) {
-    property = Array.isArray(property) ? property : toKey(property);
+    switch (typeof property) {
+        case 'object': {
+            if (Object.is(property?.valueOf(), -0)) {
+                property = '-0';
+            }
+            break;
+        }
+        case 'number': {
+            property = toKey(property);
+            break;
+        }
+    }
     source = cloneDeep(source);
     return function (target) {
         const result = get(target, property);

package/dist/compat/string/kebabCase.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to kebab case.
+ *
+ * Kebab case is the naming convention in which each word is written in lowercase and separated by a dash (-) character.
+ *
+ * @param {string} str - The string that is to be changed to kebab case.
+ * @returns {string} - The converted string to kebab case.
+ *
+ * @example
+ * const convertedStr1 = kebabCase('camelCase') // returns 'camel-case'
+ * const convertedStr2 = kebabCase('some whitespace') // returns 'some-whitespace'
+ * const convertedStr3 = kebabCase('hyphen-text') // returns 'hyphen-text'
+ * const convertedStr4 = kebabCase('HTTPRequest') // returns 'http-request'
+ */
+declare function kebabCase(str: string | object): string;
+
+export { kebabCase };

package/dist/compat/string/kebabCase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to kebab case.
+ *
+ * Kebab case is the naming convention in which each word is written in lowercase and separated by a dash (-) character.
+ *
+ * @param {string} str - The string that is to be changed to kebab case.
+ * @returns {string} - The converted string to kebab case.
+ *
+ * @example
+ * const convertedStr1 = kebabCase('camelCase') // returns 'camel-case'
+ * const convertedStr2 = kebabCase('some whitespace') // returns 'some-whitespace'
+ * const convertedStr3 = kebabCase('hyphen-text') // returns 'hyphen-text'
+ * const convertedStr4 = kebabCase('HTTPRequest') // returns 'http-request'
+ */
+declare function kebabCase(str: string | object): string;
+
+export { kebabCase };

package/dist/compat/string/kebabCase.mjs

@@ -0,0 +1,9 @@
+import { kebabCase as kebabCase$1 } from '../../string/kebabCase.mjs';
+import '../../string/deburr.mjs';
+import { normalizeForCase } from '../_internal/normalizeForCase.mjs';
+
+function kebabCase(str) {
+    return kebabCase$1(normalizeForCase(str));
+}
+
+export { kebabCase };

package/dist/compat/string/lowerCase.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to lower case.
+ *
+ * Lower case is the naming convention in which each word is written in lowercase and separated by an space ( ) character.
+ *
+ * @param {string} str - The string that is to be changed to lower case.
+ * @returns {string} - The converted string to lower case.
+ *
+ * @example
+ * const convertedStr1 = lowerCase('camelCase') // returns 'camel case'
+ * const convertedStr2 = lowerCase('some whitespace') // returns 'some whitespace'
+ * const convertedStr3 = lowerCase('hyphen-text') // returns 'hyphen text'
+ * const convertedStr4 = lowerCase('HTTPRequest') // returns 'http request'
+ */
+declare function lowerCase(str: string | object): string;
+
+export { lowerCase };

package/dist/compat/string/lowerCase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to lower case.
+ *
+ * Lower case is the naming convention in which each word is written in lowercase and separated by an space ( ) character.
+ *
+ * @param {string} str - The string that is to be changed to lower case.
+ * @returns {string} - The converted string to lower case.
+ *
+ * @example
+ * const convertedStr1 = lowerCase('camelCase') // returns 'camel case'
+ * const convertedStr2 = lowerCase('some whitespace') // returns 'some whitespace'
+ * const convertedStr3 = lowerCase('hyphen-text') // returns 'hyphen text'
+ * const convertedStr4 = lowerCase('HTTPRequest') // returns 'http request'
+ */
+declare function lowerCase(str: string | object): string;
+
+export { lowerCase };

package/dist/compat/string/lowerCase.mjs

@@ -0,0 +1,8 @@
+import { lowerCase as lowerCase$1 } from '../../string/lowerCase.mjs';
+import { normalizeForCase } from '../_internal/normalizeForCase.mjs';
+
+function lowerCase(str) {
+    return lowerCase$1(normalizeForCase(str));
+}
+
+export { lowerCase };

package/dist/compat/string/snakeCase.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to snake case.
+ *
+ * Snake case is the naming convention in which each word is written in lowercase and separated by an underscore (_) character.
+ *
+ * @param {string} str - The string that is to be changed to snake case.
+ * @returns {string} - The converted string to snake case.
+ *
+ * @example
+ * const convertedStr1 = snakeCase('camelCase') // returns 'camel_case'
+ * const convertedStr2 = snakeCase('some whitespace') // returns 'some_whitespace'
+ * const convertedStr3 = snakeCase('hyphen-text') // returns 'hyphen_text'
+ * const convertedStr4 = snakeCase('HTTPRequest') // returns 'http_request'
+ */
+declare function snakeCase(str: string | object): string;
+
+export { snakeCase };

package/dist/compat/string/snakeCase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to snake case.
+ *
+ * Snake case is the naming convention in which each word is written in lowercase and separated by an underscore (_) character.
+ *
+ * @param {string} str - The string that is to be changed to snake case.
+ * @returns {string} - The converted string to snake case.
+ *
+ * @example
+ * const convertedStr1 = snakeCase('camelCase') // returns 'camel_case'
+ * const convertedStr2 = snakeCase('some whitespace') // returns 'some_whitespace'
+ * const convertedStr3 = snakeCase('hyphen-text') // returns 'hyphen_text'
+ * const convertedStr4 = snakeCase('HTTPRequest') // returns 'http_request'
+ */
+declare function snakeCase(str: string | object): string;
+
+export { snakeCase };