@gumbee/utils 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -30,9 +30,11 @@ var __export = (target, all) => {
 // src/index.ts
 var exports_src = {};
 __export(exports_src, {
+  throttle: () => throttle,
   logWarn: () => logWarn,
   logError: () => logError,
   log: () => log,
+  debounce: () => debounce,
   clamp: () => clamp,
   Emitter: () => Emitter
 });
@@ -171,3 +173,85 @@ class Emitter {
     this.#events = {};
   }
 }
+// src/timing.ts
+function debounce(fn, delay) {
+  let timeoutId = null;
+  let latestArgs = null;
+  const debounced = (...args) => {
+    latestArgs = args;
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      if (latestArgs) {
+        fn(...latestArgs);
+        latestArgs = null;
+      }
+      timeoutId = null;
+    }, delay);
+  };
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    latestArgs = null;
+  };
+  debounced.flush = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+      if (latestArgs) {
+        fn(...latestArgs);
+        latestArgs = null;
+      }
+    }
+  };
+  return debounced;
+}
+function throttle(fn, delay) {
+  let timeoutId = null;
+  let lastExecTime = 0;
+  let latestArgs = null;
+  const throttled = (...args) => {
+    const now = Date.now();
+    latestArgs = args;
+    if (!lastExecTime && timeoutId === null) {
+      fn(...args);
+      lastExecTime = now;
+      latestArgs = null;
+    } else {
+      if (timeoutId === null) {
+        const remaining = delay - (now - lastExecTime);
+        timeoutId = setTimeout(() => {
+          if (latestArgs) {
+            fn(...latestArgs);
+            lastExecTime = Date.now();
+            latestArgs = null;
+          }
+          timeoutId = null;
+        }, Math.max(0, remaining));
+      }
+    }
+  };
+  throttled.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    lastExecTime = 0;
+    latestArgs = null;
+  };
+  throttled.flush = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    if (latestArgs) {
+      fn(...latestArgs);
+      lastExecTime = Date.now();
+      latestArgs = null;
+    }
+  };
+  return throttled;
+}

package/dist/index.d.cts

@@ -52,4 +52,41 @@ declare class Emitter<Events extends Record<string, any>> {
 	emit<K extends Exclude<keyof Events, KeysWithVoidPayload<Events>>>(event: K, args: Events[K]): void;
 	destroy(): void;
 }
-export { logWarn, logError, log, clamp, Emitter };
+/**
+* A function that can be cancelled or flushed.
+*/
+interface DebouncedFunction<T extends (...args: any[]) => void> {
+	(...args: Parameters<T>): void;
+	cancel(): void;
+	flush(): void;
+}
+/**
+* A function that can be cancelled or flushed.
+*/
+interface ThrottledFunction<T extends (...args: any[]) => void> {
+	(...args: Parameters<T>): void;
+	cancel(): void;
+	flush(): void;
+}
+/**
+* Creates a debounced function that delays invoking `fn` until after `delay` milliseconds
+* have elapsed since the last time the debounced function was invoked.
+*
+* The latest arguments provided to the debounced function are passed to `fn`.
+*
+* @param fn - The function to debounce
+* @param delay - The number of milliseconds to delay
+* @returns A debounced function with .cancel() and .flush() methods
+*/
+declare function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): DebouncedFunction<T>;
+/**
+* Creates a throttled function that only invokes `fn` at most once per every `delay` milliseconds.
+* The first call executes immediately. Subsequent calls are ignored until the delay passes,
+* but if calls were made during the delay, the latest one will execute at the end of the delay.
+*
+* @param fn - The function to throttle
+* @param delay - The number of milliseconds to throttle
+* @returns A throttled function with .cancel() and .flush() methods
+*/
+declare function throttle<T extends (...args: any[]) => void>(fn: T, delay: number): ThrottledFunction<T>;
+export { throttle, logWarn, logError, log, debounce, clamp, ThrottledFunction, Emitter, DebouncedFunction };

