feat: Add debounce utility

Author: hhvrc

src/lib/components/input/PasswordInput.svelte

@@ -7,7 +7,7 @@
   import { validatePassword } from '$lib/inputvalidation/passwordValidator';
   import type { AnyComponent } from '$lib/types/AnyComponent';
   import type { ValidationResult } from '$lib/types/ValidationResult';
-  import type { TimeoutHandle } from '$lib/types/WAPI';
+  import { debounce } from '$lib/utils/debounce';
   import type { Snippet } from 'svelte';
   import type { FullAutoFill } from 'svelte/elements';
   import PasswordStrengthMeter from './impl/PasswordStrengthMeter.svelte';
@@ -41,44 +41,32 @@
   }: Props = $props();
 
   let validationResult = $state<ValidationResult | null>(null);
-  let passwordDebounce: TimeoutHandle | undefined;
-  function checkHIBP(str: string) {
-    // Stop the previous debounce timer if it exists
-    clearTimeout(passwordDebounce);
-
-    // Set the validation result to the checking availability state
-    validationResult = { valid: false, message: 'Checking password...' };
-
-    // Start a new username request in 500ms
-    passwordDebounce = setTimeout(async () => {
-      // 500ms has passed, check if the password has been pwned
-      try {
-        // Make the API request
-        const pwnedCount = await checkPwnedCount(str);
-
-        // Map the response to a validation result
-        if (pwnedCount > 0) {
-          // Password has been pwned, change the validation result
-          validationResult = {
-            valid: false,
-            message: `Password detected in ${pwnedCount} data ${pwnedCount == 1 ? 'breach' : 'breaches'}`,
-            link: {
-              text: "What's this?",
-              href: 'https://haveibeenpwned.com/Passwords',
-            },
-          };
-        } else {
-          // Password is ok, return the successful validation result from the basic validation step
-          validationResult = { valid: true };
-        }
-      } catch (error) {
-        // Show an error toast
-        await handleApiError(error);
 
-        // We shouldnt block the user from submitting the form if the pwned password check fails
+  const requestHIBP = debounce(async (str: string) => {
+    try {
+      const pwnedCount = await checkPwnedCount(str);
+      if (pwnedCount > 0) {
+        validationResult = {
+          valid: false,
+          message: `Password detected in ${pwnedCount} data ${pwnedCount == 1 ? 'breach' : 'breaches'}`,
+          link: {
+            text: "What's this?",
+            href: 'https://haveibeenpwned.com/Passwords',
+          },
+        };
+      } else {
         validationResult = { valid: true };
       }
-    }, 500);
+    } catch (error) {
+      await handleApiError(error);
+      // Don't block submit if the pwned check fails
+      validationResult = { valid: true };
+    }
+  }, 500);
+
+  function checkHIBP(str: string) {
+    validationResult = { valid: false, message: 'Checking password...' };
+    requestHIBP(str);
   }
 
   $effect(() => {

src/lib/components/input/UsernameInput.svelte

@@ -11,7 +11,7 @@
   } from '$lib/inputvalidation/usernameValidator';
   import type { AnyComponent } from '$lib/types/AnyComponent';
   import type { ValidationResult } from '$lib/types/ValidationResult';
-  import type { TimeoutHandle } from '$lib/types/WAPI';
+  import { debounce } from '$lib/utils/debounce';
   import type { Snippet } from 'svelte';
   import type { FullAutoFill } from 'svelte/elements';
 
@@ -39,51 +39,40 @@
 
   let checkResponses = $state<Map<string, ValidationResult>>(new Map());
   let validationResult = $state<ValidationResult | null>(null);
-  let usernameDebounce: TimeoutHandle | undefined;
-  function checkUsernameAvailability(username: string) {
-    // Stop the previous debounce timer if it exists
-    clearTimeout(usernameDebounce);
 
+  const requestAvailability = debounce(async (username: string) => {
+    try {
+      const response = await accountV2Api.accountCheckUsername({ username });
+      validationResult = mapUsernameCheckResponse(response);
+      checkResponses.set(username, validationResult);
+    } catch (error) {
+      await handleApiError(error, (err) => {
+        if (!isValidationError(err)) {
+          validationResult = UsernameInternalServerErrorValRes;
+          return false;
+        }
+
+        const apiValRes = mapToValRes(err, 'Username');
+        if (apiValRes !== null) {
+          validationResult = apiValRes;
+          return true;
+        }
+
+        return false;
+      });
+    }
+  }, 250);
+
+  function checkUsernameAvailability(username: string) {
     const entry = checkResponses.get(username);
     if (entry !== undefined) {
+      requestAvailability.cancel();
       validationResult = entry;
-      usernameDebounce = undefined;
       return;
     }
 
-    // Set the validation result to the checking availability state
     validationResult = UsernameCheckingAvailabilityValRes;
-
-    // Start a new username request in 250ms
-    usernameDebounce = setTimeout(async () => {
-      // 250ms has passed, check if the username is available
-      try {
-        // Make the API request
-        const response = await accountV2Api.accountCheckUsername({ username });
-
-        // Map the response to a validation result
-        validationResult = mapUsernameCheckResponse(response);
-
-        checkResponses.set(username, validationResult);
-      } catch (error) {
-        // Show an error toast
-        await handleApiError(error, (err) => {
-          if (!isValidationError(err)) {
-            // Set the validation result to the internal server error state
-            validationResult = UsernameInternalServerErrorValRes;
-            return false;
-          }
-
-          const apiValRes = mapToValRes(err, 'Username');
-          if (apiValRes !== null) {
-            validationResult = apiValRes;
-            return true;
-          }
-
-          return false;
-        });
-      }
-    }, 250);
+    requestAvailability(username);
   }
 
   $effect(() => {

src/lib/utils/debounce.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { debounce } from './debounce';
+
+describe('debounce', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('delays invocation until the timer elapses', () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 100);
+
+    d('a');
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(99);
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledExactlyOnceWith('a');
+  });
+
+  it('collapses rapid calls into one invocation with the latest args', () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 100);
+
+    d('a');
+    vi.advanceTimersByTime(50);
+    d('b');
+    vi.advanceTimersByTime(50);
+    d('c');
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledExactlyOnceWith('c');
+  });
+
+  it('cancel() drops the pending invocation', () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 100);
+
+    d('a');
+    d.cancel();
+    vi.advanceTimersByTime(200);
+
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('flush() runs the pending invocation immediately', () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 100);
+
+    d('a');
+    d.flush();
+    expect(fn).toHaveBeenCalledExactlyOnceWith('a');
+
+    vi.advanceTimersByTime(200);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('flush() is a no-op when no call is pending', () => {
+    const fn = vi.fn();
+    const d = debounce(fn, 100);
+
+    d.flush();
+    expect(fn).not.toHaveBeenCalled();
+  });
+});

src/lib/utils/debounce.ts

@@ -0,0 +1,41 @@
+export interface Debounced<Args extends unknown[]> {
+  (...args: Args): void;
+  cancel(): void;
+  flush(): void;
+}
+
+export function debounce<Args extends unknown[]>(
+  fn: (...args: Args) => void,
+  delay: number
+): Debounced<Args> {
+  let handle: ReturnType<typeof setTimeout> | undefined;
+  let pending: Args | undefined;
+
+  const debounced = ((...args: Args) => {
+    clearTimeout(handle);
+    pending = args;
+    handle = setTimeout(() => {
+      handle = undefined;
+      const p = pending;
+      pending = undefined;
+      if (p) fn(...p);
+    }, delay);
+  }) as Debounced<Args>;
+
+  debounced.cancel = () => {
+    clearTimeout(handle);
+    handle = undefined;
+    pending = undefined;
+  };
+
+  debounced.flush = () => {
+    if (handle === undefined) return;
+    clearTimeout(handle);
+    handle = undefined;
+    const p = pending;
+    pending = undefined;
+    if (p) fn(...p);
+  };
+
+  return debounced;
+}

src/lib/utils/index.ts

@@ -1,3 +1,4 @@
+export * from './debounce';
 export * from './encoding';
 export * from './entropy';
 export * from './math';

src/routes/(app)/admin/blacklists/+page.svelte

@@ -15,7 +15,7 @@
   import { Separator } from '$lib/components/ui/separator';
   import { handleApiError } from '$lib/errorhandling/apiErrorHandling';
   import type { ValidationResult } from '$lib/types/ValidationResult';
-  import type { TimeoutHandle } from '$lib/types/WAPI';
+  import { debounce } from '$lib/utils/debounce';
 
   registerBreadcrumbs(() => [{ label: 'Blacklists' }]);
 
@@ -139,28 +139,28 @@
     }
   }
 
