@agent-native/core-corpus 0.209.2 → 0.209.3-nightly-20261016183441

package/corpus/templates/analytics/app/lib/sql-query-freshness.ts

@@ -0,0 +1,85 @@
+import type { DataSourceType } from "@/pages/adhoc/sql-dashboard/types";
+
+export type SqlQueryCacheStatus =
+  | "live"
+  | "app-cache"
+  | "provider-cache"
+  | "restored"
+  | "unknown";
+
+export interface SqlQueryFreshness {
+  /** When the app received these rows; absent when the source did not say. */
+  fetchedAt?: string;
+  cache: SqlQueryCacheStatus;
+}
+
+export interface SqlQueryFreshnessInput {
+  fetchedAt?: string;
+  cached?: boolean;
+  providerCacheHit?: boolean;
+}
+
+/**
+ * What a result can honestly say about its age. BigQuery always reports a
+ * fetch time and cache state, so a missing one is shown as unknown. Other
+ * sources report neither, and for them a missing value means "not applicable",
+ * so nothing is shown unless the result carries metadata or is a saved copy.
+ */
+export function describeSqlQueryFreshness(
+  result: SqlQueryFreshnessInput | undefined,
+  options: { source: DataSourceType; restored: boolean },
+): SqlQueryFreshness | undefined {
+  if (!result) return undefined;
+  const { fetchedAt, cached, providerCacheHit } = result;
+  if (options.restored) return { fetchedAt, cache: "restored" };
+  const bigQuery = options.source === "bigquery";
+  if (
+    !bigQuery &&
+    fetchedAt === undefined &&
+    cached === undefined &&
+    providerCacheHit === undefined
+  ) {
+    return undefined;
+  }
+  if (cached === true) return { fetchedAt, cache: "app-cache" };
+  if (providerCacheHit === true) return { fetchedAt, cache: "provider-cache" };
+  if (providerCacheHit === false || !bigQuery) {
+    return { fetchedAt, cache: "live" };
+  }
+  return { fetchedAt, cache: "unknown" };
+}
+
+/**
+ * A result older than this gets an inline age label on its panel; one exactly
+ * this old is still routine. The one place to change when the cutoff moves.
+ */
+export const STALE_RESULT_AGE_MS = 60 * 60 * 1000;
+
+function fetchedAtMs(fetchedAt: string | undefined): number | undefined {
+  if (fetchedAt === undefined) return undefined;
+  const ms = Date.parse(fetchedAt);
+  return Number.isFinite(ms) ? ms : undefined;
+}
+
+/**
+ * Whether a result is older than `STALE_RESULT_AGE_MS`. An unknown or
+ * unreadable fetch time is not stale: an age that cannot be known is never
+ * invented, and a fetch time in the future (a skewed clock) is not old.
+ */
+export function isStaleFetchTime(
+  fetchedAt: string | undefined,
+  now: number,
+): boolean {
+  const fetched = fetchedAtMs(fetchedAt);
+  return fetched !== undefined && now - fetched > STALE_RESULT_AGE_MS;
+}
+
+/** Milliseconds until the result turns stale; undefined when it cannot. */
+export function msUntilStale(
+  fetchedAt: string | undefined,
+  now: number,
+): number | undefined {
+  const fetched = fetchedAtMs(fetchedAt);
+  if (fetched === undefined) return undefined;
+  return Math.max(0, fetched + STALE_RESULT_AGE_MS + 1 - now);
+}

package/corpus/templates/analytics/app/lib/sql-query-snapshot-session.ts

