perf: add debounce for preview updates to reduce unnecessary renders

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: lambdalisue

denops/fall/lib/debounce.ts

@@ -0,0 +1,65 @@
+export type DebounceOptions = {
+  delay?: number;
+  signal?: AbortSignal;
+};
+
+/**
+ * Creates a debounced function that delays invoking the provided function until after
+ * the specified delay has elapsed since the last time the debounced function was invoked.
+ *
+ * @param fn - The function to debounce
+ * @param options - Configuration options
+ * @param options.delay - The number of milliseconds to delay (default: 0)
+ * @param options.signal - An optional AbortSignal to cancel the debounced function
+ * @returns A debounced version of the function
+ *
+ * @example
+ * ```ts
+ * import { debounce } from "./debounce.ts";
+ * import { delay } from "jsr:@std/async@^1.0.0/delay";
+ *
+ * const saveData = () => console.log("Saving data...");
+ * const debouncedSave = debounce(() => saveData(), { delay: 100 });
+ *
+ * // Multiple calls within 100ms will only trigger one save
+ * debouncedSave();
+ * debouncedSave();
+ * debouncedSave();
+ *
+ * // Wait for the debounced function to execute
+ * await delay(150);
+ *
+ * // Cancel via AbortSignal
+ * const doWork = () => console.log("Doing work...");
+ * const controller = new AbortController();
+ * const debouncedFunc = debounce(() => doWork(), {
+ *   delay: 50,
+ *   signal: controller.signal
+ * });
+ * debouncedFunc();
+ * controller.abort(); // Cancels any pending execution
+ * ```
+ */
+// deno-lint-ignore no-explicit-any
+export function debounce<F extends (...args: any[]) => void>(
+  fn: F,
+  { delay, signal }: DebounceOptions = {},
+): F {
+  let timerId: number | undefined;
+
+  const abort = () => {
+    if (timerId !== undefined) {
+      clearTimeout(timerId);
+      timerId = undefined;
+    }
+  };
+
+  signal?.addEventListener("abort", abort, { once: true });
+  return ((...args) => {
+    abort();
+    timerId = setTimeout(() => {
+      timerId = undefined;
+      fn(...args);
+    }, delay);
+  }) as F;
+}

denops/fall/lib/debounce_test.ts

@@ -0,0 +1,86 @@
+import { assertEquals } from "jsr:@std/assert@^1.0.6";
+import { delay } from "jsr:@std/async@^1.0.0/delay";
+import { FakeTime } from "jsr:@std/testing@^1.0.0/time";
+
+import { debounce } from "./debounce.ts";
+
+Deno.test("debounce", async (t) => {
+  await t.step("delays function execution", async () => {
+    using time = new FakeTime();
+
+    let callCount = 0;
+    const fn = debounce(() => {
+      callCount++;
+    }, { delay: 100 });
+
+    fn();
+    assertEquals(callCount, 0);
+
+    await time.tickAsync(50);
+    assertEquals(callCount, 0);
+
+    await time.tickAsync(50);
+    assertEquals(callCount, 1);
+  });
+
+  await t.step(
+    "cancels previous calls when called multiple times",
+    async () => {
+      using time = new FakeTime();
+
+      let callCount = 0;
+      let lastValue = 0;
+      const fn = debounce((value: number) => {
+        callCount++;
+        lastValue = value;
+      }, { delay: 100 });
+
+      fn(1);
+      await time.tickAsync(50);
+      fn(2);
+      await time.tickAsync(50);
+      fn(3);
+      await time.tickAsync(50);
+
+      assertEquals(callCount, 0);
+
+      await time.tickAsync(50);
+      assertEquals(callCount, 1);
+      assertEquals(lastValue, 3);
+    },
+  );
+
+  await t.step("works with real timers", async () => {
+    let callCount = 0;
+    const fn = debounce(() => {
+      callCount++;
+    }, { delay: 50 });
+
+    fn();
+    assertEquals(callCount, 0);
+
+    await delay(30);
+    assertEquals(callCount, 0);
+
+    await delay(30);
+    assertEquals(callCount, 1);
+  });
+
+  await t.step("respects abort signal", async () => {
+    using time = new FakeTime();
+
+    let callCount = 0;
+    const controller = new AbortController();
+    const fn = debounce(() => {
+      callCount++;
+    }, { delay: 100, signal: controller.signal });
+
+    fn();
+    await time.tickAsync(50);
+
+    controller.abort();
+
+    await time.tickAsync(100);
+    assertEquals(callCount, 0);
+  });
+});

denops/fall/picker.ts

@@ -18,6 +18,7 @@ import type { Previewer } from "jsr:@vim-fall/core@^0.3.0/previewer";
 import type { Theme } from "jsr:@vim-fall/core@^0.3.0/theme";
 
 import { Scheduler } from "./lib/scheduler.ts";
