Skip to content

The Open Standard for Generative UI

19.0 KB
Raw Blame
// ─────────────────────────────────────────────────────────────────────────────
// Query Manager — reactive data fetching for openui-lang
// ─────────────────────────────────────────────────────────────────────────────

import type { OpenUIError } from "../parser/types";
import { McpToolError } from "./mcp";
import { ToolNotFoundError } from "./toolProvider";

/**
 * ToolProvider interface for Query() and Mutation() tool calls.
 * Framework-agnostic — works with MCP, REST, GraphQL, or any backend.
 *
 * @example
 * ```ts
 * // Function map (Renderer normalizes this automatically)
 * <Renderer toolProvider={{
 *   get_users: (args) => fetch(`/api/users`).then(r => r.json()),
 * }} />
 *
 * // MCP client (Renderer wraps extractToolResult automatically)
 * <Renderer toolProvider={mcpClient} />
 * ```
 */
export interface ToolProvider {
  callTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
}

// ── Public types ─────────────────────────────────────────────────────────────

export interface QueryNode {
  statementId: string;
  toolName: string;
  args: unknown;
  defaults: unknown;
  /** Evaluated dependency value — included in cache key to force re-fetch on change. */
  deps: unknown;
  /** Auto-refresh interval in seconds. */
  refreshInterval?: number;
  complete: boolean;
}

export interface MutationNode {
  statementId: string;
  toolName: string;
}

export interface MutationResult {
  status: "idle" | "loading" | "success" | "error";
  data?: unknown;
  error?: unknown;
}

export interface QuerySnapshot extends Record<string, unknown> {
  __openui_loading: string[];
  __openui_refetching: string[];
  __openui_errors: OpenUIError[];
}

export interface QueryManager {
  evaluateQueries(queryNodes: QueryNode[]): void;
  getResult(statementId: string): unknown;
  isLoading(statementId: string): boolean;
  isAnyLoading(): boolean;
  invalidate(statementIds?: string[]): void;
  registerMutations(nodes: MutationNode[]): void;
  fireMutation(
    statementId: string,
    evaluatedArgs: Record<string, unknown>,
    refreshQueryIds?: string[],
  ): Promise<boolean>;
  getMutationResult(statementId: string): MutationResult | null;
  subscribe(listener: () => void): () => void;
  getSnapshot(): QuerySnapshot;
  activate(): void;
  dispose(): void;
}

// ── Internal types ───────────────────────────────────────────────────────────

interface QueryEntry {
  toolName: string;
  args: unknown;
  defaults: unknown;
  cacheKey: string;
  prevCacheKey?: string;
  loading: boolean;
  everFetched: boolean;
  refreshInterval: number;
  timer?: ReturnType<typeof setInterval>;
  needsRefetch: boolean;
  error?: OpenUIError;
}

interface MutationEntry {
  toolName: string;
  result: MutationResult;
  error?: OpenUIError;
}

interface CacheEntry {
  data: unknown;
  inFlight: boolean;
}

// ── Utilities ────────────────────────────────────────────────────────────────

/** JSON.stringify with stable key ordering at all nesting levels. */
function stableStringify(value: unknown): string {
  return JSON.stringify(value, (_key: string, val: unknown) => {
    if (val && typeof val === "object" && !Array.isArray(val)) {
      const sorted: Record<string, unknown> = {};
      for (const k of Object.keys(val as object).sort()) {
        sorted[k] = (val as any)[k];
      }
      return sorted;
    }
    // Serialize non-JSON-safe primitives to stable strings.
    // evaluate() can pull arbitrary values from store/ref state,
    // including undefined in object literals and edge-case numbers.
    if (val === undefined) return "__undefined__";
    if (typeof val === "number") {
      if (Number.isNaN(val)) return "__NaN__";
      if (val === Infinity) return "__Inf__";
      if (val === -Infinity) return "__-Inf__";
    }
    return val;
  });
}

function buildCacheKey(toolName: string, args: unknown, deps: unknown): string {
  const depsKey = deps != null ? "::" + stableStringify(deps) : "";
  return toolName + "::" + stableStringify(args) + depsKey;
}

// ── Factory ──────────────────────────────────────────────────────────────────

