es-toolkit 1.19.0 → 1.20.0-dev.625

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

@@ -13,6 +13,6 @@
  * const convertedStr3 = camelCase('hyphen-text') // returns 'hyphenText'
  * const convertedStr4 = camelCase('HTTPRequest') // returns 'httpRequest'
  */
-declare function camelCase(str: string | object): string;
+declare function camelCase(str?: string | object): string;
 
 export { camelCase };

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

@@ -3,7 +3,7 @@
  *
  * 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.
+ * @param {string | object} str - The string that is to be changed to kebab case.
  * @returns {string} - The converted string to kebab case.
  *
  * @example
@@ -12,6 +12,6 @@
  * const convertedStr3 = kebabCase('hyphen-text') // returns 'hyphen-text'
  * const convertedStr4 = kebabCase('HTTPRequest') // returns 'http-request'
  */
-declare function kebabCase(str: string | object): string;
+declare function kebabCase(str?: string | object): string;
 
 export { kebabCase };

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

@@ -3,7 +3,7 @@
  *
  * 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.
+ * @param {string | object} str - The string that is to be changed to kebab case.
  * @returns {string} - The converted string to kebab case.
  *
  * @example
@@ -12,6 +12,6 @@
  * const convertedStr3 = kebabCase('hyphen-text') // returns 'hyphen-text'
  * const convertedStr4 = kebabCase('HTTPRequest') // returns 'http-request'
  */
-declare function kebabCase(str: string | object): string;
+declare function kebabCase(str?: string | object): string;
 
 export { kebabCase };

package/dist/compat/string/kebabCase.mjs

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

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

@@ -3,7 +3,7 @@
  *
  * 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.
+ * @param {string | object} str - The string that is to be changed to lower case.
  * @returns {string} - The converted string to lower case.
  *
  * @example
@@ -12,6 +12,6 @@
  * const convertedStr3 = lowerCase('hyphen-text') // returns 'hyphen text'
  * const convertedStr4 = lowerCase('HTTPRequest') // returns 'http request'
  */
-declare function lowerCase(str: string | object): string;
+declare function lowerCase(str?: string | object): string;
 
 export { lowerCase };

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

@@ -3,7 +3,7 @@
  *
  * 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.
+ * @param {string | object} str - The string that is to be changed to lower case.
  * @returns {string} - The converted string to lower case.
  *
  * @example
@@ -12,6 +12,6 @@
  * const convertedStr3 = lowerCase('hyphen-text') // returns 'hyphen text'
  * const convertedStr4 = lowerCase('HTTPRequest') // returns 'http request'
  */
-declare function lowerCase(str: string | object): string;
+declare function lowerCase(str?: string | object): string;
 
 export { lowerCase };

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

@@ -3,7 +3,7 @@
  *
  * 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.
+ * @param {string | object} str - The string that is to be changed to snake case.
  * @returns {string} - The converted string to snake case.
  *
  * @example
@@ -12,6 +12,6 @@
  * const convertedStr3 = snakeCase('hyphen-text') // returns 'hyphen_text'
  * const convertedStr4 = snakeCase('HTTPRequest') // returns 'http_request'
  */
-declare function snakeCase(str: string | object): string;
+declare function snakeCase(str?: string | object): string;
 
 export { snakeCase };

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

@@ -3,7 +3,7 @@
  *
  * 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.
+ * @param {string | object} str - The string that is to be changed to snake case.
  * @returns {string} - The converted string to snake case.
  *
  * @example
@@ -12,6 +12,6 @@
  * const convertedStr3 = snakeCase('hyphen-text') // returns 'hyphen_text'
  * const convertedStr4 = snakeCase('HTTPRequest') // returns 'http_request'
  */
-declare function snakeCase(str: string | object): string;
+declare function snakeCase(str?: string | object): string;
 
 export { snakeCase };

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

@@ -2,7 +2,7 @@
  * Converts the first character of each word in a string to uppercase and the remaining characters to lowercase.
  *
  * Start case is the naming convention in which each word is written with an initial capital letter.
