es-toolkit 1.13.1 → 1.14.0-dev.399

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

@@ -0,0 +1,25 @@
+/**
+ * Checks if a given value is a plain object.
+ *
+ * A plain object is an object created by the `{}` literal, `new Object()`, or
+ * `Object.create(null)`.
+ *
+ * This function also handles objects with custom
+ * `Symbol.toStringTag` properties.
+ *
+ * `Symbol.toStringTag` is a built-in symbol that a constructor can use to customize the
+ * default string description of objects.
+ *
+ * @param {unknown} [object] - The value to check.
+ * @returns {boolean} - True if the value is a plain object, otherwise false.
+ *
+ * @example
+ * console.log(isPlainObject({})); // true
+ * console.log(isPlainObject([])); // false
+ * console.log(isPlainObject(null)); // false
+ * console.log(isPlainObject(Object.create(null))); // true
+ * console.log(isPlainObject(new Map())); // false
+ */
+declare function isPlainObject(object?: unknown): boolean;
+
+export { isPlainObject };

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

@@ -0,0 +1,25 @@
+/**
+ * Checks if a given value is a plain object.
+ *
+ * A plain object is an object created by the `{}` literal, `new Object()`, or
+ * `Object.create(null)`.
+ *
+ * This function also handles objects with custom
+ * `Symbol.toStringTag` properties.
+ *
+ * `Symbol.toStringTag` is a built-in symbol that a constructor can use to customize the
+ * default string description of objects.
+ *
+ * @param {unknown} [object] - The value to check.
+ * @returns {boolean} - True if the value is a plain object, otherwise false.
+ *
+ * @example
+ * console.log(isPlainObject({})); // true
+ * console.log(isPlainObject([])); // false
+ * console.log(isPlainObject(null)); // false
+ * console.log(isPlainObject(Object.create(null))); // true
+ * console.log(isPlainObject(new Map())); // false
+ */
+declare function isPlainObject(object?: unknown): boolean;
+
+export { isPlainObject };

package/dist/compat/predicate/isPlainObject.mjs

@@ -0,0 +1,29 @@
+function isPlainObject(object) {
+    if (typeof object !== 'object') {
+        return false;
+    }
+    if (object == null) {
+        return false;
+    }
+    if (Object.getPrototypeOf(object) === null) {
+        return true;
+    }
+    if (object.toString() !== '[object Object]') {
+        const tag = object[Symbol.toStringTag];
+        if (tag == null) {
+            return false;
+        }
+        const isTagReadonly = !Object.getOwnPropertyDescriptor(object, Symbol.toStringTag)?.writable;
+        if (isTagReadonly) {
+            return false;
+        }
+        return object.toString() === `[object ${tag}]`;
+    }
+    let proto = object;
+    while (Object.getPrototypeOf(proto) !== null) {
+        proto = Object.getPrototypeOf(proto);
+    }
+    return Object.getPrototypeOf(object) === proto;
+}
+
+export { isPlainObject };

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

@@ -0,0 +1,19 @@
+/**
+ * Checks if a value is a TypedArray.
+ * @param {unknown} x The value to check.
+ * @returns {x is
+ *   | Uint8Array
+ *   | Uint8ClampedArray
+ *   | Uint16Array
+ *   | Uint32Array
+ *   | BigUint64Array
+ *   | Int8Array
+ *   | Int16Array
+ *   | Int32Array
+ *   | BigInt64Array
+ *   | Float32Array
+ *   | Float64Array} Returns true if `x` is a TypedArray, false otherwise.
+ */
+declare function isTypedArray(x?: unknown): x is Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | BigUint64Array | Int8Array | Int16Array | Int32Array | BigInt64Array | Float32Array | Float64Array;
+
+export { isTypedArray };

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

@@ -0,0 +1,19 @@
+/**
+ * Checks if a value is a TypedArray.
+ * @param {unknown} x The value to check.
+ * @returns {x is
+ *   | Uint8Array
+ *   | Uint8ClampedArray
+ *   | Uint16Array
+ *   | Uint32Array
+ *   | BigUint64Array
+ *   | Int8Array
+ *   | Int16Array
+ *   | Int32Array
+ *   | BigInt64Array
+ *   | Float32Array
+ *   | Float64Array} Returns true if `x` is a TypedArray, false otherwise.
+ */
+declare function isTypedArray(x?: unknown): x is Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | BigUint64Array | Int8Array | Int16Array | Int32Array | BigInt64Array | Float32Array | Float64Array;
+
+export { isTypedArray };