+import { debounce } from "./lib/debounce.ts";
 import { Cmdliner } from "./util/cmdliner.ts";
 import { isIncrementalMatcher } from "./util/predicate.ts";
 import { buildMappingHelpPages } from "./util/mapping.ts";
@@ -37,6 +38,7 @@ import { HelpComponent } from "./component/help.ts";
 import { consume, type Event } from "./event.ts";
 
 const SCHEDULER_INTERVAL = 10;
+const PREVIEW_DEBOUNCE_DELAY = 150;
 const MATCHER_ICON = "🅼 ";
 const SORTER_ICON = "🆂 ";
 const RENDERER_ICON = "🆁 ";
@@ -70,6 +72,7 @@ export type PickerResult<T extends Detail> = {
 
 export type PickerOptions = {
   schedulerInterval?: number;
+  previewDebounceDelay?: number;
 };
 
 export type PickerContext<T extends Detail> = {
@@ -89,6 +92,7 @@ export class Picker<T extends Detail> implements AsyncDisposable {
   static readonly ZINDEX_ALLOCATION = 4;
   readonly #stack = new AsyncDisposableStack();
   readonly #schedulerInterval: number;
+  readonly #previewDebounceDelay: number;
   readonly #name: string;
   readonly #coordinator: Coordinator;
   readonly #collectProcessor: CollectProcessor<T>;
@@ -110,6 +114,8 @@ export class Picker<T extends Detail> implements AsyncDisposable {
 
   constructor(params: PickerParams<T>, options: PickerOptions = {}) {
     this.#schedulerInterval = options.schedulerInterval ?? SCHEDULER_INTERVAL;
+    this.#previewDebounceDelay = options.previewDebounceDelay ??
+      PREVIEW_DEBOUNCE_DELAY;
 
     const { name, theme, coordinator, zindex = 50, context } = params;
     this.#name = name;
@@ -358,6 +364,10 @@ export class Picker<T extends Detail> implements AsyncDisposable {
     const reserve = (callback: ReservedCallback) => {
       reservedCallbacks.push(callback);
     };
+    const reservePreviewDebounced = debounce(reserve, {
+      delay: this.#previewDebounceDelay,
+      signal,
+    });
     const cmdliner = new Cmdliner({
       cmdline: this.#inputComponent.cmdline,
       cmdpos: this.#inputComponent.cmdpos,
@@ -368,7 +378,13 @@ export class Picker<T extends Detail> implements AsyncDisposable {
       await cmdliner.check(denops);
 
       // Handle events synchronously
-      consume((event) => this.#handleEvent(event, { accept, reserve }));
+      consume((event) =>
+        this.#handleEvent(event, {
+          accept,
+          reserve,
+          reservePreviewDebounced,
+        })
+      );
 
       // Handle reserved callbacks asynchronously
       for (const callback of reservedCallbacks) {
@@ -469,9 +485,10 @@ export class Picker<T extends Detail> implements AsyncDisposable {
     }
   }
 
-  #handleEvent(event: Event, { accept, reserve }: {
+  #handleEvent(event: Event, { accept, reserve, reservePreviewDebounced }: {
     accept: (name: string) => Promise<void>;
     reserve: (callback: ReservedCallback) => void;
+    reservePreviewDebounced: (callback: ReservedCallback) => void;
   }): void {
     switch (event.type) {
       case "vim-cmdline-changed":
@@ -617,7 +634,7 @@ export class Picker<T extends Detail> implements AsyncDisposable {
         }
         this.#previewProcessor.previewerIndex = index;
         this.#listComponent.title = this.#getExtensionIndicator();
-        reserve((denops) => {
+        reservePreviewDebounced((denops) => {
           this.#previewProcessor?.start(denops, {
             item: this.#matchProcessor.items[this.#renderProcessor.cursor],
           });
@@ -628,7 +645,7 @@ export class Picker<T extends Detail> implements AsyncDisposable {
         if (!this.#previewProcessor) break;
         this.#previewProcessor.previewerIndex = event.index;
         this.#listComponent.title = this.#getExtensionIndicator();
-        reserve((denops) => {
+        reservePreviewDebounced((denops) => {
           this.#previewProcessor?.start(denops, {
             item: this.#matchProcessor.items[this.#renderProcessor.cursor],
           });
@@ -756,7 +773,7 @@ export class Picker<T extends Detail> implements AsyncDisposable {
         const line = this.#renderProcessor.line;
         this.#listComponent.items = this.#renderProcessor.items;
         this.#listComponent.execute(`silent! normal! ${line}G`);
-        reserve((denops) => {
+        reservePreviewDebounced((denops) => {
           this.#previewProcessor?.start(denops, {
             item: this.#matchProcessor.items[this.#renderProcessor.cursor],
           });