Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

9.3 KB
Raw Blame
import { type InfiniteData, useQueryClient } from "@tanstack/react-query";
import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
import type { GetSessionsResponse, LiveUserCountResponse } from "../../../../api/analytics/endpoints";

export type FirstPageviewPhase = "unknown" | "none" | "waiting" | "filling" | "ready" | "dismissed";

export type FirstPageviewEvent =
  | { type: "has-data"; hasData: boolean | undefined }
  | { type: "settled" }
  | { type: "dismiss" };

type Session = GetSessionsResponse[number];

// useSiteHasData's key.
const SITE_HAS_DATA_KEY = "site-has-data";
// Both polled every 10 s by SubHeader's LiveUserCount (useGetLiveUserCount, useGetSessionsInfinite).
// The sessions list only while its drawer is open, or while NoData holds it live (useHoldLiveSessions).
const LIVE_USER_COUNT_KEY = "live-user-count";
const LIVE_SESSIONS_KEY = "sessions-infinite";
// The dashboard refetch waits for the morph (install card fade-out, then the height spring) to mostly
// settle: its re-renders would otherwise stall the spring on the main thread into visible jumps. It
// also keeps "Your dashboard is filling in" on screen long enough to read.
export const ARRIVAL_REFRESH_DELAY_MS = 600;

/**
 * The install card's lifecycle for one site:
 * unknown → waiting (has-data answered false) → filling (it flipped to true while we watched)
 * → ready (the dashboard's queries refetched) → dismissed.
 * A site that already had data when has-data first answered goes to "none": nothing to celebrate.
 */
export function nextFirstPageviewPhase(phase: FirstPageviewPhase, event: FirstPageviewEvent): FirstPageviewPhase {
  switch (event.type) {
    case "has-data":
      if (event.hasData === undefined) return phase;
      if (phase === "unknown") return event.hasData ? "none" : "waiting";
      return phase === "waiting" && event.hasData ? "filling" : phase;
    case "settled":
      return phase === "filling" ? "ready" : phase;
    case "dismiss":
      return phase === "filling" || phase === "ready" ? "dismissed" : phase;
  }
}

/**
 * Whether a query was built by useAnalyticsQuery / useAnalyticsInfiniteQuery for `site`. Those keys are
 * one or more key parts followed by [scope, path, params, body], plus "infinite" for infinite queries.
 */
export function isSiteAnalyticsQueryKey(queryKey: readonly unknown[], site: string): boolean {
  const end = queryKey[queryKey.length - 1] === "infinite" ? queryKey.length - 1 : queryKey.length;
  const scope = end - 4;
  const params = queryKey[scope + 2];
  return (
    scope >= 1 &&
    String(queryKey[scope]) === site &&
    typeof queryKey[scope + 1] === "string" &&
    typeof params === "object" &&
    params !== null
  );
}

/** The session with the earliest start across cached session-list pages. */
export function earliestSession(cached: readonly unknown[]): Session | undefined {
  let earliest: Session | undefined;
  for (const data of cached) {
    for (const page of (data as InfiniteData<GetSessionsResponse | null> | undefined)?.pages ?? []) {
      for (const session of page ?? []) {
        if (!earliest || session.session_start < earliest.session_start) earliest = session;
      }
    }
  }
  return earliest;
}

interface Journey {
  site: string;
  phase: FirstPageviewPhase;
}

const startJourney = (site: string): Journey => ({ site, phase: "unknown" });

/** The card's phase for one site. Switching sites starts over. */
export function useFirstPageviewJourney(site: string, hasData: boolean | undefined) {
  const [journey, setJourney] = useState(() => startJourney(site));

  // Folded in during render rather than in an effect, so a has-data flip never paints a stale card.
  const base = journey.site === site ? journey : startJourney(site);
  const phase = nextFirstPageviewPhase(base.phase, { type: "has-data", hasData });
  if (base !== journey || phase !== journey.phase) setJourney({ ...base, phase });

  const settle = useCallback(
    () => setJourney(current => ({ ...current, phase: nextFirstPageviewPhase(current.phase, { type: "settled" }) })),
    []
  );
  const dismiss = useCallback(
    () => setJourney(current => ({ ...current, phase: nextFirstPageviewPhase(current.phase, { type: "dismiss" }) })),
    []
  );
  return { phase, settle, dismiss };
}

/**
 * While the site has no data, re-ask has-data the moment the live-user-count query (which SubHeader's
 * LiveUserCount polls every 10 s) sees a visitor, instead of waiting out has-data's 30 s poll.
 *
 * It listens to the query cache instead of mounting a useGetLiveUserCount observer of its own: each
 * observer runs its own refetch interval, and one mounted here, in the layout that outlives every page's
 * LiveUserCount, would drift out of phase with it and double the requests, or start a new 10 s poll on
 * pages that have no LiveUserCount. Pages without one fall back to has-data's own poll.
 */