export function createQueryManager(toolProvider: ToolProvider | null): QueryManager {
  const queries = new Map<string, QueryEntry>();
  const mutations = new Map<string, MutationEntry>();
  const cache = new Map<string, CacheEntry>();
  const listeners = new Set<() => void>();

  let snapshot: QuerySnapshot = {
    __openui_loading: [],
    __openui_refetching: [],
    __openui_errors: [],
  };
  let snapshotJson = JSON.stringify(snapshot);
  let disposed = false;
  let generation = 0;

  // ── Snapshot & notification ──────────────────────────────────────────────

  function rebuildSnapshot(): boolean {
    const out: QuerySnapshot = {
      __openui_loading: [],
      __openui_refetching: [],
      __openui_errors: [],
    };

    for (const [sid, q] of queries) {
      const entry = cache.get(q.cacheKey);
      if (entry && entry.data !== undefined) {
        // Use settled data (even while refetching — shows last good value)
        out[sid] = entry.data;
      } else if (q.prevCacheKey) {
        const prev = cache.get(q.prevCacheKey);
        if (prev && prev.data !== undefined) {
          out[sid] = prev.data;
        } else {
          out[sid] = q.defaults;
        }
      } else {
        out[sid] = q.defaults;
      }
      if (q.loading) {
        out.__openui_loading.push(sid);
        if (q.everFetched) out.__openui_refetching.push(sid);
      }
      if (q.error) out.__openui_errors.push(q.error);
    }

    for (const [sid, m] of mutations) {
      out[sid] = m.result;
      if (m.error) out.__openui_errors.push(m.error);
    }

    try {
      const outJson = JSON.stringify(out);
      if (outJson === snapshotJson) return false;
      snapshot = out;
      snapshotJson = outJson;
    } catch {
      snapshot = out;
      snapshotJson = "";
    }
    return true;
  }

  function notify() {
    for (const listener of [...listeners]) {
      listener();
    }
  }

  // ── Fetch execution ──────────────────────────────────────────────────────

  async function executeFetch(cacheKey: string, statementId: string) {
    if (!toolProvider) return;

    const q = queries.get(statementId);
    if (!q) return;

    // Capture the cache key at fetch start — if the query's key changes
    // while we're in-flight (deps changed), this fetch is stale.
    const fetchKey = cacheKey;
    const toolName = q.toolName;
    const args = q.args;

    // Mark in-flight — use undefined as "no data yet" sentinel (distinct from null)
    let entry = cache.get(fetchKey);
    if (!entry) {
      entry = { data: undefined, inFlight: true };
      cache.set(fetchKey, entry);
    } else {
      entry.inFlight = true;
    }
    q.loading = true;
    rebuildSnapshot();
    notify();

    try {
      const data = await toolProvider.callTool(toolName, (args as Record<string, unknown>) ?? {});
      if (disposed) return;
      // Query removed or moved to a different cache key while in-flight — discard
      const current = queries.get(statementId);
      if (!current || current.cacheKey !== fetchKey) {
        entry.inFlight = false;
        return;
      }

      entry.data = data ?? null;
      current.everFetched = true;
      current.error = undefined;

      // Clean up previous cache entry — clear prevCacheKey FIRST so
      // cleanupCacheEntry doesn't see this query as a live reference.
      if (current.prevCacheKey && current.prevCacheKey !== fetchKey) {
        const prevKey = current.prevCacheKey;
        current.prevCacheKey = undefined;
        cleanupCacheEntry(prevKey);
      }
    } catch (err) {
      // Only update error state if this fetch is still current
      const current = queries.get(statementId);
      if (current && current.cacheKey === fetchKey) {
        if (err instanceof ToolNotFoundError) {
          current.error = {
            source: "query",
            code: "tool-not-found",
            message: `Query tool "${toolName}" not found`,
            statementId,
            component: "Query",
            toolName,
            hint: err.availableTools.length
              ? `Available tools: ${err.availableTools.join(", ")}`
              : undefined,
          };
        } else if (err instanceof McpToolError) {
          current.error = {
            source: "query",
            code: "mcp-error",
            message: `Query "${toolName}" returned an error: ${err.toolErrorText}`,
            statementId,
            component: "Query",
            toolName,
          };
        } else {
          const msg = err instanceof Error ? err.message : String(err);
          current.error = {
            source: "query",
            code: "tool-error",
            message: `Query "${toolName}" failed: ${msg}`,
            statementId,
            component: "Query",
            toolName,
          };
        }
      }
      console.error(`Query "${toolName}" failed:`, err);
    } finally {
      entry.inFlight = false;
      const current = queries.get(statementId);
      // Only clear loading if this fetch is still current
      if (current && current.cacheKey === fetchKey) {
        current.loading = false;
        if (rebuildSnapshot()) notify();
        // Re-fetch if invalidation occurred while in-flight
        if (current.needsRefetch) {
          current.needsRefetch = false;
          executeFetch(current.cacheKey, statementId);
        }
      } else {
        if (rebuildSnapshot()) notify();
      }
    }
  }

  /** Remove a cache entry if no query references it. */
  function cleanupCacheEntry(cacheKey: string) {
    for (const q of queries.values()) {
      if (q.cacheKey === cacheKey || q.prevCacheKey === cacheKey) return;
    }
    cache.delete(cacheKey);
  }

  // ── Query evaluation ─────────────────────────────────────────────────────

  function evaluateQueries(queryNodes: QueryNode[]) {
    if (disposed) return;

    const activeIds = new Set(queryNodes.map((n) => n.statementId));

    // Clean up removed queries
    for (const [sid, q] of queries) {
      if (!activeIds.has(sid)) {
        if (q.timer) clearInterval(q.timer);
        queries.delete(sid);
        // Clean up cache entries that are no longer referenced
        cleanupCacheEntry(q.cacheKey);
        if (q.prevCacheKey) cleanupCacheEntry(q.prevCacheKey);
      }
    }

    // Process active queries
    for (const node of queryNodes) {
      if (!node.complete) continue;

      const cacheKey = buildCacheKey(node.toolName, node.args, node.deps);
      const existing = queries.get(node.statementId);

      if (existing) {
        // Track previous cache key for fallback display
        if (existing.cacheKey !== cacheKey) {
          existing.prevCacheKey = existing.cacheKey;
        }
        existing.toolName = node.toolName;
        existing.args = node.args;
        existing.defaults = node.defaults;
        existing.cacheKey = cacheKey;
      } else {
        queries.set(node.statementId, {
          toolName: node.toolName,
          args: node.args,
          defaults: node.defaults,
          cacheKey,
          loading: false,
          everFetched: false,
          refreshInterval: 0,
          needsRefetch: false,
        });
      }

      const q = queries.get(node.statementId)!;

      // Fire fetch if no settled data and not already in-flight
      const entry = cache.get(cacheKey);
      const hasSettledData = entry && entry.data !== undefined && !entry.inFlight;
      if (toolProvider && !hasSettledData && !entry?.inFlight) {
        executeFetch(cacheKey, node.statementId);
      }

      // Configure auto-refresh timer
      const newInterval = node.refreshInterval ?? 0;
      if (newInterval !== q.refreshInterval) {
        if (q.timer) {
          clearInterval(q.timer);
          q.timer = undefined;
        }
        if (newInterval > 0) {
          q.timer = setInterval(() => {
            if (disposed || !toolProvider) return;
            const entry = cache.get(q.cacheKey);
            if (!entry?.inFlight) {
              executeFetch(q.cacheKey, node.statementId);
            }
          }, newInterval * 1000);
        }
        q.refreshInterval = newInterval;
      }
    }

    if (rebuildSnapshot()) notify();
  }

  // ── Query accessors ──────────────────────────────────────────────────────

  function getResult(statementId: string): unknown {
    const q = queries.get(statementId);
    if (!q) return null;
    const entry = cache.get(q.cacheKey);
    if (entry && entry.data !== undefined) return entry.data;
    // Fall back to previous cache entry while loading
    if (q.prevCacheKey) {
      const prev = cache.get(q.prevCacheKey);
      if (prev && prev.data !== undefined) return prev.data;
    }
    return q.defaults;
  }

  function isLoading(statementId: string): boolean {
    return queries.get(statementId)?.loading ?? false;
  }

  function isAnyLoading(): boolean {
    for (const q of queries.values()) {
      if (q.loading) return true;
    }
    return false;
  }

  function invalidate(statementIds?: string[]) {
    if (disposed || !toolProvider) return;

    const targets = statementIds?.length
      ? statementIds.filter((sid) => queries.has(sid))
      : [...queries.keys()];

    for (const sid of targets) {
      const q = queries.get(sid);
      if (!q) continue;
      const entry = cache.get(q.cacheKey);
      if (entry?.inFlight) {
        q.needsRefetch = true;
      } else {
        executeFetch(q.cacheKey, sid);
      }
    }
  }

  // ── Mutation methods ─────────────────────────────────────────────────────

  function registerMutations(nodes: MutationNode[]) {
    const activeIds = new Set(nodes.map((n) => n.statementId));

    // Clean up removed mutations
    for (const sid of mutations.keys()) {
      if (!activeIds.has(sid)) mutations.delete(sid);
    }

    // Register/update active mutations
    for (const node of nodes) {
      const existing = mutations.get(node.statementId);
      if (existing) {
        if (existing.toolName !== node.toolName) {
          existing.toolName = node.toolName;
          existing.result = { status: "idle", data: null, error: null };
          existing.error = undefined;
        }
      } else {
        mutations.set(node.statementId, {
          toolName: node.toolName,
          result: { status: "idle" },
        });
      }
    }

    if (rebuildSnapshot()) notify();
  }

  async function fireMutation(
    statementId: string,
    evaluatedArgs: Record<string, unknown>,
    refreshQueryIds?: string[],
  ): Promise<boolean> {
    if (disposed || !toolProvider) return false;
    const m = mutations.get(statementId);
    if (!m) return false;

    // Reject concurrent calls on the same mutation — prevents double-submit
    if (m.result.status === "loading") return false;

    const gen = generation;

    m.result = { status: "loading" };
    rebuildSnapshot();
    notify();

    let success = false;
    try {
      const data = await toolProvider.callTool(m.toolName, evaluatedArgs);
      if (disposed || gen !== generation) return false;
      m.result = { status: "success", data };
      m.error = undefined;
      success = true;
    } catch (err) {
      if (disposed || gen !== generation) return false;
      const msg = err instanceof Error ? err.message : String(err);
      m.result = { status: "error", error: msg };
      if (err instanceof ToolNotFoundError) {
        m.error = {
          source: "mutation",
          code: "tool-not-found",
          message: `Mutation tool "${m.toolName}" not found`,
          statementId,
          component: "Mutation",
          toolName: m.toolName,
          hint: err.availableTools.length
            ? `Available tools: ${err.availableTools.join(", ")}`
            : undefined,
        };
      } else if (err instanceof McpToolError) {
        m.error = {
          source: "mutation",
          code: "mcp-error",
          message: `Mutation "${m.toolName}" returned an error: ${err.toolErrorText}`,
          statementId,
          component: "Mutation",
          toolName: m.toolName,
        };
      } else {
        m.error = {
          source: "mutation",
          code: "tool-error",
          message: `Mutation "${m.toolName}" failed: ${msg}`,
          statementId,
          component: "Mutation",
          toolName: m.toolName,
        };
      }
    }

    rebuildSnapshot();
    notify();

    if (success && refreshQueryIds?.length) {
      invalidate(refreshQueryIds);
    }

    return success;
  }

  function getMutationResult(statementId: string): MutationResult | null {
    return mutations.get(statementId)?.result ?? null;
  }

  // ── Pub/sub ──────────────────────────────────────────────────────────────

  function subscribe(listener: () => void): () => void {
    listeners.add(listener);
    return () => listeners.delete(listener);
  }

  function getSnapshot(): QuerySnapshot {
    return snapshot;
  }

  // ── Lifecycle ────────────────────────────────────────────────────────────

  function activate() {
    disposed = false;
  }

  function dispose() {
    disposed = true;
    generation++;
    listeners.clear();
    // Clear timers and transient state, preserve cache + query entries for Strict Mode re-attach
    for (const q of queries.values()) {
      if (q.timer) {
        clearInterval(q.timer);
        q.timer = undefined;
      }
      q.refreshInterval = 0;
      q.loading = false;
      q.needsRefetch = false;
    }
    mutations.clear();
  }

  return {
    evaluateQueries,
    getResult,
    isLoading,
    isAnyLoading,
    invalidate,
    registerMutations,
    fireMutation,
    getMutationResult,
    subscribe,
    getSnapshot,
    activate,
    dispose,
  };
}