package/dist/index.d.ts

@@ -52,4 +52,41 @@ declare class Emitter<Events extends Record<string, any>> {
 	emit<K extends Exclude<keyof Events, KeysWithVoidPayload<Events>>>(event: K, args: Events[K]): void;
 	destroy(): void;
 }
-export { logWarn, logError, log, clamp, Emitter };
+/**
+* A function that can be cancelled or flushed.
+*/
+interface DebouncedFunction<T extends (...args: any[]) => void> {
+	(...args: Parameters<T>): void;
+	cancel(): void;
+	flush(): void;
+}
+/**
+* A function that can be cancelled or flushed.
+*/
+interface ThrottledFunction<T extends (...args: any[]) => void> {
+	(...args: Parameters<T>): void;
+	cancel(): void;
+	flush(): void;
+}
+/**
+* Creates a debounced function that delays invoking `fn` until after `delay` milliseconds
+* have elapsed since the last time the debounced function was invoked.
+*
+* The latest arguments provided to the debounced function are passed to `fn`.
+*
+* @param fn - The function to debounce
+* @param delay - The number of milliseconds to delay
+* @returns A debounced function with .cancel() and .flush() methods
+*/
+declare function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): DebouncedFunction<T>;
+/**
+* Creates a throttled function that only invokes `fn` at most once per every `delay` milliseconds.
+* The first call executes immediately. Subsequent calls are ignored until the delay passes,
+* but if calls were made during the delay, the latest one will execute at the end of the delay.
+*
+* @param fn - The function to throttle
+* @param delay - The number of milliseconds to throttle
+* @returns A throttled function with .cancel() and .flush() methods
+*/
+declare function throttle<T extends (...args: any[]) => void>(fn: T, delay: number): ThrottledFunction<T>;
+export { throttle, logWarn, logError, log, debounce, clamp, ThrottledFunction, Emitter, DebouncedFunction };

package/dist/index.js

@@ -131,10 +131,94 @@ class Emitter {
     this.#events = {};
   }
 }
+// src/timing.ts
+function debounce(fn, delay) {
+  let timeoutId = null;
+  let latestArgs = null;
+  const debounced = (...args) => {
+    latestArgs = args;
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      if (latestArgs) {
+        fn(...latestArgs);
+        latestArgs = null;
+      }
+      timeoutId = null;
+    }, delay);
+  };
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    latestArgs = null;
+  };
+  debounced.flush = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+      if (latestArgs) {
+        fn(...latestArgs);
+        latestArgs = null;
+      }
+    }
+  };
+  return debounced;
+}
+function throttle(fn, delay) {
+  let timeoutId = null;
+  let lastExecTime = 0;
+  let latestArgs = null;
+  const throttled = (...args) => {
+    const now = Date.now();
+    latestArgs = args;
+    if (!lastExecTime && timeoutId === null) {
+      fn(...args);
+      lastExecTime = now;
+      latestArgs = null;
+    } else {
+      if (timeoutId === null) {
+        const remaining = delay - (now - lastExecTime);
+        timeoutId = setTimeout(() => {
+          if (latestArgs) {
+            fn(...latestArgs);
+            lastExecTime = Date.now();
+            latestArgs = null;
+          }
+          timeoutId = null;
+        }, Math.max(0, remaining));
+      }
+    }
+  };
+  throttled.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    lastExecTime = 0;
+    latestArgs = null;
+  };
+  throttled.flush = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    if (latestArgs) {
+      fn(...latestArgs);
+      lastExecTime = Date.now();
+      latestArgs = null;
+    }
+  };
+  return throttled;
+}
 export {
+  throttle,
   logWarn,
   logError,
   log,
+  debounce,
   clamp,
   Emitter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gumbee/utils",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "Gumbee <mugeeb.hassan@gmail.com>",
   "repository": {
     "type": "git",