Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

9.2 KB
Raw Blame
import { useState, useEffect, useRef, useCallback } from 'react';
import { useVisibilityEvent } from './useVisibilityEvent.js';

/**
 * Auto-refetch on an interval, pausing while the tab is hidden and re-firing
 * once when it becomes visible again. Replaces the per-component
 * useEffect + setInterval pattern for data-fetch polling.
 *
 * Polling is an anti-pattern in PortOS: data should arrive via Socket.IO
 * events and own mutations should update local state from their response.
 * Reach for this hook only for a source that cannot push (hardware telemetry,
 * an external system with no callback) — see "Realtime updates, not polling"
 * in docs/UX_DESIGN_GUIDE.md.
 *
 * The hook catches whatever `fetchFn` throws, warns, and keeps the prior
 * `data` untouched — so data-path callers (those reading the returned `data`)
 * should NOT swallow errors with `.catch(() => null)`. Returning `null` here
 * applies that null and wipes the previously-displayed snapshot on every
 * transient blip; letting the error throw preserves the last good data.
 * `pollOnly` (side-effect) callers can also handle errors inside `fetchFn`
 * for their own logging or recovery; doing so swallows the rejection and
 * suppresses the hook's warn, so re-throw if you still want the hook log.
 *
 * `refetch` is intentionally unconditional — it bypasses the hidden-tab
 * short-circuit so explicit "Refresh" buttons work regardless of visibility.
 * Don't call it from effects that fire on mount/route change without a
 * visibility gate, or the "pauses while hidden" guarantee leaks.
 *
 * Each hook instance is single-flight: at most one `fetchFn` call is pending
 * at a time, so a slow response can never land after (and overwrite) a newer
 * one, and a stalled request can't pile up a new request per tick. Interval
 * and visibility ticks that arrive while a fetch is pending are dropped. A
 * `refetch()` that arrives while a fetch is pending queues ONE trailing fetch
 * (the pending one may predate the caller's mutation); every `refetch()` made
 * during that window shares the trailing fetch's promise. Unmounting drops a
 * queued trailing fetch — its promise resolves `undefined` without fetching.
 *
 * @param {Function} fetchFn - async; returns the new data, or any value if
 *   used purely for its side effects (see `pollOnly`).
 * @param {number} intervalMs - poll cadence; changing restarts the interval.
 * @param {Object} [options]
 * @param {boolean} [options.enabled=true] - when false, no interval and no fetch.
 * @param {boolean} [options.immediate=true] - when false, skip the on-mount
 *   fetch and wait `intervalMs` before the first fetch. Use when the caller
 *   already performs a one-shot fetch via another path.
 * @param {(prev:any, next:any)=>boolean} [options.compare] - when provided,
 *   each fetch keeps the previous reference (skipping the re-render) if
 *   `compare(prev, next)` returns true. Only invoked when both `prev` and
 *   `next` are non-null — the first fetch always sets data. Use for polls
 *   that return monotonic snapshots (e.g. `(a, b) => a.updatedAt === b.updatedAt`).
 *   Ignored in `pollOnly` mode (no data is tracked to compare).
 * @param {boolean} [options.pollOnly=false] - when true, the hook is treated
 *   as a side-effect-only poll tick: `data` / `loading` state is not tracked,
 *   no `applyResult` / setState calls run, and the return is `{ refetch }`
 *   only. Use when the caller owns its own state via `fetchFn`'s side
 *   effects and would otherwise `return null` and ignore `data` / `loading`.
 * @returns {{ refetch: Function, data?: any, loading?: boolean, error?: Error|null }}
 *   `data` / `loading` / `error` are omitted when `pollOnly` is true. `error`
 *   holds the most recent fetch failure (cleared on the next success) — the
 *   `data` it accompanies is still the last GOOD result, per the note above,
 *   so a caller that wants to show a "showing stale data" indicator without
 *   erasing the last good render checks `error` alongside `data` rather than
 *   inferring staleness from an empty/falsy `data`.
 */
// Normalize whatever a rejected fetchFn threw (an Error, or any other value —
// a caller can reject with a plain string/object) into a real Error so
// `error.message` is always safe to read.
const toFetchError = (err) => (err instanceof Error ? err : new Error(String(err ?? 'Auto-refetch failed')));

