add performance utilities; implement debounce and throttle functions for improved function execution control

Author: dev-aditya-lab

src/index.ts

@@ -1,2 +1,3 @@
 export * from "./browser";
 export * from "./utils";
+export * from "./performance";

src/performance/debounce/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Debounce utility — delays function execution until after a pause.
+ * Useful for input events, search bars, resize listeners, etc.
+ */
+
+type DebouncedFunction<T extends (...args: any[]) => void> = (...args: Parameters<T>) => void;
+
+/**
+ * Creates a debounced version of the given function.
+ * @param fn - The function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns A debounced function
+ */
+export function debounce<T extends (...args: any[]) => void>(
+  fn: T,
+  delay: number
+): DebouncedFunction<T> {
+  if (typeof fn !== 'function') {
+    throw new TypeError('[webdev-power-kit][debounce] First argument must be a function.');
+  }
+
+  if (typeof delay !== 'number' || delay < 0) {
+    throw new TypeError('[webdev-power-kit][debounce] Delay must be a non-negative number.');
+  }
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  return function debouncedFn(...args: Parameters<T>) {
+    if (timer) clearTimeout(timer);
+
+    timer = setTimeout(() => {
+      try {
+        fn(...args);
+      } catch (err) {
+        console.error('[webdev-power-kit][debounce] Function threw an error:', err);
+      }
+    }, delay);
+  };
+}

src/performance/index.ts

@@ -0,0 +1,2 @@
+export * from "./debounce";
+export * from "./throttle";

src/performance/throttle/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Throttle utility — limits how often a function can run.
+ * Useful for scroll events, mouse moves, resize, etc.
+ */
+
+type ThrottledFunction<T extends (...args: any[]) => void> = (...args: Parameters<T>) => void;
+
+/**
+ * Creates a throttled version of the given function.
+ * @param fn - Function to throttle
+ * @param interval - Minimum time (in ms) between calls
+ * @returns A throttled function
+ */
+export function throttle<T extends (...args: any[]) => void>(
+  fn: T,
+  interval: number
+): ThrottledFunction<T> {
+  if (typeof fn !== 'function') {
+    throw new TypeError('[webdev-power-kit][throttle] First argument must be a function.');
+  }
+
+  if (typeof interval !== 'number' || interval < 0) {
+    throw new TypeError('[webdev-power-kit][throttle] Interval must be a non-negative number.');
+  }
+
+  let lastCalled = 0;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  return function throttledFn(...args: Parameters<T>) {
+    const now = Date.now();
+    const timeSinceLastCall = now - lastCalled;
+
+    if (timeSinceLastCall >= interval) {
+      lastCalled = now;
+      try {
+        fn(...args);
+      } catch (err) {
+        console.error('[webdev-power-kit][throttle] Function threw an error:', err);
+      }
+    } else if (!timeoutId) {
+      const timeRemaining = interval - timeSinceLastCall;
+      timeoutId = setTimeout(() => {
+        timeoutId = null;
+        lastCalled = Date.now();
+        try {
+          fn(...args);
+        } catch (err) {
+          console.error('[webdev-power-kit][throttle] Function threw an error:', err);
+        }
+      }, timeRemaining);
+    }
+  };
+}