es-toolkit 1.29.0 → 1.30.0-dev.963

package/dist/compat/object/keys.mjs

@@ -0,0 +1,32 @@
+import { isBuffer } from '../../predicate/isBuffer.mjs';
+import { isPrototype } from '../_internal/isPrototype.mjs';
+import { isArrayLike } from '../predicate/isArrayLike.mjs';
+import { isTypedArray } from '../predicate/isTypedArray.mjs';
+import { times } from '../util/times.mjs';
+
+function keys(object) {
+    if (isArrayLike(object)) {
+        return arrayLikeKeys(object);
+    }
+    const result = Object.keys(Object(object));
+    if (!isPrototype(object)) {
+        return result;
+    }
+    return result.filter(key => key !== 'constructor');
+}
+function arrayLikeKeys(object) {
+    const indices = times(object.length, index => `${index}`);
+    const filteredKeys = new Set(indices);
+    if (isBuffer(object)) {
+        filteredKeys.add('offset');
+        filteredKeys.add('parent');
+    }
+    if (isTypedArray(object)) {
+        filteredKeys.add('buffer');
+        filteredKeys.add('byteLength');
+        filteredKeys.add('byteOffset');
+    }
+    return [...indices, ...Object.keys(object).filter(key => !filteredKeys.has(key))];
+}
+
+export { keys };

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

@@ -0,0 +1,22 @@
+/**
+ * Creates a function that returns the value at a given path of an object.
+ *
+ * Unlike `property`, which creates a function bound to a specific path and allows you to query different objects,
+ * `propertyOf` creates a function bound to a specific object and allows you to query different paths within that object.
+ *
+ * @param {unknown} object - The object to query.
+ * @returns {(path: PropertyKey | PropertyKey[]) => unknown} - Returns a new function that takes a path and retrieves the value from the object at the specified path.
+ *
+ * @example
+ * const getValue = propertyOf({ a: { b: { c: 3 } } });
+ * const result = getValue('a.b.c');
+ * console.log(result); // => 3
+ *
+ * @example
+ * const getValue = propertyOf({ a: { b: { c: 3 } } });
+ * const result = getValue(['a', 'b', 'c']);
+ * console.log(result); // => 3
+ */
+declare function propertyOf(object: unknown): (path: PropertyKey | readonly PropertyKey[]) => unknown;
+
+export { propertyOf };

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

@@ -0,0 +1,22 @@
+/**
+ * Creates a function that returns the value at a given path of an object.
+ *
+ * Unlike `property`, which creates a function bound to a specific path and allows you to query different objects,
+ * `propertyOf` creates a function bound to a specific object and allows you to query different paths within that object.
+ *
+ * @param {unknown} object - The object to query.
+ * @returns {(path: PropertyKey | PropertyKey[]) => unknown} - Returns a new function that takes a path and retrieves the value from the object at the specified path.
+ *
+ * @example
+ * const getValue = propertyOf({ a: { b: { c: 3 } } });
+ * const result = getValue('a.b.c');
+ * console.log(result); // => 3
+ *
+ * @example
+ * const getValue = propertyOf({ a: { b: { c: 3 } } });
+ * const result = getValue(['a', 'b', 'c']);
+ * console.log(result); // => 3
+ */
+declare function propertyOf(object: unknown): (path: PropertyKey | readonly PropertyKey[]) => unknown;
+
+export { propertyOf };

package/dist/compat/object/propertyOf.mjs

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

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

@@ -12,6 +12,6 @@
  * isArrayLike(null); // false
  * isArrayLike(undefined); // false
  */
-declare function isArrayLike(value: unknown): value is ArrayLike<unknown>;
+declare function isArrayLike(value?: unknown): value is ArrayLike<unknown>;
 
 export { isArrayLike };

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

@@ -12,6 +12,6 @@
  * isArrayLike(null); // false
  * isArrayLike(undefined); // false
  */
-declare function isArrayLike(value: unknown): value is ArrayLike<unknown>;
+declare function isArrayLike(value?: unknown): value is ArrayLike<unknown>;
 
 export { isArrayLike };

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