export function useAutoRefetch(fetchFn, intervalMs, options = {}) {
  const { enabled = true, immediate = true, compare, pollOnly = false } = options;
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(!pollOnly);
  const [error, setError] = useState(null);
  const fetchRef = useRef(fetchFn);
  const compareRef = useRef(compare);
  // The pending fetch (`{ promise, owner }`) or null. `owner` is the poll
  // effect's cancellation token for a tick-started fetch, or null for a manual
  // one — see `startFetch`.
  const inFlightRef = useRef(null);
  // A `refetch()` that arrived mid-flight: `{ promise, resolve }`, or null.
  const trailingRef = useRef(null);
  const disposedRef = useRef(false);

  useEffect(() => {
    fetchRef.current = fetchFn;
  }, [fetchFn]);

  // Kept in a ref so callers can pass an inline arrow without re-creating
  // applyResult/refetch on every render.
  useEffect(() => {
    compareRef.current = compare;
  }, [compare]);

  const applyResult = useCallback((result) => {
    if (pollOnly) return;
    setError(null);
    setData((prev) => {
      const cmp = compareRef.current;
      if (cmp && prev != null && result != null && cmp(prev, result)) return prev;
      return result;
    });
  }, [pollOnly]);

  // Runs one fetch as the instance's single in-flight request. A tick-started
  // fetch carries its poll effect's token as `owner`, so a result landing after
  // that effect was torn down (unmount, or `enabled` flipped off) is dropped —
  // unless a newer poll effect adopted it (see `loadData`). A manual fetch has
  // no owner and applies unless the hook unmounted. When it settles, a queued
  // trailing refetch starts, or is abandoned if the hook unmounted meanwhile.
  const startFetch = useCallback(function runFetch(owner) {
    const run = { owner, promise: null };
    const shouldApply = () => !disposedRef.current && !run.owner?.cancelled;
    // Claimed before the call: a fetchFn that throws synchronously settles
    // (and runs `finally`) before the IIFE returns.
    inFlightRef.current = run;
    run.promise = (async () => {
      try {
        const result = await fetchRef.current();
        if (shouldApply()) {
          applyResult(result);
          if (!pollOnly) setLoading(false);
        }
        return result;
      } catch (err) {
        console.warn(`⚠️ Auto-refetch failed: ${err?.message ?? String(err)}`);
        if (shouldApply() && !pollOnly) {
          setLoading(false);
          setError(toFetchError(err));
        }
        return undefined;
      } finally {
        inFlightRef.current = null;
        const trailing = trailingRef.current;
        trailingRef.current = null;
        if (trailing) trailing.resolve(disposedRef.current ? undefined : runFetch(null).promise);
      }
    })();
    return run;
  }, [applyResult, pollOnly]);

  // Stable, unconditional refetch for callers (Refresh buttons, post-mutation
  // refresh paths, and key-change effects that need an immediate fetch with
  // the new closure). Bypasses the visibility short-circuit — when a user
  // clicks Refresh the tab is by definition visible.
  const refetch = useCallback(() => {
    if (!inFlightRef.current) return startFetch(null).promise;
    if (!trailingRef.current) {
      let resolve;
      const promise = new Promise((r) => { resolve = r; });
      trailingRef.current = { promise, resolve };
    }
    return trailingRef.current.promise;
  }, [startFetch]);

  useEffect(() => {
    disposedRef.current = false;
    return () => {
      disposedRef.current = true;
      // Drop a queued follow-up now rather than when the pending fetch
      // settles, so nothing fires after unmount.
      trailingRef.current?.resolve(undefined);
      trailingRef.current = null;
    };
  }, []);

  const loadOnVisibleRef = useRef(null);

  useEffect(() => {
    if (!enabled) {
      loadOnVisibleRef.current = null;
      return undefined;
    }

    const token = { cancelled: false };

    const loadData = () => {
      if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return;
      const pending = inFlightRef.current;
      if (pending) {
        // Coalesce: never stack a second request. A tick-started fetch owned
        // by a torn-down poll effect (StrictMode remount, interval change,
        // enabled re-toggle) is adopted so its result still lands.
        if (pending.owner) pending.owner = token;
        return;
      }
      startFetch(token);
    };

    loadOnVisibleRef.current = loadData;
    if (immediate) loadData();
    const interval = setInterval(loadData, intervalMs);

    return () => {
      token.cancelled = true;
      clearInterval(interval);
      loadOnVisibleRef.current = null;
    };
  }, [intervalMs, enabled, immediate, startFetch]);

  useVisibilityEvent((state) => {
    if (state === 'visible') loadOnVisibleRef.current?.();
  });

  if (pollOnly) return { refetch };
  return { data, loading, error, refetch };
}