@@ -0,0 +1,145 @@
+import { isSigningOut } from "@agent-native/core/client/hooks";
+
+import {
+  dashboardCacheScope,
+  type DashboardCacheSession,
+} from "./prefetch-keys";
+import {
+  clearSqlQuerySnapshots,
+  readSqlQuerySnapshot,
+  removeSqlQuerySnapshot,
+  writeSqlQuerySnapshot,
+  type SqlQuerySnapshotClear,
+  type SqlQuerySnapshotInput,
+  type SqlQuerySnapshotRead,
+  type SqlQuerySnapshotWrite,
+} from "./sql-query-cache";
+
+/**
+ * Ties the saved SQL results to the signed-in account.
+ *
+ * The scope is module state rather than a hook ref because a late result can
+ * land after the component that asked for it is gone: sign-out unmounts the
+ * whole app shell, and a ref in an unmounted component would still hold the
+ * old scope. `undefined` means nothing has bound a scope yet and `null` means
+ * the session ended; both refuse writes.
+ */
+let boundScope: string | null | undefined;
+
+export type SqlQuerySnapshotSessionStatus =
+  | "loading"
+  | "authenticated"
+  | "unauthenticated"
+  | "unavailable"
+  | "signing-out";
+
+/**
+ * Called from a component mounted outside the session gate, since the gate
+ * unmounts everything under it before a sign-out reaches an effect there.
+ * Loading and unavailable are transient and change nothing, so a reload keeps
+ * the saved results it is about to restore.
+ */
+export function syncSqlQuerySnapshotsToSession(input: {
+  status: SqlQuerySnapshotSessionStatus;
+  session: DashboardCacheSession | null;
+}): SqlQuerySnapshotClear | undefined {
+  if (input.status === "authenticated" && input.session) {
+    const accountScope = dashboardCacheScope(input.session);
+    boundScope = accountScope;
+    return warnIfNotCleared(
+      clearSqlQuerySnapshots({ exceptAccountScope: accountScope }),
+    );
+  }
+  if (input.status === "unauthenticated" || input.status === "signing-out") {
+    boundScope = null;
+    return warnIfNotCleared(clearSqlQuerySnapshots());
+  }
+  return undefined;
+}
+
+/** Whether a result fetched for `accountScope` may still be saved. */
+export function canWriteSqlQuerySnapshot(accountScope: string): boolean {
+  return boundScope === accountScope && !isSigningOut();
+}
+
+export function readSqlQuerySnapshotForSession(options: {
+  accountScope: string;
+  queryKey: string;
+}): SqlQuerySnapshotRead {
+  const read = readSqlQuerySnapshot(options);
+  if (read.status === "unavailable") {
+    console.warn("[sql-query] saved results unavailable", {
+      reason: read.reason,
+      errorName: read.errorName,
+    });
+  } else if (read.status === "miss" && isUnexpectedMiss(read.reason)) {
+    console.warn("[sql-query] dropped an unusable saved result", {
+      reason: read.reason,
+    });
+  }
+  return read;
+}
+
+export function removeSqlQuerySnapshotForSession(options: {
+  accountScope: string;
+  queryKey: string;
+}): SqlQuerySnapshotClear {
+  return warnIfNotCleared(removeSqlQuerySnapshot(options));
+}
+
+export function writeSqlQuerySnapshotForSession(options: {
+  accountScope: string;
+  queryKey: string;
+  result: SqlQuerySnapshotInput;
+  /** A query cancelled after its result arrived must not save it. */
+  signal?: AbortSignal;
+}): SqlQuerySnapshotWrite | { status: "skipped"; reason: "session-changed" } {
+  if (
+    options.signal?.aborted ||
+    !canWriteSqlQuerySnapshot(options.accountScope)
+  ) {
+    return { status: "skipped", reason: "session-changed" };
+  }
+  const write = writeSqlQuerySnapshot({
+    accountScope: options.accountScope,
+    queryKey: options.queryKey,
+    result: options.result,
+  });
+  if (write.status === "unavailable") {
+    console.warn("[sql-query] could not save the result", {
+      reason: write.reason,
+      errorName: write.errorName,
+    });
+  } else if (
+    write.status === "skipped" &&
+    (write.reason === "invalid-result" || write.reason === "invalid-fetched-at")
+  ) {
+    console.warn("[sql-query] result not saved", { reason: write.reason });
+  }
+  return write;
+}
+
+/** Absent, expired and another account's copy are ordinary; the rest are not. */
+function isUnexpectedMiss(reason: string): boolean {
+  return (
+    reason === "corrupt" ||
+    reason === "oversized" ||
+    reason === "truncated" ||
+    reason === "unsupported-version"
+  );
+}
+
+function warnIfNotCleared(clear: SqlQuerySnapshotClear): SqlQuerySnapshotClear {
+  if (clear.status === "unavailable") {
+    console.warn("[sql-query] could not clear saved results", {
+      reason: clear.reason,
+      errorName: clear.errorName,
+    });
+  }
+  return clear;
+}
+
+/** @internal test seam: forgets the bound scope between tests. */
+export function resetSqlQuerySnapshotSessionForTests(): void {
+  boundScope = undefined;
+}