package/dist/compat/predicate/isTypedArray.mjs

@@ -0,0 +1,7 @@
+import { isTypedArray as isTypedArray$1 } from '../../predicate/isTypedArray.mjs';
+
+function isTypedArray(x) {
+    return isTypedArray$1(x);
+}
+
+export { isTypedArray };

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

@@ -0,0 +1,27 @@
+/**
+ * Creates a function that performs a deep comparison between a given target and the source object.
+ *
+ * @param {unknown} source - The source object to create the matcher from.
+ * @returns {(target: unknown) => boolean} - Returns a function that takes a target object and returns `true` if the target matches the source, otherwise `false`.
+ *
+ * @example
+ * // Basic usage
+ * const matcher = matches({ a: 1, b: 2 });
+ * matcher({ a: 1, b: 2, c: 3 }); // true
+ * matcher({ a: 1, c: 3 }); // false
+ *
+ * @example
+ * // Matching arrays
+ * const arrayMatcher = matches([1, 2, 3]);
+ * arrayMatcher([1, 2, 3, 4]); // true
+ * arrayMatcher([4, 5, 6]); // false
+ *
+ * @example
+ * // Matching objects with nested structures
+ * const nestedMatcher = matches({ a: { b: 2 } });
+ * nestedMatcher({ a: { b: 2, c: 3 } }); // true
+ * nestedMatcher({ a: { c: 3 } }); // false
+ */
+declare function matches(source: unknown): (target: unknown) => boolean;
+
+export { matches };

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

@@ -0,0 +1,27 @@
+/**
+ * Creates a function that performs a deep comparison between a given target and the source object.
+ *
+ * @param {unknown} source - The source object to create the matcher from.
+ * @returns {(target: unknown) => boolean} - Returns a function that takes a target object and returns `true` if the target matches the source, otherwise `false`.
+ *
+ * @example
+ * // Basic usage
+ * const matcher = matches({ a: 1, b: 2 });
+ * matcher({ a: 1, b: 2, c: 3 }); // true
+ * matcher({ a: 1, c: 3 }); // false
+ *
+ * @example
+ * // Matching arrays
+ * const arrayMatcher = matches([1, 2, 3]);
+ * arrayMatcher([1, 2, 3, 4]); // true
+ * arrayMatcher([4, 5, 6]); // false
+ *
+ * @example
+ * // Matching objects with nested structures
+ * const nestedMatcher = matches({ a: { b: 2 } });
+ * nestedMatcher({ a: { b: 2, c: 3 } }); // true
+ * nestedMatcher({ a: { c: 3 } }); // false
+ */
+declare function matches(source: unknown): (target: unknown) => boolean;
+
+export { matches };

package/dist/compat/predicate/matches.mjs

@@ -0,0 +1,11 @@
+import { cloneDeep } from '../../object/cloneDeep.mjs';
+import { isMatch } from './isMatch.mjs';
+
+function matches(source) {
+    source = cloneDeep(source);
+    return (target) => {
+        return isMatch(target, source);
+    };
+}
+
+export { matches };

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if a string contains another string at the end of the string.
+ *
+ * Checks if one string endsWith another string. Optional position parameter to offset searching before a certain index.
+ *
+ * @param {string} str - The string that might contain the target string.
+ * @param {string} target - The string to search for.
+ * @param {number} position - An optional position from the start to search up to this index
+ * @returns {boolean} - True if the str string ends with the target string.
+ *
+ * @example
+ * const isPrefix = endsWith('fooBar', 'foo') // returns true
+ * const isPrefix = endsWith('fooBar', 'bar') // returns false
+ * const isPrefix = endsWith('fooBar', 'abc') // returns false
+ * const isPrefix = endsWith('fooBar', 'foo', 3) // returns true
+ * const isPrefix = endsWith('fooBar', 'abc', 5) // returns false
+ */
+declare const endsWith: (str: string, target: string, position?: number) => boolean;
+
+export { endsWith };

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if a string contains another string at the end of the string.
+ *
+ * Checks if one string endsWith another string. Optional position parameter to offset searching before a certain index.
+ *
+ * @param {string} str - The string that might contain the target string.
+ * @param {string} target - The string to search for.
+ * @param {number} position - An optional position from the start to search up to this index
+ * @returns {boolean} - True if the str string ends with the target string.
+ *
+ * @example
+ * const isPrefix = endsWith('fooBar', 'foo') // returns true
+ * const isPrefix = endsWith('fooBar', 'bar') // returns false
+ * const isPrefix = endsWith('fooBar', 'abc') // returns false
+ * const isPrefix = endsWith('fooBar', 'foo', 3) // returns true
+ * const isPrefix = endsWith('fooBar', 'abc', 5) // returns false
+ */
+declare const endsWith: (str: string, target: string, position?: number) => boolean;
+
+export { endsWith };

