es-toolkit 1.20.0 → 1.21.0-dev.660

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

@@ -0,0 +1,50 @@
+/**
+ * Generate a random number within 0 and 1.
+ *
+ * @returns {number} A random number between 0 (inclusive) and 1 (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `0`.
+ *
+ * @example
+ * const result = random(); // Returns a random number between 0 and 1.
+ */
+declare function random(floating?: boolean): number;
+/**
+ * Generate a random number within 0 and 1.
+ *
+ * @returns {number} A random number between 0 (inclusive) and 1 (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `0`.
+ *
+ * @example
+ * const result = random(); // Returns a random number between 0 and 1.
+ */
+declare function random(min: number, index: string | number, guard: object): number;
+/**
+ * Generate a random number within the given range.
+ *
+ * If only one argument is provided, a number between `0` and the given number is returned.
+ *
+ * @param {number} maximum - The upper bound (exclusive).
+ * @returns {number} A random number between 0 (inclusive) and maximum (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `0`.
+ *
+ * @example
+ * const result1 = random(5); // Returns a random number between 0 and 5.
+ * const result2 = random(0); // Returns a random number between 0 and 0 (which is 0).
+ */
+declare function random(maximum: number, floating?: boolean): number;
+/**
+ * Generate a random number within the given range.
+ *
+ * @param {number} minimum - The lower bound (inclusive).
+ * @param {number} maximum - The upper bound (exclusive).
+ * @returns {number} A random number between minimum (inclusive) and maximum (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `minimum`.
+ *
+ * @example
+ * const result1 = random(0, 5); // Returns a random number between 0 and 5.
+ * const result2 = random(5, 0); // If the minimum is greater than the maximum, an error is thrown.
+ * const result3 = random(5, 5); // If the minimum is equal to the maximum, an error is thrown.
+ */
+declare function random(minimum: number, maximum: number, floating?: boolean): number;
+
+export { random };

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

@@ -0,0 +1,50 @@
+/**
+ * Generate a random number within 0 and 1.
+ *
+ * @returns {number} A random number between 0 (inclusive) and 1 (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `0`.
+ *
+ * @example
+ * const result = random(); // Returns a random number between 0 and 1.
+ */
+declare function random(floating?: boolean): number;
+/**
+ * Generate a random number within 0 and 1.
+ *
+ * @returns {number} A random number between 0 (inclusive) and 1 (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `0`.
+ *
+ * @example
+ * const result = random(); // Returns a random number between 0 and 1.
+ */
+declare function random(min: number, index: string | number, guard: object): number;
+/**
+ * Generate a random number within the given range.
+ *
+ * If only one argument is provided, a number between `0` and the given number is returned.
+ *
+ * @param {number} maximum - The upper bound (exclusive).
+ * @returns {number} A random number between 0 (inclusive) and maximum (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `0`.
+ *
+ * @example
+ * const result1 = random(5); // Returns a random number between 0 and 5.
+ * const result2 = random(0); // Returns a random number between 0 and 0 (which is 0).
+ */
+declare function random(maximum: number, floating?: boolean): number;
+/**
+ * Generate a random number within the given range.
+ *
+ * @param {number} minimum - The lower bound (inclusive).
+ * @param {number} maximum - The upper bound (exclusive).
+ * @returns {number} A random number between minimum (inclusive) and maximum (exclusive). The number can be an integer or a decimal.
+ * @throws {Error} Throws an error if `maximum` is not greater than `minimum`.
+ *
+ * @example
+ * const result1 = random(0, 5); // Returns a random number between 0 and 5.
+ * const result2 = random(5, 0); // If the minimum is greater than the maximum, an error is thrown.
+ * const result3 = random(5, 5); // If the minimum is equal to the maximum, an error is thrown.
+ */
+declare function random(minimum: number, maximum: number, floating?: boolean): number;
+
+export { random };

package/dist/compat/math/random.mjs