-  let usernameDebounce: TimeoutHandle | undefined;
+  const debouncedLoadUsernames = debounce(loadUsernames, 400);
   $effect(() => {
-    clearTimeout(usernameDebounce);
     if (usernameEntry.length == 0) {
+      debouncedLoadUsernames.cancel();
       loadUsernames();
       return;
     }
 
-    usernameDebounce = setTimeout(() => loadUsernames(), 400);
+    debouncedLoadUsernames();
   });
 
-  let emailDebounce: TimeoutHandle | undefined;
+  const debouncedLoadEmails = debounce(loadEmails, 400);
   $effect(() => {
-    clearTimeout(emailDebounce);
     if (emailEntry.length == 0) {
+      debouncedLoadEmails.cancel();
       loadEmails();
       return;
     }
 
     if (!emailEntryValid) return;
 
-    emailDebounce = setTimeout(() => loadEmails(), 400);
+    debouncedLoadEmails();
   });
 </script>
 

src/routes/(app)/admin/users/+page.svelte

@@ -85,7 +85,7 @@
   import { CardHeader, CardTitle } from '$lib/components/ui/card';
   import { Input } from '$lib/components/ui/input';
   import { handleApiError } from '$lib/errorhandling/apiErrorHandling';
-  import type { TimeoutHandle } from '$lib/types/WAPI';
+  import { debounce } from '$lib/utils/debounce';
 
   let isFetching = $state(false);
 
@@ -117,10 +117,8 @@
     page = Math.floor(response.offset / response.limit) + 1;
   }
 
-  let searchDebounce: TimeoutHandle | undefined;
+  const applyFilterQuery = debounce((query: string | undefined) => (filterQuery = query), 800);
   $effect(() => {
-    clearTimeout(searchDebounce);
-
     const queries: string[] = [];
 
     const nameQ = createSearchQuery('name', nameSearch);
@@ -132,7 +130,7 @@
     const query = queries.length > 0 ? queries.join(' and ') : undefined;
     if (query === filterQuery) return;
 
-    searchDebounce = setTimeout(() => (filterQuery = query), 800);
+    applyFilterQuery(query);
   });
 
   $effect(() => {