refactor: replace debounce/throttle deps with first-party code (#38610)

Adds `web_src/js/utils/func.ts` with `debounce` and `throttle`, dropping
`throttle-debounce` and `perfect-debounce` dependencies. Both were
needed before: the former has no promise-returning debounce, which
`TextExpander` requires, and the latter no `throttle`.

Signature follows lodash and es-toolkit: `(func, wait, {leading,
trailing})` plus `cancel`, so argument order flips at the migrated call
sites.

web_src/js/utils/dom.ts

@@ -1,4 +1,4 @@
-import {debounce} from 'throttle-debounce';
+import {debounce} from './func.ts';
 import type {Promisable} from '../types.ts';
 import type $ from 'jquery';
 import {isInFrontendUnitTest} from './testhelper.ts';
@@ -242,7 +242,7 @@ export function autosize(textarea: HTMLTextAreaElement, {viewportMarginBottom =
 }
 
 export function onInputDebounce(fn: () => Promisable<any>) {
-  return debounce(300, fn);
+  return debounce(fn, 300);
 }
 
 type LoadableElement = HTMLEmbedElement | HTMLIFrameElement | HTMLImageElement | HTMLScriptElement | HTMLTrackElement;

web_src/js/utils/func.test.ts

@@ -0,0 +1,74 @@
+import {debounce, throttle} from './func.ts';
+
+test('debounce', {concurrent: false}, () => {
+  vi.useFakeTimers();
+  const spy = vi.fn();
+  const fn = debounce(spy, 10);
+  fn();
+  fn();
+  fn();
+  expect(spy).toHaveBeenCalledTimes(0);
+  vi.advanceTimersByTime(30);
+  expect(spy).toHaveBeenCalledTimes(1);
+  vi.useRealTimers();
+});
+
+test('debounce leading', {concurrent: false}, () => {
+  vi.useFakeTimers();
+  const spy = vi.fn();
+  const fn = debounce(spy, 10, {leading: true, trailing: false});
+  fn();
+  expect(spy).toHaveBeenCalledTimes(1);
+  fn();
+  vi.advanceTimersByTime(30);
+  expect(spy).toHaveBeenCalledTimes(1);
+  vi.useRealTimers();
+});
+
+test('debounce result', {concurrent: false}, async () => {
+  vi.useFakeTimers();
+  const fn = debounce((value: number) => value * 2, 10);
+  const first = fn(1);
+  const second = fn(2);
+  vi.advanceTimersByTime(10);
+  expect(await first).toEqual(4); // both calls collapse into the last one
+  expect(await second).toEqual(4);
+  vi.useRealTimers();
+});
+
+test('debounce cancel', {concurrent: false}, () => {
+  vi.useFakeTimers();
+  const spy = vi.fn();
+  const fn = debounce(spy, 10);
+  fn();
+  fn.cancel();
+  vi.advanceTimersByTime(30);
+  expect(spy).toHaveBeenCalledTimes(0);
+  vi.useRealTimers();
+});
+
+test('throttle', {concurrent: false}, () => {
+  vi.useFakeTimers();
+  const spy = vi.fn();
+  const fn = throttle(spy, 10);
+  fn();
+  fn();
+  fn();
+  expect(spy).toHaveBeenCalledTimes(1); // leading
+  vi.advanceTimersByTime(30);
+  expect(spy).toHaveBeenCalledTimes(2); // plus one trailing for the collapsed rest
+  vi.useRealTimers();
+});
+
+test('throttle trailing only', {concurrent: false}, () => {
+  vi.useFakeTimers();
+  const spy = vi.fn();
+  const fn = throttle(spy, 10, {leading: false});
+  fn();
+  fn();
+  fn();
+  expect(spy).toHaveBeenCalledTimes(0);
+  vi.advanceTimersByTime(30);
+  expect(spy).toHaveBeenCalledTimes(1);
+  vi.useRealTimers();
+});

web_src/js/utils/func.ts

@@ -0,0 +1,82 @@
+import type {TimeoutId} from '../types.ts';
+
+/** Options for `debounce` */
+export type DebounceOpts = {
+  /** Invoke on the leading edge of the wait period. Default: `false` */
+  leading?: boolean,
+  /** Invoke on the trailing edge of the wait period. Default: `true` */
+  trailing?: boolean,
+};
+
+/** Options for `throttle` */
+export type ThrottleOpts = {
+  /** Invoke on the leading edge of the interval. Default: `true` */
+  leading?: boolean,
+  /** Invoke on the trailing edge of the interval. Default: `true` */
+  trailing?: boolean,
+};
+
+/** A debounced or throttled function. Calls collapsed into one invocation settle with its result, dropped calls never settle. */
+export type TimedFunction<T extends (...args: Array<any>) => any> = ((...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>) & {
+  /** Drop the pending invocation */
+  cancel: () => void,
+};
+
+function createTimed<T extends (...args: Array<any>) => any>(func: T, wait: number, leading: boolean, trailing: boolean, isThrottle: boolean): TimedFunction<T> {
+  let timer: TimeoutId | null = null;
+  let pendingArgs: Parameters<T> | null = null;
+  let resolvers: Array<{resolve: (value: any) => void, reject: (reason: any) => void}> = [];
+
+  const invoke = async (args: Parameters<T>): Promise<void> => {
+    const settling = resolvers;
+    resolvers = [];
+    try {
+      const value = await func(...args);
+      for (const {resolve} of settling) resolve(value);
+    } catch (err) {
+      for (const {reject} of settling) reject(err);
+    }
+  };
+
+  const onTimer = (): void => {
+    timer = null;
+    const args = pendingArgs;
+    pendingArgs = null;
+    if (trailing && args) {
+      invoke(args);
+      if (isThrottle) timer = setTimeout(onTimer, wait); // keep the window open so a burst stays rate-limited
+    } else {
+      resolvers = [];
+    }
+  };
+
+  const cancel = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    pendingArgs = null;
+    resolvers = [];
+  };
+
+  const wrapper = (...args: Parameters<T>): Promise<Awaited<ReturnType<T>>> => {
+    const promise = new Promise<Awaited<ReturnType<T>>>((resolve, reject) => {
+      resolvers.push({resolve, reject});
+    });
+    const isLeadingCall = leading && timer === null;
+    if (!isThrottle && timer) { clearTimeout(timer); timer = null } // debounce restarts the wait on every call, throttle does not
+    if (isLeadingCall) invoke(args); else pendingArgs = args;
+    if (timer === null) timer = setTimeout(onTimer, wait);
+    return promise;
+  };
+
+  return Object.assign(wrapper, {cancel});
+}
+
+/** Debounce a function, delaying invocation until `wait` milliseconds have passed without another call */
+export function debounce<T extends (...args: Array<any>) => any>(func: T, wait: number, {leading = false, trailing = true}: DebounceOpts = {}): TimedFunction<T> {
+  return createTimed(func, wait, leading, trailing, false);
+}
+
+/** Throttle a function to invoke at most once per `interval` milliseconds */
+export function throttle<T extends (...args: Array<any>) => any>(func: T, interval: number, {leading = true, trailing = true}: ThrottleOpts = {}): TimedFunction<T> {
+  return createTimed(func, interval, leading, trailing, true);
+}