@@ -0,0 +1,70 @@
+import { random as random$1 } from '../../math/random.mjs';
+import { randomInt } from '../../math/randomInt.mjs';
+import { clamp } from './clamp.mjs';
+
+function random(...args) {
+    let minimum = 0;
+    let maximum = 1;
+    let floating = false;
+    switch (args.length) {
+        case 1: {
+            if (typeof args[0] === 'boolean') {
+                floating = args[0];
+            }
+            else {
+                maximum = args[0];
+            }
+            break;
+        }
+        case 2: {
+            if (typeof args[1] === 'boolean') {
+                maximum = args[0];
+                floating = args[1];
+            }
+            else {
+                minimum = args[0];
+                maximum = args[1];
+            }
+        }
+        case 3: {
+            if (typeof args[2] === 'object' && args[2] != null && args[2][args[1]] === args[0]) {
+                minimum = 0;
+                maximum = args[0];
+                floating = false;
+            }
+            else {
+                minimum = args[0];
+                maximum = args[1];
+                floating = args[2];
+            }
+        }
+    }
+    if (typeof minimum !== 'number') {
+        minimum = Number(minimum);
+    }
+    if (typeof maximum !== 'number') {
+        minimum = Number(maximum);
+    }
+    if (!minimum) {
+        minimum = 0;
+    }
+    if (!maximum) {
+        maximum = 0;
+    }
+    if (minimum > maximum) {
+        [minimum, maximum] = [maximum, minimum];
+    }
+    minimum = clamp(minimum, -Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+    maximum = clamp(maximum, -Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+    if (minimum === maximum) {
+        return minimum;
+    }
+    if (floating) {
+        return random$1(minimum, maximum + 1);
+    }
+    else {
+        return randomInt(minimum, maximum + 1);
+    }
+}
+
+export { random };

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

@@ -0,0 +1,49 @@
+/**
+ * Creates a deep clone of the given object.
+ *
+ * @template T - The type of the object.
+ * @param {T} obj - The object to clone.
+ * @returns {T} - A deep clone of the given object.
+ *
+ * @example
+ * // Clone a primitive values
+ * const num = 29;
+ * const clonedNum = clone(num);
+ * console.log(clonedNum); // 29
+ * console.log(clonedNum === num) ; // true
+ *
+ * @example
+ * // Clone an array
+ * const arr = [1, 2, 3];
+ * const clonedArr = clone(arr);
+ * console.log(clonedArr); // [1, 2, 3]
+ * console.log(clonedArr === arr); // false
+ *
+ * @example
+ * // Clone an array with nested objects
+ * const arr = [1, { a: 1 }, [1, 2, 3]];
+ * const clonedArr = clone(arr);
+ * arr[1].a = 2;
+ * console.log(arr); // [2, { a: 2 }, [1, 2, 3]]
+ * console.log(clonedArr); // [1, { a: 1 }, [1, 2, 3]]
+ * console.log(clonedArr === arr); // false
+ *
+ * @example
+ * // Clone an object
+ * const obj = { a: 1, b: 'es-toolkit', c: [1, 2, 3] };
+ * const clonedObj = clone(obj);
+ * console.log(clonedObj); // { a: 1, b: 'es-toolkit', c: [1, 2, 3] }
+ * console.log(clonedObj === obj); // false
+ *
+ * @example
+ * // Clone an object with nested objects
+ * const obj = { a: 1, b: { c: 1 } };
+ * const clonedObj = clone(obj);
+ * obj.b.c = 2;
+ * console.log(obj); // { a: 1, b: { c: 2 } }
+ * console.log(clonedObj); // { a: 1, b: { c: 1 } }
+ * console.log(clonedObj === obj); // false
+ */
+declare function cloneDeep<T>(obj: T): T;
+
+export { cloneDeep };

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

@@ -0,0 +1,49 @@
+/**
+ * Creates a deep clone of the given object.
+ *
+ * @template T - The type of the object.
+ * @param {T} obj - The object to clone.
+ * @returns {T} - A deep clone of the given object.
+ *
+ * @example
+ * // Clone a primitive values
+ * const num = 29;
+ * const clonedNum = clone(num);
+ * console.log(clonedNum); // 29
+ * console.log(clonedNum === num) ; // true
+ *
+ * @example
+ * // Clone an array
+ * const arr = [1, 2, 3];
+ * const clonedArr = clone(arr);
+ * console.log(clonedArr); // [1, 2, 3]
+ * console.log(clonedArr === arr); // false
+ *
+ * @example
+ * // Clone an array with nested objects
+ * const arr = [1, { a: 1 }, [1, 2, 3]];
+ * const clonedArr = clone(arr);
+ * arr[1].a = 2;
+ * console.log(arr); // [2, { a: 2 }, [1, 2, 3]]
+ * console.log(clonedArr); // [1, { a: 1 }, [1, 2, 3]]
+ * console.log(clonedArr === arr); // false
+ *
+ * @example
+ * // Clone an object
+ * const obj = { a: 1, b: 'es-toolkit', c: [1, 2, 3] };
+ * const clonedObj = clone(obj);
+ * console.log(clonedObj); // { a: 1, b: 'es-toolkit', c: [1, 2, 3] }
+ * console.log(clonedObj === obj); // false
+ *
+ * @example
+ * // Clone an object with nested objects
+ * const obj = { a: 1, b: { c: 1 } };
+ * const clonedObj = clone(obj);
+ * obj.b.c = 2;
+ * console.log(obj); // { a: 1, b: { c: 2 } }
+ * console.log(clonedObj); // { a: 1, b: { c: 1 } }
+ * console.log(clonedObj === obj); // false
+ */
+declare function cloneDeep<T>(obj: T): T;
+
+export { cloneDeep };

package/dist/compat/object/pick.mjs

@@ -7,7 +7,8 @@ function pick(obj, ...keysArr) {
         return {};
     }
     const result = {};
-    for (let keys of keysArr) {
+    for (let i = 0; i < keysArr.length; i++) {
+        let keys = keysArr[i];
         switch (typeof keys) {
             case 'object': {
                 if (!Array.isArray(keys)) {

package/dist/compat/predicate/conformsTo.mjs

@@ -5,7 +5,9 @@ function conformsTo(target, source) {
     if (target == null) {
         return Object.keys(source).length === 0;
     }
-    for (const key of Object.keys(source)) {
+    const keys = Object.keys(source);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
         const predicate = source[key];
         const value = target[key];
         if ((value === undefined && !(key in target)) || !predicate(value)) {

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

@@ -0,0 +1,15 @@
+/**
+ * Checks if the given value is a non-primitive, array-like object.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is ArrayLike<unknown> & object} `true` if the value is a non-primitive, array-like object, `false` otherwise.
+ *
+ * @example
+ * isArrayLikeObject([1, 2, 3]); // true
+ * isArrayLikeObject({ 0: 'a', length: 1 }); // true
+ * isArrayLikeObject('abc'); // false
+ * isArrayLikeObject(()=>{}); // false
+ */
+declare function isArrayLikeObject(value: unknown): value is ArrayLike<unknown> & object;
+
+export { isArrayLikeObject };

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

@@ -0,0 +1,15 @@
+/**
+ * Checks if the given value is a non-primitive, array-like object.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is ArrayLike<unknown> & object} `true` if the value is a non-primitive, array-like object, `false` otherwise.
+ *
+ * @example
+ * isArrayLikeObject([1, 2, 3]); // true
+ * isArrayLikeObject({ 0: 'a', length: 1 }); // true
+ * isArrayLikeObject('abc'); // false
+ * isArrayLikeObject(()=>{}); // false
+ */
+declare function isArrayLikeObject(value: unknown): value is ArrayLike<unknown> & object;
+
+export { isArrayLikeObject };

package/dist/compat/predicate/isArrayLikeObject.mjs

@@ -0,0 +1,8 @@
+import { isArrayLike } from './isArrayLike.mjs';
+import { isObjectLike } from './isObjectLike.mjs';
+
+function isArrayLikeObject(value) {
+    return isObjectLike(value) && isArrayLike(value);
+}
+
+export { isArrayLikeObject };

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

@@ -6,8 +6,8 @@
  *
  *  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 boolean, false otherwise.
+ * @param {unknown} value - The Value to test if it is boolean.
+ * @returns {value is boolean} True if the value is boolean, false otherwise.
  *
  * @example
  *
@@ -20,6 +20,6 @@
  * console.log(isBoolean(value3)); // false
  *
  */
-declare function isBoolean(x: unknown): x is boolean;
+declare function isBoolean(value?: unknown): value is boolean;
 
 export { isBoolean };

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

@@ -6,8 +6,8 @@
  *
  *  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 boolean, false otherwise.
+ * @param {unknown} value - The Value to test if it is boolean.
+ * @returns {value is boolean} True if the value is boolean, false otherwise.
  *
  * @example
  *
@@ -20,6 +20,6 @@
  * console.log(isBoolean(value3)); // false
  *
  */
-declare function isBoolean(x: unknown): x is boolean;
+declare function isBoolean(value?: unknown): value is boolean;
 
 export { isBoolean };

package/dist/compat/predicate/isBoolean.mjs

@@ -1,13 +1,5 @@
-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;
+function isBoolean(value) {
+    return typeof value === 'boolean' || value instanceof Boolean;
 }
 
 export { isBoolean };

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

@@ -0,0 +1,16 @@
+/**
+ * Checks if `value` is an Error object.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is Error} Returns `true` if `value` is an Error object, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * console.log(isError(new Error())); // true
+ * console.log(isError('Error')); // false
+ * console.log(isError({ name: 'Error', message: '' })); // false
+ * ```
+ */
+declare function isError(value?: unknown): value is Error;
+
+export { isError };

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

@@ -0,0 +1,16 @@
+/**
+ * Checks if `value` is an Error object.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is Error} Returns `true` if `value` is an Error object, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * console.log(isError(new Error())); // true
+ * console.log(isError('Error')); // false
+ * console.log(isError({ name: 'Error', message: '' })); // false
+ * ```
+ */
+declare function isError(value?: unknown): value is Error;
+
+export { isError };

package/dist/compat/predicate/isError.mjs

@@ -0,0 +1,7 @@
+import { getTag } from '../_internal/getTag.mjs';
+
+function isError(value) {
+    return getTag(value) === '[object Error]';
+}
+
+export { isError };

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if `value` is a finite number.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is number} Returns `true` if `value` is a finite number, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * const value1 = 100;
+ * const value2 = Infinity;
+ * const value3 = '100';
+ *
+ * console.log(isFinite(value1)); // true
+ * console.log(isFinite(value2)); // false
+ * console.log(isFinite(value3)); // false
+ * ```
+ */
+declare function isFinite(value: unknown): value is number;
+
+export { isFinite };

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if `value` is a finite number.
+ *
+ * @param {unknown} value The value to check.
+ * @returns {value is number} Returns `true` if `value` is a finite number, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * const value1 = 100;
+ * const value2 = Infinity;
+ * const value3 = '100';
+ *
+ * console.log(isFinite(value1)); // true
+ * console.log(isFinite(value2)); // false
+ * console.log(isFinite(value3)); // false
+ * ```
+ */
+declare function isFinite(value: unknown): value is number;
+
+export { isFinite };

package/dist/compat/predicate/isFinite.mjs

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

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

@@ -0,0 +1,22 @@
+/**
+ * Checks if a given value is null or undefined.
+ *
+ * This function tests whether the provided value is either `null` or `undefined`.
+ * It returns `true` if the value is `null` or `undefined`, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null` or `undefined`.
+ *
+ * @param {unknown} x - The value to test for null or undefined.
+ * @returns {boolean} `true` if the value is null or undefined, `false` otherwise.
+ *
+ * @example
+ * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ * const result1 = isNil(value1); // true
+ * const result2 = isNil(value2); // true
+ * const result3 = isNil(value3); // false
+ */
+declare function isNil(x?: unknown): x is null | undefined;
+
+export { isNil };

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

@@ -0,0 +1,22 @@
+/**
+ * Checks if a given value is null or undefined.
+ *
+ * This function tests whether the provided value is either `null` or `undefined`.
+ * It returns `true` if the value is `null` or `undefined`, and `false` otherwise.
+ *
+ * This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to `null` or `undefined`.
+ *
+ * @param {unknown} x - The value to test for null or undefined.
+ * @returns {boolean} `true` if the value is null or undefined, `false` otherwise.
+ *
+ * @example
+ * const value1 = null;
+ * const value2 = undefined;
+ * const value3 = 42;
+ * const result1 = isNil(value1); // true
+ * const result2 = isNil(value2); // true
+ * const result3 = isNil(value3); // false
+ */
+declare function isNil(x?: unknown): x is null | undefined;
+
+export { isNil };

package/dist/compat/predicate/isNumber.mjs

@@ -1,10 +1,5 @@
-import { getTag } from '../_internal/getTag.mjs';
-
 function isNumber(value) {
-    if (typeof value === 'object' && value != null && getTag(value) === '[object Number]') {
-        return true;
-    }
-    return typeof value === 'number';
+    return typeof value === 'number' || value instanceof Number;
 }
 
 export { isNumber };

package/dist/compat/predicate/isRegExp.mjs

@@ -1,7 +1,7 @@
-import { getTag } from '../_internal/getTag.mjs';
+import { isRegExp as isRegExp$1 } from '../../predicate/isRegExp.mjs';
 
 function isRegExp(value) {
-    return getTag(value) === '[object RegExp]';
+    return isRegExp$1(value);
 }
 
 export { isRegExp };

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

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

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

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

package/dist/compat/predicate/isString.mjs

@@ -1,13 +1,5 @@
-import { getTag } from '../_internal/getTag.mjs';
-
 function isString(value) {
-    if (typeof value === 'string') {
-        return true;
-    }
-    if (typeof value === 'object' && value != null && getTag(value) === '[object String]') {
-        return true;
-    }
-    return false;
+    return typeof value === 'string' || value instanceof String;
 }
 
 export { isString };

package/dist/compat/predicate/isSymbol.mjs

@@ -1,5 +1,5 @@
 function isSymbol(value) {
-    return typeof value === 'symbol' || (value != null && value instanceof Symbol);
+    return typeof value === 'symbol' || value instanceof Symbol;
 }
 
 export { isSymbol };

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

@@ -0,0 +1,19 @@
+/**
+ * Pads string on the left and right sides if it's shorter than length. Padding characters are truncated if they can't be evenly divided by length.
+ * If the length is less than or equal to the original string's length, or if the padding character is an empty string, the original string is returned unchanged.
+ *
+ * @param {string} str - The string to pad.
+ * @param {number} [length] - The length of the resulting string once padded.
+ * @param {string} [chars] - The character(s) to use for padding.
+ * @returns {string} - The padded string, or the original string if padding is not required.
+ *
+ * @example
+ * const result1 = pad('abc', 8);         // result will be '  abc   '
+ * const result2 = pad('abc', 8, '_-');   // result will be '_-abc_-_'
+ * const result3 = pad('abc', 3);         // result will be 'abc'
+ * const result4 = pad('abc', 2);         // result will be 'abc'
+ *
+ */
+declare function pad(str: string, length: number, chars?: string): string;
+
+export { pad };

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

@@ -0,0 +1,19 @@
+/**
+ * Pads string on the left and right sides if it's shorter than length. Padding characters are truncated if they can't be evenly divided by length.
+ * If the length is less than or equal to the original string's length, or if the padding character is an empty string, the original string is returned unchanged.
+ *
+ * @param {string} str - The string to pad.
+ * @param {number} [length] - The length of the resulting string once padded.
+ * @param {string} [chars] - The character(s) to use for padding.
+ * @returns {string} - The padded string, or the original string if padding is not required.
+ *
+ * @example
+ * const result1 = pad('abc', 8);         // result will be '  abc   '
+ * const result2 = pad('abc', 8, '_-');   // result will be '_-abc_-_'
+ * const result3 = pad('abc', 3);         // result will be 'abc'
+ * const result4 = pad('abc', 2);         // result will be 'abc'
+ *
+ */
+declare function pad(str: string, length: number, chars?: string): string;
+
+export { pad };

package/dist/compat/string/pad.mjs

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

package/dist/compat/string/padEnd.mjs

@@ -1,5 +1,7 @@
+import { toString } from '../util/toString.mjs';
+
 function padEnd(str, length = 0, chars = ' ') {
-    return str.padEnd(length, chars);
+    return toString(str).padEnd(length, chars);
 }
 
 export { padEnd };