@sohanemon/utils 4.0.33 → 4.1.0

package/dist/functions/index.d.ts

@@ -80,21 +80,77 @@ export declare const svgToBase64: (str: string) => string;
  * @returns - A Promise that resolves after the specified time
  */
 export declare const sleep: (time?: number) => Promise<unknown>;
+type DebouncedFunction<F extends (...args: any[]) => any> = {
+    (...args: Parameters<F>): ReturnType<F> | undefined;
+    readonly isPending: boolean;
+};
 /**
  * Creates a debounced function that delays invoking the provided function until
- * after the specified wait time has elapsed since the last invocation.
+ * after the specified `wait` time has elapsed since the last invocation.
  *
- * @param func - The function to debounce
- * @param wait - The number of milliseconds to delay (default is 1000ms)
- * @returns - A debounced version of the function
+ * If the `immediate` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the wait interval. Subsequent calls during the wait interval
+ * will reset the timer but not invoke the function until the interval elapses again.
+ *
+ * The returned function includes the `isPending` property to check if the debounce
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to debounce.
+ *
+ * @param function_ - The function to debounce.
+ * @param wait - The number of milliseconds to delay (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `immediate` (boolean): If `true`, invokes the function on the leading edge
+ *     of the wait interval instead of the trailing edge.
+ *
+ * @returns A debounced version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
+ *
+ * @example
+ * const log = debounce((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" after 200ms if no other call is made.
+ * console.log(log.isPending); // true if the timer is active.
  */
-export declare function debounce<T extends (...args: any[]) => void>(func: T, wait?: number): (...args: Parameters<T>) => void;
+export declare function debounce<F extends (...args: any[]) => any>(function_: F, wait?: number, options?: {
+    immediate: boolean;
+}): DebouncedFunction<F>;
+type ThrottledFunction<F extends (...args: any[]) => any> = {
+    (...args: Parameters<F>): ReturnType<F> | undefined;
+    readonly isPending: boolean;
+};
 /**
  * Creates a throttled function that invokes the provided function at most once
- * every specified wait time.
+ * every `wait` milliseconds.
+ *
+ * If the `leading` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
+ * the function will also be invoked at the end of the throttle interval if additional
+ * calls were made during the interval.
+ *
+ * The returned function includes the `isPending` property to check if the throttle
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to throttle.
+ *
+ * @param function_ - The function to throttle.
+ * @param wait - The number of milliseconds to wait between invocations (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
+ *   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
+ *
+ * @returns A throttled version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
  *
- * @param func - The function to throttle
- * @param wait - The number of milliseconds to wait (default is 1000ms)
- * @returns - A throttled version of the function
+ * @example
+ * const log = throttle((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" immediately if leading is true.
+ * console.log(log.isPending); // true if the timer is active.
  */
-export declare function throttle<T extends (...args: any[]) => void>(func: T, wait?: number): (...args: Parameters<T>) => void;
+export declare function throttle<F extends (...args: any[]) => any>(function_: F, wait?: number, options?: {
+    leading?: boolean;
+    trailing?: boolean;
+}): ThrottledFunction<F>;

package/dist/functions/index.js

@@ -131,36 +131,150 @@ export const svgToBase64 = (str) => isSSR ? Buffer.from(str).toString('base64')
 export const sleep = (time = 1000) => new Promise((resolve) => setTimeout(resolve, time));
 /**
  * Creates a debounced function that delays invoking the provided function until
- * after the specified wait time has elapsed since the last invocation.
+ * after the specified `wait` time has elapsed since the last invocation.
  *
- * @param func - The function to debounce
- * @param wait - The number of milliseconds to delay (default is 1000ms)
- * @returns - A debounced version of the function
+ * If the `immediate` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the wait interval. Subsequent calls during the wait interval
+ * will reset the timer but not invoke the function until the interval elapses again.
+ *
+ * The returned function includes the `isPending` property to check if the debounce
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to debounce.
+ *
+ * @param function_ - The function to debounce.
+ * @param wait - The number of milliseconds to delay (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `immediate` (boolean): If `true`, invokes the function on the leading edge
+ *     of the wait interval instead of the trailing edge.
+ *
+ * @returns A debounced version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
+ *
+ * @example
+ * const log = debounce((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" after 200ms if no other call is made.
+ * console.log(log.isPending); // true if the timer is active.
  */