- * @param {string} str - The string to convert.
+ * @param {string | object} str - The string to convert.
  * @returns {string} The converted string.
  *
  * @example
@@ -11,6 +11,6 @@
  * const result3 = startCase('hello-world');  // result will be 'Hello World'
  * const result4 = startCase('hello_world');  // result will be 'Hello World'
  */
-declare function startCase(str: string | object): string;
+declare function startCase(str?: string | object): string;
 
 export { startCase };

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

@@ -2,7 +2,7 @@
  * Converts the first character of each word in a string to uppercase and the remaining characters to lowercase.
  *
  * Start case is the naming convention in which each word is written with an initial capital letter.
- * @param {string} str - The string to convert.
+ * @param {string | object} str - The string to convert.
  * @returns {string} The converted string.
  *
  * @example
@@ -11,6 +11,6 @@
  * const result3 = startCase('hello-world');  // result will be 'Hello World'
  * const result4 = startCase('hello_world');  // result will be 'Hello World'
  */
-declare function startCase(str: string | object): string;
+declare function startCase(str?: string | object): string;
 
 export { startCase };

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

@@ -3,7 +3,6 @@
  *
  * @param {string} str - The string from which leading and trailing characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified leading and trailing characters have been removed.
  *
  * @example

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

@@ -3,7 +3,6 @@
  *
  * @param {string} str - The string from which leading and trailing characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified leading and trailing characters have been removed.
  *
  * @example

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

@@ -3,7 +3,6 @@
  *
  * @param {string} str - The string from which trailing characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified trailing character has been removed.
  *
  * @example

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

@@ -3,7 +3,6 @@
  *
  * @param {string} str - The string from which trailing characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified trailing character has been removed.
  *
  * @example

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

@@ -3,7 +3,6 @@
  *
  * @param {string} str - The string from which leading characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified leading character has been removed.
  *
  * @example

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

@@ -3,7 +3,6 @@
  *
  * @param {string} str - The string from which leading characters will be trimmed.
  * @param {string | string[]} chars - The character(s) to remove from the end of the string. Defaults to `" "`.
- * @param guard
  * @returns {string} - The resulting string after the specified leading character has been removed.
  *
  * @example

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

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to upper case.
+ *
+ * Upper case is the naming convention in which each word is written in uppercase and separated by an space ( ) character.
+ *
+ * @param {string | object} str - The string that is to be changed to upper case.
+ * @returns {string} - The converted string to upper case.
+ *
+ * @example
+ * const convertedStr1 = upperCase('camelCase') // returns 'CAMEL CASE'
+ * const convertedStr2 = upperCase('some whitespace') // returns 'SOME WHITESPACE'
+ * const convertedStr3 = upperCase('hyphen-text') // returns 'HYPHEN TEXT'
+ * const convertedStr4 = upperCase('HTTPRequest') // returns 'HTTP REQUEST'
+ */
+declare function upperCase(str?: string | object): string;
+
+export { upperCase };

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

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to upper case.
+ *
+ * Upper case is the naming convention in which each word is written in uppercase and separated by an space ( ) character.
+ *
+ * @param {string | object} str - The string that is to be changed to upper case.
+ * @returns {string} - The converted string to upper case.
+ *
+ * @example
+ * const convertedStr1 = upperCase('camelCase') // returns 'CAMEL CASE'
+ * const convertedStr2 = upperCase('some whitespace') // returns 'SOME WHITESPACE'
+ * const convertedStr3 = upperCase('hyphen-text') // returns 'HYPHEN TEXT'
+ * const convertedStr4 = upperCase('HTTPRequest') // returns 'HTTP REQUEST'
+ */
+declare function upperCase(str?: string | object): string;
+
+export { upperCase };

package/dist/compat/string/upperCase.mjs

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

package/dist/function/debounce.d.mts

