debounce refactoring and add throttle

Author: Archmonger

src/js/packages/@reactpy/client/src/components.tsx

@@ -8,6 +8,14 @@ import {
   type TargetedEvent,
 } from "preact";
 import { useContext, useEffect, useRef, useState } from "preact/hooks";
+import {
+  HANDLER_DEBOUNCE,
+  HANDLER_MARKER,
+  HANDLER_THROTTLE,
+  getInitialDebounce,
+  isValidDebounce,
+  type TaggedEventHandler,
+} from "./handler";
 import type {
   ImportSourceBinding,
   ReactPyComponent,
@@ -18,12 +26,25 @@ import type { ReactPyClient } from "./client";
 
 const ClientContext = createContext<ReactPyClient>(null as any);
 
-const DEFAULT_INPUT_DEBOUNCE = 200;
-
-type ReactPyInputHandler = ((event: TargetedEvent<any>) => void) & {
-  debounce?: number;
-  isHandler?: boolean;
-};
+// Built-in default debounce (ms) used by user-input elements (``<input>``,
+// ``<select>``, ``<textarea>``) when no per-handler ``debounce`` is set.
+// Non-input elements default to 0 ms (no debounce) — set ``debounce`` or
+// ``throttle`` explicitly on the handler if you need either behavior.
+const DEFAULT_INPUT_DEBOUNCE_MS = 200;
+const DEFAULT_NON_INPUT_DEBOUNCE_MS = 0;
+
+const USER_INPUT_TAGS = new Set(["input", "select", "textarea"]);
+
+/**
+ * Return the built-in default debounce (ms) for an element type.
+ * Inputs default to 200 ms to preserve text-input coherency against
+ * server-driven ``value`` updates; all other elements default to 0 ms.
+ */
+export function getDefaultDebounceMs(tagName: string): number {
+  return USER_INPUT_TAGS.has(tagName)
+    ? DEFAULT_INPUT_DEBOUNCE_MS
+    : DEFAULT_NON_INPUT_DEBOUNCE_MS;
+}
 
 type UserInputTarget =
   | HTMLInputElement
@@ -49,6 +70,64 @@ function trackUserInput(
   lastInputDebounce.current = debounce;
 }
 
+/**
+ * Wrap ``handler`` so its outgoing call is throttled to at most once per
+ * ``intervalMs`` milliseconds. Subsequent calls inside the window are
+ * collapsed and the trailing call (with the most recent arguments) fires
+ * once the window expires.
+ *
+ * Returns the original handler unchanged when ``intervalMs`` is missing or
+ * invalid.
+ */
+function throttleHandler(
+  handler: TaggedEventHandler,
+  intervalMs: number,
+): TaggedEventHandler {
+  if (!isValidDebounce(intervalMs)) {
+    return handler;
+  }
+  let pendingArgs: any[] | null = null;
+  let timer: number | null = null;
+  let lastFireTime = 0;
+
+  const wrapped = function (...args: any[]) {
+    const now = Date.now();
+    const elapsed = now - lastFireTime;
+    if (elapsed >= intervalMs) {
+      // Leading edge: fire immediately, then start a cooldown.
+      lastFireTime = now;
+      (handler as (...a: any[]) => void)(...args);
+      return;
+    }
+    // Trailing edge: remember the latest args and schedule a fire at the
+    // end of the cooldown so no event is silently dropped.
+    pendingArgs = args;
+    if (timer === null) {
+      timer = window.setTimeout(
+        () => {
+          timer = null;
+          if (pendingArgs !== null) {
+            const callArgs = pendingArgs;
+            pendingArgs = null;
+            lastFireTime = Date.now();
+            (handler as (...a: any[]) => void)(...callArgs);
+          }
+        },
+        Math.max(0, intervalMs - elapsed),
+      );
+    }
+  } as TaggedEventHandler;
+
+  // Preserve the tag markers so downstream code can still introspect the
+  // wrapped function.
+  wrapped[HANDLER_MARKER] = true;
+  const debounce = handler[HANDLER_DEBOUNCE];
+  if (typeof debounce === "number") {
+    wrapped[HANDLER_DEBOUNCE] = debounce;
+  }
+  return wrapped;
+}
+
 export function Layout(props: { client: ReactPyClient }): JSX.Element {
   const currentModel: ReactPyVdom = useState({ tagName: "" })[0];
   const forceUpdate = useForceUpdate();
@@ -97,12 +176,29 @@ export function Element({ model }: { model: ReactPyVdom }): JSX.Element | null {
 
 function StandardElement({ model }: { model: ReactPyVdom }) {
   const client = useContext(ClientContext);
+  const attrs = createAttributes(model, client);
+  // Apply the throttle wrapper to tagged handlers. ``debounce`` (server-→
+  // client value reconciliation) only applies to user-input elements, so
+  // it's intentionally ignored here; ``throttle`` works everywhere.
+  for (const [name, prop] of Object.entries(attrs)) {
+    if (typeof prop !== "function") {
+      continue;
+    }
+    const handler = prop as TaggedEventHandler;
+    if (!handler[HANDLER_MARKER]) {
+      continue;
+    }
+    const throttle = handler[HANDLER_THROTTLE];
+    if (isValidDebounce(throttle)) {
+      attrs[name] = throttleHandler(handler, throttle as number);
+    }
+  }
   // Use createElement here to avoid warning about variable numbers of children not
   // having keys. Warning about this must now be the responsibility of the client
   // providing the models instead of the client rendering them.
   return createElement(
     model.tagName === "" ? Fragment : model.tagName,
-    createAttributes(model, client),
+    attrs,
     ...createChildren(model, (child) => {
       return <Element model={child} key={child.attributes?.key} />;
     }),
@@ -115,7 +211,13 @@ function UserInputElement({ model }: { model: ReactPyVdom }): JSX.Element {
   const [value, setValue] = useState(props.value);
   const lastUserValue = useRef(props.value);
   const lastChangeTime = useRef(0);
-  const lastInputDebounce = useRef(DEFAULT_INPUT_DEBOUNCE);
+  // Seed the debounce window from the handlers themselves when possible,
+  // otherwise fall back to the per-tagName built-in default (200 ms for
+  // user-input tags, 0 ms elsewhere). This ensures the very first
+  // server-driven update already respects the configured debounce.
+  const lastInputDebounce = useRef(
+    getInitialDebounce(props, getDefaultDebounceMs(model.tagName)),
+  );
   const reconcileTimeout = useRef<number | null>(null);
 
   // honor changes to value from the client via props
@@ -154,23 +256,30 @@ function UserInputElement({ model }: { model: ReactPyVdom }): JSX.Element {
       continue;
     }
 
-    const givenHandler = prop as ReactPyInputHandler;
-    if (!givenHandler.isHandler) {
+    const givenHandler = prop as TaggedEventHandler;
+    if (!givenHandler[HANDLER_MARKER]) {
       continue;
     }
 
+    const handlerDebounce = givenHandler[HANDLER_DEBOUNCE];
+    const effectiveDebounce = isValidDebounce(handlerDebounce)
+      ? handlerDebounce
+      : getDefaultDebounceMs(model.tagName);
+
+    const throttled = isValidDebounce(givenHandler[HANDLER_THROTTLE])
+      ? throttleHandler(givenHandler, givenHandler[HANDLER_THROTTLE] as number)
+      : givenHandler;
+
     props[name] = (event: TargetedEvent<any>) => {
       trackUserInput(
         event,
         setValue,
         lastUserValue,
         lastChangeTime,
         lastInputDebounce,
-        typeof givenHandler.debounce === "number"
-          ? givenHandler.debounce
-          : DEFAULT_INPUT_DEBOUNCE,
+        effectiveDebounce,
       );
-      givenHandler(event);
+      throttled(event);
     };
   }
 

src/js/packages/@reactpy/client/src/handler.ts

@@ -0,0 +1,56 @@
+// Shared marker property names attached to event handler functions created by
+// `vdom.tsx::createEventHandler`. Centralizing these strings keeps `components.tsx`
+// and `vdom.tsx` in sync without relying on ad-hoc property names.
+
+export const HANDLER_MARKER = "isHandler" as const;
+export const HANDLER_DEBOUNCE = "debounce" as const;
+export const HANDLER_THROTTLE = "throttle" as const;
+
+export type HandlerMarker = typeof HANDLER_MARKER;
+export type HandlerDebounce = typeof HANDLER_DEBOUNCE;
+export type HandlerThrottle = typeof HANDLER_THROTTLE;
+
+export type TaggedEventHandler = ((event: Event) => void) & {
+  [HANDLER_MARKER]: true;
+  [HANDLER_DEBOUNCE]?: number;
+  [HANDLER_THROTTLE]?: number;
+};
+
+/**
+ * Returns the debounce value (in milliseconds) to use as the default for a user
+ * input element when no user input has been recorded yet. Uses the maximum
+ * debounce among the element's tagged handlers, falling back to the global
+ * default if none of the handlers specify one.
+ */
+export function getInitialDebounce(
+  props: Record<string, unknown>,
+  fallback: number,
+): number {
+  let max = 0;
+  for (const value of Object.values(props)) {
+    if (typeof value !== "function") {
+      continue;
+    }
+    const candidate = (value as TaggedEventHandler)[HANDLER_DEBOUNCE];
+    if (typeof candidate === "number" && candidate > max) {
+      max = candidate;
+    }
+  }
+  return max > 0 ? max : fallback;
+}
+
+/**
+ * Returns true when the given value is a finite, non-negative integer.
+ * Used to validate debounce/throttle values arriving over the wire from the
+ * Python layout.
+ */
+export function isValidDebounce(value: unknown): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    Number.isInteger(value) &&
+    value >= 0
+  );
+}
+
+export const isValidThrottle = isValidDebounce;

src/js/packages/@reactpy/client/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./client";
 export * from "./components";
+export * from "./handler";
 export * from "./mount";
 export * from "./types";
 export * from "./vdom";

src/js/packages/@reactpy/client/src/types.ts

@@ -61,6 +61,7 @@ export type ReactPyVdomEventHandler = {
   preventDefault?: boolean;
   stopPropagation?: boolean;
   debounce?: number;
+  throttle?: number;
 };
 
 export type ReactPyVdomImportSource = {

src/js/packages/@reactpy/client/src/vdom.tsx

@@ -1,17 +1,25 @@
 import eventToObject from "event-to-object";
 import { Fragment } from "preact";
+import {
+  HANDLER_DEBOUNCE,
+  HANDLER_MARKER,
+  HANDLER_THROTTLE,
+  isValidDebounce,
+  isValidThrottle,
+  type TaggedEventHandler,
+} from "./handler";
+import { infer_bind_from_environment } from "./bind";
+import log from "./logger";
+import type { ReactPyClient } from "./client";
 import type {
-  ReactPyVdom,
-  ReactPyVdomImportSource,
-  ReactPyVdomEventHandler,
-  ReactPyModule,
   BindImportSource,
-  ReactPyModuleBinding,
   ImportSourceBinding,
+  ReactPyModule,
+  ReactPyModuleBinding,
+  ReactPyVdom,
+  ReactPyVdomEventHandler,
+  ReactPyVdomImportSource,
 } from "./types";
-import { infer_bind_from_environment } from "./bind";
-import log from "./logger";
-import type { ReactPyClient } from "./client";
 
 export async function loadImportSource(
   vdomImportSource: ReactPyVdomImportSource,
@@ -211,8 +219,9 @@ function createEventHandler(
     preventDefault,
     stopPropagation,
     debounce,
+    throttle,
   }: ReactPyVdomEventHandler,
-): [string, () => void] {
+): [string, TaggedEventHandler] {
   const eventHandler = function (...args: any[]) {
     const data = Array.from(args).map((value) => {
       const event = value as Event;
@@ -231,19 +240,27 @@ function createEventHandler(
       }
     });
     client.sendMessage({ type: "layout-event", data, target });
-  };
-  (
-    eventHandler as typeof eventHandler & {
-      debounce?: number;
-      isHandler: boolean;
+  } as TaggedEventHandler;
+  eventHandler[HANDLER_MARKER] = true;
+  if (debounce !== undefined) {
+    if (!isValidDebounce(debounce)) {
+      log.warn(
+        `Ignoring invalid debounce value ${JSON.stringify(debounce)} ` +
+          `on event handler "${name}": expected a non-negative integer.`,
+      );
+    } else {
+      eventHandler[HANDLER_DEBOUNCE] = debounce;
+    }
+  }
+  if (throttle !== undefined) {
+    if (!isValidThrottle(throttle)) {
+      log.warn(
+        `Ignoring invalid throttle value ${JSON.stringify(throttle)} ` +
+          `on event handler "${name}": expected a non-negative integer.`,
+      );
+    } else {
+      eventHandler[HANDLER_THROTTLE] = throttle;
     }
-  ).isHandler = true;
-  if (typeof debounce === "number") {
-    (
-      eventHandler as typeof eventHandler & {
-        debounce?: number;
-      }
-    ).debounce = debounce;
   }
   return [name, eventHandler];
 }