types.ts

/**
 * Shared types for query-cache-inspector.
 *
 * These describe the *serialized*, JSON-safe view of a TanStack Query cache that
 * travels from the inspected page all the way to the DevTools panel. Nothing in
 * here depends on the DOM or on chrome APIs, so it is reused by the extension,
 * the standalone demo, and the unit tests alike.
 */

/** TanStack Query's `state.status` — the data lifecycle of a query. */
export type QueryStatus = "pending" | "success" | "error";

/** TanStack Query's `state.fetchStatus` — whether a fetch is happening right now. */
export type FetchStatus = "fetching" | "paused" | "idle";

/**
 * The single, human-facing status we render as a colored badge. Derived from the
 * raw `status` / `fetchStatus` / staleness / observer count (see `status.ts`).
 */
export type DerivedStatus = "fresh" | "stale" | "fetching" | "inactive";

/** A JSON-safe snapshot of one query in the cache. */
export interface QuerySnapshot {
  /** Stable hash TanStack Query assigns to the (serialized) query key. */
  queryHash: string;
  /** The query key, coerced to a JSON-safe value. */
  queryKey: unknown;
  status: QueryStatus;
  fetchStatus: FetchStatus;
  /** Result of `query.isStale()` at snapshot time. */
  isStale: boolean;
  /** Whether at least one mounted observer is subscribed. */
  isActive: boolean;
  /** Number of observers (mounted `useQuery` hooks) watching this query. */
  observers: number;
  /** Epoch ms of the last successful data update (0 if never). */
  dataUpdatedAt: number;
  /** Epoch ms of the last error (0 if never). */
  errorUpdatedAt: number;
  /** The badge status we render. */
  derived: DerivedStatus;
  /** Truncated, JSON-safe preview of `state.data` (undefined if none). */
  dataPreview?: string;
  /** Stringified error message, if the query is in an error state. */
  error?: string;
}

/** A full snapshot of the cache at a moment in time. */
export interface CacheSnapshot {
  /** Epoch ms the snapshot was taken. */
  takenAt: number;
  queries: QuerySnapshot[];
}

/**
 * The event types TanStack Query's `QueryCache.subscribe` emits. We keep the
 * full union so the panel can label events precisely, but the store collapses
 * them into add / update / remove semantics.
 */
export type CacheEventType =
  | "added"
  | "removed"
  | "updated"
  | "observerAdded"
  | "observerRemoved"
  | "observerResultsUpdated"
  | "observerOptionsUpdated";

/** A JSON-safe record of one cache event, for the live event log. */
export interface CacheEvent {
  /** Monotonic id assigned by the store, for stable React-free keying. */
  id: number;
  /** Epoch ms the event was observed. */
  at: number;
  type: CacheEventType;
  queryHash: string;
  queryKey: unknown;
  status?: QueryStatus;
  fetchStatus?: FetchStatus;
}

/** Message envelope used across the page → content → background → panel hops. */
export interface Envelope {
  /** Marks the sender so each hop can filter foreign messages. */
  source: "qci-page" | "qci-content" | "qci-panel" | "qci-background";
  kind: "snapshot" | "event" | "hello" | "ping" | "detected" | "not-detected";
  tabId?: number;
  snapshot?: CacheSnapshot;
  event?: CacheEvent;
  detail?: string;
}