@@ -10,6 +10,6 @@
  * isArrayLikeObject('abc'); // false
  * isArrayLikeObject(()=>{}); // false
  */
-declare function isArrayLikeObject(value: unknown): value is ArrayLike<unknown> & object;
+declare function isArrayLikeObject(value?: unknown): value is ArrayLike<unknown> & object;
 
 export { isArrayLikeObject };

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

@@ -10,6 +10,6 @@
  * isArrayLikeObject('abc'); // false
  * isArrayLikeObject(()=>{}); // false
  */
-declare function isArrayLikeObject(value: unknown): value is ArrayLike<unknown> & object;
+declare function isArrayLikeObject(value?: unknown): value is ArrayLike<unknown> & object;
 
 export { isArrayLikeObject };

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

@@ -8,6 +8,6 @@
  * console.log(isElement(document.body)); // true
  * console.log(isElement('<body>')); // false
  */
-declare function isElement(value: any): boolean;
+declare function isElement(value?: any): boolean;
 
 export { isElement };

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

@@ -8,6 +8,6 @@
  * console.log(isElement(document.body)); // true
  * console.log(isElement('<body>')); // false
  */
-declare function isElement(value: any): boolean;
+declare function isElement(value?: any): boolean;
 
 export { isElement };

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

@@ -15,6 +15,6 @@
  * console.log(isFinite(value3)); // false
  * ```
  */
-declare function isFinite(value: unknown): value is number;
+declare function isFinite(value?: unknown): value is number;
 
 export { isFinite };

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

@@ -15,6 +15,6 @@
  * console.log(isFinite(value3)); // false
  * ```
  */
-declare function isFinite(value: unknown): value is number;
+declare function isFinite(value?: unknown): value is number;
 
 export { isFinite };

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

@@ -10,6 +10,6 @@
  * isNaN('NaN'); // false
  * isNaN(undefined); // false
  */
-declare function isNaN(value: unknown): value is typeof NaN;
+declare function isNaN(value?: unknown): value is typeof NaN;
 
 export { isNaN };

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

@@ -10,6 +10,6 @@
  * isNaN('NaN'); // false
  * isNaN(undefined); // false
  */
-declare function isNaN(value: unknown): value is typeof NaN;
+declare function isNaN(value?: unknown): value is typeof NaN;
 
 export { isNaN };

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

@@ -21,6 +21,6 @@
  * console.log(isObject(value3)); // true
  * console.log(isObject(value4)); // false
  */
-declare function isObject(value: unknown): value is object;
+declare function isObject(value?: unknown): value is object;
 
 export { isObject };

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

@@ -21,6 +21,6 @@
  * console.log(isObject(value3)); // true
  * console.log(isObject(value4)); // false
  */
-declare function isObject(value: unknown): value is object;
+declare function isObject(value?: unknown): value is object;
 
 export { isObject };

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

@@ -22,6 +22,6 @@
  * console.log(isObjectLike(value4)); // false
  * console.log(isObjectLike(value5)); // false
  */
-declare function isObjectLike(value: unknown): value is object;
+declare function isObjectLike(value?: unknown): value is object;
 
 export { isObjectLike };

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

@@ -22,6 +22,6 @@
  * console.log(isObjectLike(value4)); // false
  * console.log(isObjectLike(value5)); // false
  */
-declare function isObjectLike(value: unknown): value is object;
+declare function isObjectLike(value?: unknown): value is object;
 
 export { isObjectLike };

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

@@ -0,0 +1,22 @@
+/**
+ * Converts a string by replacing special characters and diacritical marks with their ASCII equivalents.
+ * For example, "Crème brûlée" becomes "Creme brulee".
+ *
+ * @param {string} str - The input string to be deburred.
+ * @returns {string} - The deburred string with special characters replaced by their ASCII equivalents.
+ *
+ * @example
+ * // Basic usage:
+ * deburr('Æthelred') // returns 'Aethelred'
+ *
+ * @example
+ * // Handling diacritical marks:
+ * deburr('München') // returns 'Munchen'
+ *
+ * @example
+ * // Special characters:
+ * deburr('Crème brûlée') // returns 'Creme brulee'
+ */
+declare function deburr(str?: string): string;
+
+export { deburr };

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

