@brftech/filex-core 0.33.0 → 0.34.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brftech/filex-core",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "description": "filex core — Vue 3 source of truth for the filex file manager (FileExplorer + ConnectionsPanel SFCs, composables, types)",
   "type": "module",
   "main": "./dist/filex-core.umd.cjs",

package/src/composables/useRealtime.ts

@@ -8,8 +8,15 @@
 
 import { ref, type Ref } from 'vue';
 import { RealtimeClient, type PresenceUser, type PresenceMessage } from '../lib/realtime';
+import { burstDebounce } from '../lib/burstDebounce';
 
 const RELOAD_DEBOUNCE_MS = 200;
+// Ceiling on how long a run of change frames may postpone the reload it is
+// waiting for — see burstDebounce for the starvation this exists to stop.
+// Measured in a real browser on 2026-09-06, watching a folder while a
+// 5 000-file zip was extracted into it: the first re-listing came 114 s into
+// the job, and there was a 40 s gap in the middle.
+const RELOAD_MAX_WAIT_MS = 2_000;
 const POLL_INTERVAL_MS = 12_000;
 
 export interface RealtimeApi {
@@ -28,19 +35,12 @@ export function useRealtime(api: RealtimeApi, opts: { reload: () => void }) {
 
   let client: RealtimeClient | null = null;
   let pendingSubscribe: string | null = null;
-  let reloadTimer: ReturnType<typeof setTimeout> | null = null;
+  const debouncedReload = burstDebounce(() => opts.reload(), {
+    wait: RELOAD_DEBOUNCE_MS,
+    maxWait: RELOAD_MAX_WAIT_MS,
+  });
   let pollTimer: ReturnType<typeof setInterval> | null = null;
 
-  function debouncedReload(): void {
-    // A burst of change frames (e.g. a multi-file upload) collapses into one
-    // soft reload of the current folder.
-    if (reloadTimer) clearTimeout(reloadTimer);
-    reloadTimer = setTimeout(() => {
-      reloadTimer = null;
-      opts.reload();
-    }, RELOAD_DEBOUNCE_MS);
-  }
-
   function onPresence(msg: PresenceMessage): void {
     // Ignore late frames for a folder we've already navigated away from.
     if (pendingSubscribe && msg.path && msg.path !== pendingSubscribe) return;
@@ -85,10 +85,7 @@ export function useRealtime(api: RealtimeApi, opts: { reload: () => void }) {
   }
 
   function stop(): void {
-    if (reloadTimer) {
-      clearTimeout(reloadTimer);
-      reloadTimer = null;
-    }
+    debouncedReload.cancel();
     if (pollTimer) {
       clearInterval(pollTimer);
       pollTimer = null;

package/src/lib/burstDebounce.ts

@@ -0,0 +1,57 @@
+// burstDebounce: a trailing debounce that cannot be starved.
+//
+// The explorer re-lists a folder when a change frame says it changed, debounced
+// so a burst of frames costs one listing instead of N. A PLAIN trailing
+// debounce has a failure mode that only shows up under a sustained stream:
+// every frame clears the pending timer, so while frames keep arriving closer
+// together than `wait`, the reload never happens at all. That is not "one
+// reload instead of many" — it is zero, and the person watching the folder sees
+// nothing change until the job that is writing the files finishes.
+//
+// Measured in a real browser on 2026-09-06 against a 5 000-file zip extraction
+// (frames roughly every 40 ms for 195 s): the folder's first re-listing came
+// 114 s in, with a 40 s gap after it.
+//
+// `maxWait` is the ceiling: however long the stream goes on, the call happens
+// at most `maxWait` after the FIRST frame of the run, and the run then starts
+// again. A quiet folder is untouched — one frame still calls `wait` later.
+export interface BurstDebounceOptions {
+  /** Quiet period after the last call before firing. */
+  wait: number;
+  /** Ceiling from the first call of a run. Must be >= wait to mean anything. */
+  maxWait: number;
+  /** Clock, injectable for tests. */
+  now?: () => number;
+}
+
+export interface BurstDebounced {
+  (): void;
+  /** Drop any pending call (unmount). */
+  cancel(): void;
+}
+
+export function burstDebounce(fn: () => void, opts: BurstDebounceOptions): BurstDebounced {
+  const now = opts.now ?? (() => Date.now());
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let runStartedAt: number | null = null;
+
+  const call = () => {
+    const t = now();
+    if (runStartedAt === null) runStartedAt = t;
+    // Never later than the ceiling, never sooner than 0.
+    const untilCeiling = runStartedAt + opts.maxWait - t;
+    const delay = Math.max(0, Math.min(opts.wait, untilCeiling));
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      runStartedAt = null;
+      fn();
+    }, delay);
+  };
+  call.cancel = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    runStartedAt = null;
+  };
+  return call;
+}