package/dist/compat/string/endsWith.mjs

@@ -0,0 +1,5 @@
+const endsWith = (str, target, position = str.length) => {
+    return str.endsWith(target, position);
+};
+
+export { endsWith };

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

@@ -0,0 +1,20 @@
+/**
+ * Pads the start of a string with a given character until it reaches the specified 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 = padStart('abc', 6);          // result will be '   abc'
+ * const result2 = padStart('abc', 6, '_-');    // result will be '_-_abc'
+ * const result3 = padStart('abc', 3);          // result will be 'abc'
+ * const result4 = padStart('abc', 2);          // result will be 'abc'
+ */
+declare function padStart(str: string, length?: number, chars?: string): string;
+
+export { padStart };

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

@@ -0,0 +1,20 @@
+/**
+ * Pads the start of a string with a given character until it reaches the specified 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 = padStart('abc', 6);          // result will be '   abc'
+ * const result2 = padStart('abc', 6, '_-');    // result will be '_-_abc'
+ * const result3 = padStart('abc', 3);          // result will be 'abc'
+ * const result4 = padStart('abc', 2);          // result will be 'abc'
+ */
+declare function padStart(str: string, length?: number, chars?: string): string;
+
+export { padStart };

package/dist/compat/string/padStart.mjs

@@ -0,0 +1,5 @@
+function padStart(str, length = 0, chars = ' ') {
+    return str.padStart(length, chars);
+}
+
+export { padStart };

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if a string contains another string at the beginning of the string.
+ *
+ * Checks if one string startsWith another string. Optional position parameter to start searching from a certain index.
+ *
+ * @param {string} str - The string that might contain the target string.
+ * @param {string} target - The string to search for.
+ * @param {number} position - An optional offset to start searching in the str string
+ * @returns {boolean} - True if the str string starts with the target string.
+ *
+ * @example
+ * const isPrefix = startsWith('fooBar', 'foo') // returns true
+ * const isPrefix = startsWith('fooBar', 'bar') // returns false
+ * const isPrefix = startsWith('fooBar', 'abc') // returns false
+ * const isPrefix = startsWith('fooBar', 'Bar', 2) // returns true
+ * const isPrefix = startsWith('fooBar', 'Bar', 5) // returns false
+ */
+declare const startsWith: (str: string, target: string, position?: number) => boolean;
+
+export { startsWith };

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

@@ -0,0 +1,20 @@
+/**
+ * Checks if a string contains another string at the beginning of the string.
+ *
+ * Checks if one string startsWith another string. Optional position parameter to start searching from a certain index.
+ *
+ * @param {string} str - The string that might contain the target string.
+ * @param {string} target - The string to search for.
+ * @param {number} position - An optional offset to start searching in the str string
+ * @returns {boolean} - True if the str string starts with the target string.
+ *
+ * @example
+ * const isPrefix = startsWith('fooBar', 'foo') // returns true
+ * const isPrefix = startsWith('fooBar', 'bar') // returns false
+ * const isPrefix = startsWith('fooBar', 'abc') // returns false
+ * const isPrefix = startsWith('fooBar', 'Bar', 2) // returns true
+ * const isPrefix = startsWith('fooBar', 'Bar', 5) // returns false
+ */
+declare const startsWith: (str: string, target: string, position?: number) => boolean;
+
+export { startsWith };

package/dist/compat/string/startsWith.mjs

@@ -0,0 +1,5 @@
+const startsWith = (str, target, position = 0) => {
+    return str.startsWith(target, position);
+};
+
+export { startsWith };

package/dist/error/AbortError.mjs

@@ -1,8 +1,8 @@
-import {
-  AbortError
-} from "../chunk-DXB7EZUQ.mjs";
-import "../chunk-24FKGR6U.mjs";
-export {
-  AbortError
-};
-//# sourceMappingURL=AbortError.mjs.map
+class AbortError extends Error {
+    constructor(message = 'The operation was aborted') {
+        super(message);
+        this.name = 'AbortError';
+    }
+}
+
+export { AbortError };