@@ -0,0 +1,22 @@
+/**
+ * Converts a string by replacing special characters and diacritical marks with their ASCII equivalents.
+ * For example, "Crème brûlée" becomes "Creme brulee".
+ *
+ * @param {string} str - The input string to be deburred.
+ * @returns {string} - The deburred string with special characters replaced by their ASCII equivalents.
+ *
+ * @example
+ * // Basic usage:
+ * deburr('Æthelred') // returns 'Aethelred'
+ *
+ * @example
+ * // Handling diacritical marks:
+ * deburr('München') // returns 'Munchen'
+ *
+ * @example
+ * // Special characters:
+ * deburr('Crème brûlée') // returns 'Creme brulee'
+ */
+declare function deburr(str?: string): string;
+
+export { deburr };

package/dist/compat/string/deburr.mjs

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

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

@@ -0,0 +1,14 @@
+/**
+ * Escapes the RegExp special characters "^", "$", "\\", ".", "*", "+", "?", "(", ")", "[", "]", "{", "}", and "|" in `str`.
+ *
+ * @param {string} str The string to escape.
+ * @returns {string} Returns the escaped string.
+ *
+ * @example
+ * import { escapeRegExp } from 'es-toolkit/string';
+ *
+ * escapeRegExp('[es-toolkit](https://es-toolkit.slash.page/)'); // returns '\[es-toolkit\]\(https://es-toolkit\.slash\.page/\)'
+ */
+declare function escapeRegExp(str?: string): string;
+
+export { escapeRegExp };

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

@@ -0,0 +1,14 @@
+/**
+ * Escapes the RegExp special characters "^", "$", "\\", ".", "*", "+", "?", "(", ")", "[", "]", "{", "}", and "|" in `str`.
+ *
+ * @param {string} str The string to escape.
+ * @returns {string} Returns the escaped string.
+ *
+ * @example
+ * import { escapeRegExp } from 'es-toolkit/string';
+ *
+ * escapeRegExp('[es-toolkit](https://es-toolkit.slash.page/)'); // returns '\[es-toolkit\]\(https://es-toolkit\.slash\.page/\)'
+ */
+declare function escapeRegExp(str?: string): string;
+
+export { escapeRegExp };

package/dist/compat/string/escapeRegExp.mjs

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

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

@@ -0,0 +1,14 @@
+/**
+ * Converts the first character of string to lower case.
+ *
+ * @param {string} str - The string that is to be changed
+ * @returns {string} - The converted string.
+ *
+ * @example
+ * const convertedStr1 = lowerCase('fred') // returns 'fred'
+ * const convertedStr2 = lowerCase('Fred') // returns 'fred'
+ * const convertedStr3 = lowerCase('FRED') // returns 'fRED'
+ */
+declare function lowerFirst(str?: string): string;
+
+export { lowerFirst };

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

@@ -0,0 +1,14 @@
+/**
+ * Converts the first character of string to lower case.
+ *
+ * @param {string} str - The string that is to be changed
+ * @returns {string} - The converted string.
+ *
+ * @example
+ * const convertedStr1 = lowerCase('fred') // returns 'fred'
+ * const convertedStr2 = lowerCase('Fred') // returns 'fred'
+ * const convertedStr3 = lowerCase('FRED') // returns 'fRED'
+ */
+declare function lowerFirst(str?: string): string;
+
+export { lowerFirst };

package/dist/compat/string/lowerFirst.mjs

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

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

@@ -0,0 +1,20 @@
+/**
+ * Converts the given value to a string and transforms it to lower case.
+ * The function can handle various input types by first converting them to strings.
+ *
+ * @param {unknown} [value=''] The value to convert.
+ * @returns {string} Returns the lower cased string.
+ * @example
+ *
+ * toLower('--FOO-BAR--');
+ * // => '--foo-bar--'
+ *
+ * toLower(null);
+ * // => ''
+ *
+ * toLower([1, 2, 3]);
+ * // => '1,2,3'
+ */
+declare function toLower(value?: unknown): string;
+
+export { toLower };

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