-export function debounce(func, wait = 1000) {
-    let timeout;
-    return function (...args) {
-        clearTimeout(timeout);
-        timeout = setTimeout(() => func.apply(this, args), wait);
+export function debounce(function_, wait = 100, options) {
+    if (typeof function_ !== 'function') {
+        throw new TypeError(`Expected the first parameter to be a function, got \`${typeof function_}\`.`);
+    }
+    if (wait < 0) {
+        throw new RangeError('`wait` must not be negative.');
+    }
+    const immediate = options?.immediate ?? false;
+    let timeoutId;
+    let lastArgs;
+    let lastContext;
+    let result;
+    function run() {
+        result = function_.apply(lastContext, lastArgs);
+        lastArgs = undefined;
+        lastContext = undefined;
+        return result;
+    }
+    const debounced = function (...args) {
+        lastArgs = args;
+        lastContext = this;
+        if (timeoutId === undefined && immediate) {
+            result = run.call(this);
+        }
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(run.bind(this), wait);
+        return result;
     };
+    Object.defineProperty(debounced, 'isPending', {
+        get() {
+            return timeoutId !== undefined;
+        },
+    });
+    return debounced;
 }
 /**
  * Creates a throttled function that invokes the provided function at most once
- * every specified wait time.
+ * every `wait` milliseconds.
+ *
+ * If the `leading` option is set to `true`, the function will be invoked immediately
+ * on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
+ * the function will also be invoked at the end of the throttle interval if additional
+ * calls were made during the interval.
  *
- * @param func - The function to throttle
- * @param wait - The number of milliseconds to wait (default is 1000ms)
- * @returns - A throttled version of the function
+ * The returned function includes the `isPending` property to check if the throttle
+ * timer is currently active.
+ *
+ * @typeParam F - The type of the function to throttle.
+ *
+ * @param function_ - The function to throttle.
+ * @param wait - The number of milliseconds to wait between invocations (default is 100ms).
+ * @param options - An optional object with the following properties:
+ *   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
+ *   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
+ *
+ * @returns A throttled version of the provided function, enhanced with the `isPending` property.
+ *
+ * @throws {TypeError} If the first parameter is not a function.
+ * @throws {RangeError} If the `wait` parameter is negative.
+ *
+ * @example
+ * const log = throttle((message: string) => console.log(message), 200);
+ * log('Hello'); // Logs "Hello" immediately if leading is true.
+ * console.log(log.isPending); // true if the timer is active.
  */
-export function throttle(func, wait = 1000) {
-    let inThrottle = false;
-    return function (...args) {
-        if (!inThrottle) {
-            func.apply(this, args);
-            inThrottle = true;
-            setTimeout(() => {
-                inThrottle = false;
-            }, wait);
+export function throttle(function_, wait = 100, options) {
+    if (typeof function_ !== 'function') {
+        throw new TypeError(`Expected the first parameter to be a function, got \`${typeof function_}\`.`);
+    }
+    if (wait < 0) {
+        throw new RangeError('`wait` must not be negative.');
+    }
+    const leading = options?.leading ?? true;
+    const trailing = options?.trailing ?? true;
+    let timeoutId;
+    let lastArgs;
+    let lastContext;
+    let lastCallTime;
+    let result;
+    function invoke() {
+        lastCallTime = Date.now();
+        result = function_.apply(lastContext, lastArgs);
+        lastArgs = undefined;
+        lastContext = undefined;
+    }
+    function later() {
+        timeoutId = undefined;
+        if (trailing && lastArgs) {
+            invoke();
+        }
+    }
+    const throttled = function (...args) {
+        const now = Date.now();
+        const timeSinceLastCall = lastCallTime
+            ? now - lastCallTime
+            : Number.POSITIVE_INFINITY;
+        lastArgs = args;
+        lastContext = this;
+        if (timeSinceLastCall >= wait) {
+            if (leading) {
+                invoke();
+            }
+            else {
+                timeoutId = setTimeout(later, wait);
+            }
+        }
+        else if (!timeoutId && trailing) {
+            timeoutId = setTimeout(later, wait - timeSinceLastCall);
         }
+        return result;
     };
+    Object.defineProperty(throttled, 'isPending', {
+        get() {
+            return timeoutId !== undefined;
+        },
+    });
+    return throttled;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "4.0.33",
+  "version": "4.1.0",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",
@@ -15,19 +15,33 @@
   },
   "typesVersions": {
     "*": {
-      "core": ["dist/index.d.ts"],
-      "types": ["dist/types/index.d.ts"],
-      "hooks": ["dist/hooks/index.d.ts"],
-      "components": ["dist/components/index.d.ts"]
+      "core": [
+        "dist/index.d.ts"
+      ],
+      "types": [
+        "dist/types/index.d.ts"
+      ],
+      "hooks": [
+        "dist/hooks/index.d.ts"
+      ],
+      "components": [
+        "dist/components/index.d.ts"
+      ]
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc --watch",
     "export": "tsc && npm publish"
   },
-  "keywords": ["utils", "cn"],
+  "keywords": [
+    "utils",
+    "cn"
+  ],
   "license": "ISC",
   "devDependencies": {
     "@types/node": "^22.4.0",