@@ -1,5 +1,16 @@
 interface DebounceOptions {
+    /**
+     * An optional AbortSignal to cancel the debounced function.
+     */
     signal?: AbortSignal;
+    /**
+     * An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
+     * If `edges` includes "leading", the function will be invoked at the start of the delay period.
+     * If `edges` includes "trailing", the function will be invoked at the end of the delay period.
+     * If both "leading" and "trailing" are included, the function will be invoked at both the start and end of the delay period.
+     * @default ["trailing"]
+     */
+    edges?: Array<'leading' | 'trailing'>;
 }
 /**
  * Creates a debounced function that delays invoking the provided function until after `debounceMs` milliseconds
@@ -36,8 +47,26 @@ interface DebounceOptions {
  * // Will cancel the debounced function call
  * controller.abort();
  */
-declare function debounce<F extends (...args: any[]) => void>(func: F, debounceMs: number, { signal }?: DebounceOptions): ((...args: Parameters<F>) => void) & {
+declare function debounce<F extends (...args: any[]) => void>(func: F, debounceMs: number, { signal, edges }?: DebounceOptions): ((...args: Parameters<F>) => void) & {
+    /**
+     * Schedules the execution of the debounced function after the specified debounce delay.
+     * This method resets any existing timer, ensuring that the function is only invoked
+     * after the delay has elapsed since the last call to the debounced function.
+     * It is typically called internally whenever the debounced function is invoked.
+     *
+     * @returns {void}
+     */
+    schedule: () => void;
+    /**
+     * Cancels any pending execution of the debounced function.
+     * This method clears the active timer and resets any stored context or arguments.
+     */
     cancel: () => void;
+    /**
+     * Immediately invokes the debounced function if there is a pending execution.
+     * This method also cancels the current timer, ensuring that the function executes right away.
+     */
+    flush: () => void;
 };
 
 export { debounce };

package/dist/function/debounce.d.ts

@@ -1,5 +1,16 @@
 interface DebounceOptions {
+    /**
+     * An optional AbortSignal to cancel the debounced function.
+     */
     signal?: AbortSignal;
+    /**
+     * An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
+     * If `edges` includes "leading", the function will be invoked at the start of the delay period.
+     * If `edges` includes "trailing", the function will be invoked at the end of the delay period.
+     * If both "leading" and "trailing" are included, the function will be invoked at both the start and end of the delay period.
+     * @default ["trailing"]
+     */
+    edges?: Array<'leading' | 'trailing'>;
 }
 /**
  * Creates a debounced function that delays invoking the provided function until after `debounceMs` milliseconds
@@ -36,8 +47,26 @@ interface DebounceOptions {
  * // Will cancel the debounced function call
  * controller.abort();
  */
-declare function debounce<F extends (...args: any[]) => void>(func: F, debounceMs: number, { signal }?: DebounceOptions): ((...args: Parameters<F>) => void) & {
+declare function debounce<F extends (...args: any[]) => void>(func: F, debounceMs: number, { signal, edges }?: DebounceOptions): ((...args: Parameters<F>) => void) & {
+    /**
+     * Schedules the execution of the debounced function after the specified debounce delay.
+     * This method resets any existing timer, ensuring that the function is only invoked
+     * after the delay has elapsed since the last call to the debounced function.
+     * It is typically called internally whenever the debounced function is invoked.
+     *
+     * @returns {void}
+     */
+    schedule: () => void;
+    /**
+     * Cancels any pending execution of the debounced function.
+     * This method clears the active timer and resets any stored context or arguments.
+     */
     cancel: () => void;
+    /**
+     * Immediately invokes the debounced function if there is a pending execution.
+     * This method also cancels the current timer, ensuring that the function executes right away.
+     */
+    flush: () => void;
 };
 
 export { debounce };

package/dist/function/debounce.mjs

@@ -1,27 +1,62 @@
-function debounce(func, debounceMs, { signal } = {}) {
+function debounce(func, debounceMs, { signal, edges } = {}) {
+    let pendingThis = undefined;
+    let pendingArgs = null;
+    const leading = edges != null && edges.includes('leading');
+    const trailing = edges == null || edges.includes('trailing');
+    const invoke = () => {
+        if (pendingArgs !== null) {
+            func.apply(pendingThis, pendingArgs);
+            pendingThis = undefined;
+            pendingArgs = null;
+        }
+    };
+    const onTimerEnd = () => {
+        if (trailing) {
+            invoke();
+        }
+        cancel();
+    };
     let timeoutId = null;
-    const debounced = function (...args) {
-        if (timeoutId !== null) {
+    const schedule = () => {
+        if (timeoutId != null) {
             clearTimeout(timeoutId);
         }
-        if (signal?.aborted) {
-            return;
-        }
         timeoutId = setTimeout(() => {
-            func(...args);
             timeoutId = null;
+            onTimerEnd();
         }, debounceMs);
     };
-    const onAbort = function () {
-        debounced.cancel();
-    };
-    debounced.cancel = function () {
+    const cancelTimer = () => {
         if (timeoutId !== null) {
             clearTimeout(timeoutId);
             timeoutId = null;
         }
     };
-    signal?.addEventListener('abort', onAbort, { once: true });
+    const cancel = () => {
+        cancelTimer();
+        pendingThis = undefined;
+        pendingArgs = null;
+    };
+    const flush = () => {
+        cancelTimer();
+        invoke();
+    };
+    const debounced = function (...args) {
+        if (signal?.aborted) {
+            return;
+        }
+        pendingThis = this;
+        pendingArgs = args;
+        const isFirstCall = timeoutId == null;
+        schedule();
+        if (leading && isFirstCall) {
+            invoke();
+        }
+    };
+    debounced.schedule = schedule;
+    debounced.cancel = cancel;
+    debounced.flush = flush;
+    signal?.addEventListener('abort', cancel, { once: true });
     return debounced;
 }
 

package/dist/function/index.js

@@ -2,7 +2,47 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const curry = require('../_chunk/curry-BmwJrK.js');
+const rest = require('../_chunk/rest-pUyjvl.js');
+
+function throttle(func, throttleMs, { signal, edges = ['leading', 'trailing'] } = {}) {
+    let pendingAt = null;
+    const debounced = rest.debounce(func, throttleMs, { signal, edges });
+    const throttled = function (...args) {
+        if (pendingAt == null) {
+            pendingAt = Date.now();
+        }
+        else {
+            if (Date.now() - pendingAt >= throttleMs) {
+                debounced.cancel();
+                debounced(...args);
+            }
+        }
+        debounced(...args);
+    };
+    throttled.cancel = debounced.cancel;
+    throttled.flush = debounced.flush;
+    return throttled;
+}
+
+function curry(func) {
+    if (func.length === 0 || func.length === 1) {
+        return func;
+    }
+    return function (arg) {
+        return makeCurry(func, func.length, [arg]);
+    };
+}
+function makeCurry(origin, argsLength, args) {
+    if (args.length === argsLength) {
+        return origin(...args);
+    }
+    else {
+        const next = function (arg) {
+            return makeCurry(origin, argsLength, [...args, arg]);
+        };
+        return next;
+    }
+}
 
 function spread(func) {
     return function (argsArr) {
@@ -10,18 +50,18 @@ function spread(func) {
     };
 }
 
-exports.after = curry.after;
-exports.ary = curry.ary;
-exports.before = curry.before;
-exports.curry = curry.curry;
-exports.debounce = curry.debounce;
-exports.memoize = curry.memoize;
-exports.negate = curry.negate;
-exports.noop = curry.noop;
-exports.once = curry.once;
-exports.partial = curry.partial;
-exports.partialRight = curry.partialRight;
-exports.rest = curry.rest;
-exports.throttle = curry.throttle;
-exports.unary = curry.unary;
+exports.after = rest.after;
+exports.ary = rest.ary;
+exports.before = rest.before;
+exports.debounce = rest.debounce;
+exports.memoize = rest.memoize;
+exports.negate = rest.negate;
+exports.noop = rest.noop;
+exports.once = rest.once;
+exports.partial = rest.partial;
+exports.partialRight = rest.partialRight;
+exports.rest = rest.rest;
+exports.unary = rest.unary;
+exports.curry = curry;
 exports.spread = spread;
+exports.throttle = throttle;

package/dist/function/throttle.d.mts

@@ -1,3 +1,17 @@
+interface ThrottleOptions {
+    /**
+     * An optional AbortSignal to cancel the debounced function.
+     */
+    signal?: AbortSignal;
+    /**
+     * An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
+     * If `edges` includes "leading", the function will be invoked at the start of the delay period.
+     * If `edges` includes "trailing", the function will be invoked at the end of the delay period.
+     * If both "leading" and "trailing" are included, the function will be invoked at both the start and end of the delay period.
+     * @default ["leading", "trailing"]
+     */
+    edges?: Array<'leading' | 'trailing'>;
+}
 /**
  * Creates a throttled function that only invokes the provided function at most once
  * per every `throttleMs` milliseconds. Subsequent calls to the throttled function
@@ -24,6 +38,9 @@
  *   throttledFunction(); // Will log 'Function executed'
  * }, 1000);
  */
-declare function throttle<F extends (...args: any[]) => void>(func: F, throttleMs: number): (...args: Parameters<F>) => void;
+declare function throttle<F extends (...args: any[]) => void>(func: F, throttleMs: number, { signal, edges }?: ThrottleOptions): ((...args: Parameters<F>) => void) & {
+    cancel: () => void;
+    flush: () => void;
+};
 
 export { throttle };

package/dist/function/throttle.d.ts

@@ -1,3 +1,17 @@
+interface ThrottleOptions {
+    /**
+     * An optional AbortSignal to cancel the debounced function.
+     */
+    signal?: AbortSignal;
+    /**
+     * An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
+     * If `edges` includes "leading", the function will be invoked at the start of the delay period.
+     * If `edges` includes "trailing", the function will be invoked at the end of the delay period.
+     * If both "leading" and "trailing" are included, the function will be invoked at both the start and end of the delay period.
+     * @default ["leading", "trailing"]
+     */
+    edges?: Array<'leading' | 'trailing'>;
+}
 /**
  * Creates a throttled function that only invokes the provided function at most once
  * per every `throttleMs` milliseconds. Subsequent calls to the throttled function
@@ -24,6 +38,9 @@
  *   throttledFunction(); // Will log 'Function executed'
  * }, 1000);
  */
-declare function throttle<F extends (...args: any[]) => void>(func: F, throttleMs: number): (...args: Parameters<F>) => void;
+declare function throttle<F extends (...args: any[]) => void>(func: F, throttleMs: number, { signal, edges }?: ThrottleOptions): ((...args: Parameters<F>) => void) & {
+    cancel: () => void;
+    flush: () => void;
+};
 
 export { throttle };

package/dist/function/throttle.mjs

@@ -1,13 +1,23 @@
-function throttle(func, throttleMs) {
-    let lastCallTime;
-    const throttledFunction = function (...args) {
-        const now = Date.now();
-        if (lastCallTime == null || now - lastCallTime >= throttleMs) {
-            lastCallTime = now;
-            func(...args);
+import { debounce } from './debounce.mjs';
+
+function throttle(func, throttleMs, { signal, edges = ['leading', 'trailing'] } = {}) {
+    let pendingAt = null;
+    const debounced = debounce(func, throttleMs, { signal, edges });
+    const throttled = function (...args) {
+        if (pendingAt == null) {
+            pendingAt = Date.now();
+        }
+        else {
+            if (Date.now() - pendingAt >= throttleMs) {
+                debounced.cancel();
+                debounced(...args);
+            }
         }
+        debounced(...args);
     };
-    return throttledFunction;
+    throttled.cancel = debounced.cancel;
+    throttled.flush = debounced.flush;
+    return throttled;
 }
 
 export { throttle };