@@ -0,0 +1,20 @@
+/**
+ * Converts the given value to a string and transforms it to lower case.
+ * The function can handle various input types by first converting them to strings.
+ *
+ * @param {unknown} [value=''] The value to convert.
+ * @returns {string} Returns the lower cased string.
+ * @example
+ *
+ * toLower('--FOO-BAR--');
+ * // => '--foo-bar--'
+ *
+ * toLower(null);
+ * // => ''
+ *
+ * toLower([1, 2, 3]);
+ * // => '1,2,3'
+ */
+declare function toLower(value?: unknown): string;
+
+export { toLower };

package/dist/compat/string/toLower.mjs

@@ -0,0 +1,7 @@
+import { toString } from '../util/toString.mjs';
+
+function toLower(value) {
+    return toString(value).toLowerCase();
+}
+
+export { toLower };

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

@@ -0,0 +1,16 @@
+/**
+ * Converts the HTML entities `&`, `<`, `>`, `"`, and `'` in `str` to their corresponding characters.
+ * It is the inverse of `escape`.
+ *
+ * @param {string} str The string to unescape.
+ * @returns {string} Returns the unescaped string.
+ *
+ * @example
+ * unescape('This is a &lt;div&gt; element.'); // returns 'This is a <div> element.'
+ * unescape('This is a &quot;quote&quot;'); // returns 'This is a "quote"'
+ * unescape('This is a &#39;quote&#39;'); // returns 'This is a 'quote''
+ * unescape('This is a &amp; symbol'); // returns 'This is a & symbol'
+ */
+declare function unescape(str?: string): string;
+
+export { unescape };

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

@@ -0,0 +1,16 @@
+/**
+ * Converts the HTML entities `&`, `<`, `>`, `"`, and `'` in `str` to their corresponding characters.
+ * It is the inverse of `escape`.
+ *
+ * @param {string} str The string to unescape.
+ * @returns {string} Returns the unescaped string.
+ *
+ * @example
+ * unescape('This is a &lt;div&gt; element.'); // returns 'This is a <div> element.'
+ * unescape('This is a &quot;quote&quot;'); // returns 'This is a "quote"'
+ * unescape('This is a &#39;quote&#39;'); // returns 'This is a 'quote''
+ * unescape('This is a &amp; symbol'); // returns 'This is a & symbol'
+ */
+declare function unescape(str?: string): string;
+
+export { unescape };

package/dist/compat/string/unescape.mjs

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

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

@@ -0,0 +1,14 @@
+/**
+ * Converts the first character of string to upper case.
+ *
+ * @param {string} str - The string that is to be changed
+ * @returns {string} - The converted string.
+ *
+ * @example
+ * const convertedStr1 = upperFirst('fred') // returns 'Fred'
+ * const convertedStr2 = upperFirst('Fred') // returns 'Fred'
+ * const convertedStr3 = upperFirst('FRED') // returns 'FRED'
+ */
+declare function upperFirst(str?: string): string;
+
+export { upperFirst };

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

@@ -0,0 +1,14 @@
+/**
+ * Converts the first character of string to upper case.
+ *
+ * @param {string} str - The string that is to be changed
+ * @returns {string} - The converted string.
+ *
+ * @example
+ * const convertedStr1 = upperFirst('fred') // returns 'Fred'
+ * const convertedStr2 = upperFirst('Fred') // returns 'Fred'
+ * const convertedStr3 = upperFirst('FRED') // returns 'FRED'
+ */
+declare function upperFirst(str?: string): string;
+
+export { upperFirst };

package/dist/compat/string/upperFirst.mjs

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

package/dist/compat/util/invoke.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Invokes the method at `path` of `object` with the given arguments.
+ *
+ * @param {unknown} object - The object to query.
+ * @param {PropertyKey | PropertyKey[]} path - The path of the method to invoke.
+ * @param {any[]} args - The arguments to invoke the method with.
+ * @returns {any} - Returns the result of the invoked method.
+ *
+ * @example
+ * const object = {
+ *   a: {
+ *     b: function (x, y) {
+ *       return x + y;
+ *     }
+ *   }
+ * };
+ *
+ * invoke(object, 'a.b', [1, 2]); // => 3
+ * invoke(object, ['a', 'b'], [1, 2]); // => 3
+ */
+declare function invoke(object: unknown, path: PropertyKey | PropertyKey[], args?: any[]): any;
+
+export { invoke };