package/dist/error/TimeoutError.mjs

@@ -1,8 +1,8 @@
-import {
-  TimeoutError
-} from "../chunk-KIOYQRMQ.mjs";
-import "../chunk-24FKGR6U.mjs";
-export {
-  TimeoutError
-};
-//# sourceMappingURL=TimeoutError.mjs.map
+class TimeoutError extends Error {
+    constructor(message = 'The operation was timed out') {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+
+export { TimeoutError };

package/dist/function/after.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Creates a function that only executes starting from the `n`-th call.
+ * The provided function will be invoked starting from the `n`-th call.
+ *
+ * This is particularly useful for scenarios involving events or asynchronous operations
+ * where an action should occur only after a certain number of invocations.
+ *
+ * @template F - The type of the function to be invoked.
+ * @param {number} n - The number of calls required for `func` to execute.
+ * @param {F} func - The function to be invoked.
+ * @returns {F} - A new function that:
+ * - Tracks the number of calls.
+ * - Invokes `func` starting from the `n`-th call.
+ * - Returns `undefined` if fewer than `n` calls have been made.
+ * @throws {Error} - Throws an error if `n` is negative.
+ * @example
+ *
+ * const afterFn = after(3, () => {
+ *  console.log("called")
+ * });
+ *
+ * // Will not log anything.
+ * afterFn()
+ * // Will not log anything.
+ * afterFn()
+ * // Will log 'called'.
+ * afterFn()
+ */
+declare const after: <F extends (...args: any[]) => any>(n: number, func: F) => F;
+
+export { after };

package/dist/function/after.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Creates a function that only executes starting from the `n`-th call.
+ * The provided function will be invoked starting from the `n`-th call.
+ *
+ * This is particularly useful for scenarios involving events or asynchronous operations
+ * where an action should occur only after a certain number of invocations.
+ *
+ * @template F - The type of the function to be invoked.
+ * @param {number} n - The number of calls required for `func` to execute.
+ * @param {F} func - The function to be invoked.
+ * @returns {F} - A new function that:
+ * - Tracks the number of calls.
+ * - Invokes `func` starting from the `n`-th call.
+ * - Returns `undefined` if fewer than `n` calls have been made.
+ * @throws {Error} - Throws an error if `n` is negative.
+ * @example
+ *
+ * const afterFn = after(3, () => {
+ *  console.log("called")
+ * });
+ *
+ * // Will not log anything.
+ * afterFn()
+ * // Will not log anything.
+ * afterFn()
+ * // Will log 'called'.
+ * afterFn()
+ */
+declare const after: <F extends (...args: any[]) => any>(n: number, func: F) => F;
+
+export { after };

package/dist/function/after.mjs

@@ -0,0 +1,14 @@
+const after = (n, func) => {
+    if (!Number.isInteger(n) || n < 0) {
+        throw new Error(`n must be a non-negative integer.`);
+    }
+    let counter = 0;
+    return ((...args) => {
+        if (++counter >= n) {
+            return func(...args);
+        }
+        return undefined;
+    });
+};
+
+export { after };

package/dist/function/ary.d.mts

@@ -0,0 +1,12 @@
+/**
+ * Creates a function that invokes func, with up to n arguments, ignoring any additional arguments.
+ *
+ * @template F - The type of the function.
+ * @param {F} func - The function to cap arguments for.
+ * @param {number} n - The arity cap.
+ * @param {any} guard - Enables use as an iteratee for methods like `map`.
+ * @returns {(...args: any[]) => ReturnType<F>} Returns the new capped function.
+ */
+declare function ary<F extends (...args: any[]) => any>(func: F, n: number): ((...args: any[]) => ReturnType<F>);
+
+export { ary };

package/dist/function/ary.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Creates a function that invokes func, with up to n arguments, ignoring any additional arguments.
+ *
+ * @template F - The type of the function.
+ * @param {F} func - The function to cap arguments for.
+ * @param {number} n - The arity cap.
+ * @param {any} guard - Enables use as an iteratee for methods like `map`.
+ * @returns {(...args: any[]) => ReturnType<F>} Returns the new capped function.
+ */
+declare function ary<F extends (...args: any[]) => any>(func: F, n: number): ((...args: any[]) => ReturnType<F>);
+
+export { ary };

package/dist/function/ary.mjs

@@ -0,0 +1,7 @@
+function ary(func, n) {
+    return function (...args) {
+        return func.apply(this, args.slice(0, n));
+    };
+}
+
+export { ary };

package/dist/function/before.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Creates a function that limits the number of times the given function (`func`) can be called.
+ *
+ * @template F - The type of the function to be invoked.
+ * @param {number} n - The number of times the returned function is allowed to call `func` before stopping.
+ * - If `n` is 0, `func` will never be called.
+ * - If `n` is a positive integer, `func` will be called up to `n-1` times.
+ * @param {F} func - The function to be called with the limit applied.
+ * @returns {F} - A new function that:
+ * - Tracks the number of calls.
+ * - Invokes `func` until the `n-1`-th call.
+ * - Returns `undefined` if the number of calls reaches or exceeds `n`, stopping further calls.
+ * @throws {Error} - Throw an error if `n` is negative.
+ * @example
+ *
+ * const beforeFn = before(3, () => {
+ *  console.log("called");
+ * })
+ *
+ * // Will log 'called'.
+ * beforeFn();
+ *
+ * // Will log 'called'.
+ * beforeFn();
+ *
+ * // Will not log anything.
+ * beforeFn();
+ */
+declare const before: <F extends (...args: any[]) => any>(n: number, func: F) => F;
+
+export { before };

package/dist/function/before.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Creates a function that limits the number of times the given function (`func`) can be called.
+ *
+ * @template F - The type of the function to be invoked.
+ * @param {number} n - The number of times the returned function is allowed to call `func` before stopping.
+ * - If `n` is 0, `func` will never be called.
+ * - If `n` is a positive integer, `func` will be called up to `n-1` times.
+ * @param {F} func - The function to be called with the limit applied.
+ * @returns {F} - A new function that:
+ * - Tracks the number of calls.
+ * - Invokes `func` until the `n-1`-th call.
+ * - Returns `undefined` if the number of calls reaches or exceeds `n`, stopping further calls.
+ * @throws {Error} - Throw an error if `n` is negative.
+ * @example
+ *
+ * const beforeFn = before(3, () => {
+ *  console.log("called");
+ * })
+ *
+ * // Will log 'called'.
+ * beforeFn();
+ *
+ * // Will log 'called'.
+ * beforeFn();
+ *
+ * // Will not log anything.
+ * beforeFn();
+ */
+declare const before: <F extends (...args: any[]) => any>(n: number, func: F) => F;
+
+export { before };

package/dist/function/before.mjs

@@ -0,0 +1,14 @@
+const before = (n, func) => {
+    if (!Number.isInteger(n) || n < 0) {
+        throw new Error('n must be a non-negative integer.');
+    }
+    let counter = 0;
+    return ((...args) => {
+        if (++counter < n) {
+            return func(...args);
+        }
+        return undefined;
+    });
+};
+
+export { before };

package/dist/function/debounce.mjs

@@ -1,8 +1,28 @@
-import {
-  debounce
-} from "../chunk-3IP4JVLL.mjs";
-import "../chunk-24FKGR6U.mjs";
-export {
-  debounce
-};
-//# sourceMappingURL=debounce.mjs.map
+function debounce(func, debounceMs, { signal } = {}) {
+    let timeoutId = null;
+    const debounced = function (...args) {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+        if (signal?.aborted) {
+            return;
+        }
+        timeoutId = setTimeout(() => {
+            func(...args);
+            timeoutId = null;
+        }, debounceMs);
+    };
+    const onAbort = function () {
+        debounced.cancel();
+    };
+    debounced.cancel = function () {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+        }
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    return debounced;
+}
+
+export { debounce };

package/dist/function/index.d.mts

@@ -1,5 +1,9 @@
+export { before } from './before.mjs';
+export { after } from './after.mjs';
 export { debounce } from './debounce.mjs';
 export { noop } from './noop.mjs';
 export { once } from './once.mjs';
 export { throttle } from './throttle.mjs';
 export { negate } from './negate.mjs';
+export { ary } from './ary.mjs';
+export { unary } from './unary.mjs';

package/dist/function/index.d.ts

@@ -1,5 +1,9 @@
+export { before } from './before.js';
+export { after } from './after.js';
 export { debounce } from './debounce.js';
 export { noop } from './noop.js';
 export { once } from './once.js';
 export { throttle } from './throttle.js';
 export { negate } from './negate.js';
+export { ary } from './ary.js';
+export { unary } from './unary.js';