export function useLiveVisitorNudge(site: string, enabled: boolean) {
  const queryClient = useQueryClient();

  useEffect(() => {
    if (!enabled || !site) return;
    const cache = queryClient.getQueryCache();
    const someoneOnline = () =>
      cache
        .findAll({ queryKey: [LIVE_USER_COUNT_KEY, site] })
        .some(query => ((query.state.data as LiveUserCountResponse | undefined)?.count ?? 0) > 0);
    const nudge = () => void queryClient.invalidateQueries({ queryKey: [SITE_HAS_DATA_KEY, site], exact: true });

    let online = someoneOnline();
    if (online) nudge();
    return cache.subscribe(event => {
      if (event.type !== "updated" || event.action.type !== "success") return;
      const [key, scope] = event.query.queryKey;
      if (key !== LIVE_USER_COUNT_KEY || scope !== site) return;
      const now = someoneOnline();
      if (now && !online) nudge();
      online = now;
    });
  }, [enabled, queryClient, site]);
}

/**
 * The first visitor, read from sessions the live-sessions query has already fetched for the site.
 * Never fetches: undefined until (and unless) that data is in the cache.
 */
export function useFirstSession(site: string, enabled: boolean): Session | undefined {
  const cache = useQueryClient().getQueryCache();
  const subscribe = useCallback(
    (onChange: () => void) => (enabled ? cache.subscribe(onChange) : () => {}),
    [cache, enabled]
  );
  const getSnapshot = () =>
    enabled && site
      ? earliestSession(cache.findAll({ queryKey: [LIVE_SESSIONS_KEY, site] }).map(query => query.state.data))
      : undefined;
  return useSyncExternalStore(subscribe, getSnapshot, () => undefined);
}

// Sites whose install card is up: waiting for the first pageview, or celebrating it until dismissed.
// LiveUserCount keeps its sessions list live for them, since useFirstSession names the first visitor from
// that list's cache, and an observed list is never garbage-collected from under the card. Kept here, not in
// LiveUserCount: switching dashboard tabs remounts LiveUserCount mid-journey, while NoData (layout) stays.
const liveSessionHolds = new Map<string, number>();
const liveSessionListeners = new Set<() => void>();

const notifyLiveSessionHolds = () => liveSessionListeners.forEach(listener => listener());

/** Keeps `site`'s live sessions list polling until the returned release runs. */
export function holdLiveSessions(site: string): () => void {
  liveSessionHolds.set(site, (liveSessionHolds.get(site) ?? 0) + 1);
  notifyLiveSessionHolds();
  let released = false;
  return () => {
    if (released) return;
    released = true;
    const count = (liveSessionHolds.get(site) ?? 1) - 1;
    if (count > 0) liveSessionHolds.set(site, count);
    else liveSessionHolds.delete(site);
    notifyLiveSessionHolds();
  };
}

/** Holds `site`'s live sessions list while `active` (NoData: while its install card is on screen). */
export function useHoldLiveSessions(site: string, active: boolean) {
  useEffect(() => (active && site ? holdLiveSessions(site) : undefined), [active, site]);
}

const subscribeLiveSessionHolds = (listener: () => void) => {
  liveSessionListeners.add(listener);
  return () => void liveSessionListeners.delete(listener);
};

/** Whether LiveUserCount keeps its sessions list polling with the drawer closed. */
export function useLiveSessionsForFirstVisitor(site: string): boolean {
  return useSyncExternalStore(
    subscribeLiveSessionHolds,
    () => !!site && liveSessionHolds.has(site),
    () => false
  );
}

/**
 * Shortly after arrival, refetch this site's analytics queries that are on screen and mark the rest
 * stale, so the dashboard fills in now rather than after their 60 s staleTime. Calls `onSettled` once
 * they land. Dismissing (or leaving) before the delay runs out starts the refetch at once.
 */
export function useArrivalRefresh(site: string, enabled: boolean, onSettled: () => void) {
  const queryClient = useQueryClient();

  useEffect(() => {
    if (!enabled || !site) return;
    let current = true;
    let started = false;
    const refresh = () => {
      if (started) return;
      started = true;
      void queryClient
        .invalidateQueries({ predicate: query => isSiteAnalyticsQueryKey(query.queryKey, site) })
        .then(() => {
          if (current) onSettled();
        });
    };
    const timeout = window.setTimeout(refresh, ARRIVAL_REFRESH_DELAY_MS);
    return () => {
      current = false;
      window.clearTimeout(timeout);
      refresh();
    };
  }, [enabled, onSettled, queryClient, site]);
}