package/dist/compat/util/invoke.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Invokes the method at `path` of `object` with the given arguments.
+ *
+ * @param {unknown} object - The object to query.
+ * @param {PropertyKey | PropertyKey[]} path - The path of the method to invoke.
+ * @param {any[]} args - The arguments to invoke the method with.
+ * @returns {any} - Returns the result of the invoked method.
+ *
+ * @example
+ * const object = {
+ *   a: {
+ *     b: function (x, y) {
+ *       return x + y;
+ *     }
+ *   }
+ * };
+ *
+ * invoke(object, 'a.b', [1, 2]); // => 3
+ * invoke(object, ['a', 'b'], [1, 2]); // => 3
+ */
+declare function invoke(object: unknown, path: PropertyKey | PropertyKey[], args?: any[]): any;
+
+export { invoke };

package/dist/compat/util/invoke.mjs

@@ -0,0 +1,48 @@
+import { toPath } from './toPath.mjs';
+import { toKey } from '../_internal/toKey.mjs';
+import { last } from '../array/last.mjs';
+import { get } from '../object/get.mjs';
+
+function invoke(object, path, args = []) {
+    if (object == null) {
+        return;
+    }
+    switch (typeof path) {
+        case 'string': {
+            if (typeof object === 'object' && Object.hasOwn(object, path)) {
+                return invokeImpl(object, [path], args);
+            }
+            return invokeImpl(object, toPath(path), args);
+        }
+        case 'number':
+        case 'symbol': {
+            return invokeImpl(object, [path], args);
+        }
+        default: {
+            if (Array.isArray(path)) {
+                return invokeImpl(object, path, args);
+            }
+            else {
+                return invokeImpl(object, [path], args);
+            }
+        }
+    }
+}
+function invokeImpl(object, path, args) {
+    const parent = get(object, path.slice(0, -1), object);
+    if (parent == null) {
+        return undefined;
+    }
+    let lastKey = last(path);
+    let lastValue = lastKey?.valueOf();
+    if (typeof lastValue === 'number') {
+        lastKey = toKey(lastValue);
+    }
+    else {
+        lastKey = String(lastKey);
+    }
+    const func = get(parent, lastKey);
+    return func?.apply(parent, args);
+}
+
+export { invoke };

package/dist/compat/util/lt.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Checks if value is less than other.
+ *
+ * @param {unknown} value The value to compare.
+ * @param {unknown} other The other value to compare.
+ * @returns {boolean} Returns `true` if value is less than other, else `false`.
+ *
+ * @example
+ * lt(1, 3); // true
+ * lt(3, 3); // false
+ * lt(3, 1); // false
+ */
+declare function lt(value: unknown, other: unknown): boolean;
+
+export { lt };

package/dist/compat/util/lt.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Checks if value is less than other.
+ *
+ * @param {unknown} value The value to compare.
+ * @param {unknown} other The other value to compare.
+ * @returns {boolean} Returns `true` if value is less than other, else `false`.
+ *
+ * @example
+ * lt(1, 3); // true
+ * lt(3, 3); // false
+ * lt(3, 1); // false
+ */
+declare function lt(value: unknown, other: unknown): boolean;
+
+export { lt };

package/dist/compat/util/lt.mjs

@@ -0,0 +1,10 @@
+import { toNumber } from './toNumber.mjs';
+
+function lt(value, other) {
+    if (typeof value === 'string' && typeof other === 'string') {
+        return value < other;
+    }
+    return toNumber(value) < toNumber(other);
+}
+
+export { lt };

package/dist/compat/util/lte.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Checks if value is less than or equal to other.
+ *
+ * @param {unknown} value The value to compare.
+ * @param {unknown} other The other value to compare.
+ * @returns {boolean} Returns `true` if value is less than or equal to other, else `false`.
+ *
+ * @example
+ * lte(1, 3); // => true
+ * lte(3, 3); // => true
+ * lte(3, 1); // => false
+ */
+declare function lte(value: unknown, other: unknown): boolean;
+
+export { lte };