Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

10.1 KB
Raw Blame
import { usePending } from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import {
  type Accessor,
  batch,
  createMemo,
  createRenderEffect,
  createSignal,
  on,
  onCleanup,
  untrack,
} from 'solid-js';
import { createStore, produce, reconcile } from 'solid-js/store';
import type { RecordSelection } from '../../../graphql-cache/exchange/record-selection';
import type { CacheHost } from '../../../graphql-cache/host/types';
import {
  type CacheRevision,
  type EntityFilterCacheArgs,
  parseCacheRevision,
} from '../../../graphql-cache/protocol';
import { createHiddenDeferral } from '../../visible-refresh';
import { soupCacheTelemetry } from './cache-activity-telemetry';

/** A declared source and generated fragment; no mutation-specific query updates. */
export type PredicateQueryRequest<T> = {
  source: Omit<EntityFilterCacheArgs, 'liveQuery' | 'mail'> & {
    baseline: NonNullable<EntityFilterCacheArgs['baseline']>;
  };
  select: RecordSelection<T>;
};

export type LiveQueryRow<T> = {
  recordKey: string;
  record: T;
  identity?: { mutationUuid: string | null; pending: boolean };
};

export type LiveQuerySnapshot<T> = {
  revision: CacheRevision;
  keys: readonly string[];
  records: readonly LiveQueryRow<T>[];
  retainedKeys: readonly string[];
  optimistic: boolean;
};

type LiveQueryHost = Pick<
  CacheHost,
  'entityFilter' | 'onCacheChanged' | 'onCacheGenerationChanged'
>;

export type PredicateQueryStatus =
  | 'idle'
  | 'loading'
  | 'ready'
  | 'unsupported'
  | 'error';
/**
 * Binds one cache-engine maintained view for `createSoupLiveQuery`. Owns
 * subscription, coalescing, generation recovery, and keyed Solid rows.
 *
 * Internal to the Soup query layer, not a general reactive query API: GraphQL
 * documents use `createLiveQuery`, and Soup lists use `createSoupLiveQuery`.
 */
export function createPredicateQuery<T extends object>(options: {
  host: Accessor<LiveQueryHost | undefined>;
  query: Accessor<PredicateQueryRequest<T> | undefined>;
}) {
  const [data, setData] = createSignal<LiveQuerySnapshot<T>>();
  const [status, setStatus] = createSignal<PredicateQueryStatus>('idle');
  const [error, setError] = createSignal<unknown>();
  let requestRefresh = () => {};
  // A caller may derive a new request object from a query snapshot even when
  // its actual membership evidence and selection have not changed.
  const query = createMemo(options.query, undefined, {
    equals: (previous, next) =>
      JSON.stringify(previous) === JSON.stringify(next),
  });

  createRenderEffect(
    on([query, options.host], ([request, host]) => {
      setData(undefined);
      setError(undefined);
      if (!request || !host) {
        setStatus('idle');
        requestRefresh = () => {};
        return;
      }
      const id = crypto.randomUUID();
      const [rows, setRows] = createStore<Record<string, LiveQueryRow<T>>>({});
      let keys: readonly string[] = [];
      let orderedRows: readonly LiveQueryRow<T>[] = [];
      let since: CacheRevision | undefined;
      let latest: CacheRevision | undefined;
      let epoch = 0;
      let active = true;
      let running = false;
      let pending = false;
      let unsupported = false;
      let runPromise: Promise<void> | undefined;
      const args = (release = false): EntityFilterCacheArgs => ({
        ...request.source,
        liveQuery: {
          id,
          ...request.select,
          since,
          ...(release ? { release } : {}),
        },
      });
      setStatus('loading');

      const run = async () => {
        if (running || !active) return;
        running = true;
        try {
          while (pending && active) {
            pending = false;
            const observedEpoch = epoch;
            let outcome: 'success' | 'unsupported' | 'error' | 'discarded' =
              'discarded';
            let upserts = 0;
            let patches = 0;
            let removed = 0;
            const startedAt = performance.now();
            try {
              const result = await host.entityFilter(args());
              if (!active || epoch !== observedEpoch) continue;
              if (result.kind !== 'live-query') {
                outcome = 'unsupported';
                unsupported = true;
                pending = false;
                setStatus('unsupported');
                continue;
              }
              upserts = result.upserts.length;
              patches = result.patches.length;
              removed = result.removed.length;
              const revision = parseCacheRevision(result.revision);
              if (latest !== undefined && BigInt(revision) < BigInt(latest)) {
                pending = true;
                continue;
              }
              if (result.reset && result.keys === undefined)
                throw new Error('live query reset omitted its keys');
              // Check row envelopes and patch bases before updating reactive state.
              for (const row of result.upserts) {
                if (
                  !row.recordKey ||
                  row.record === null ||
                  typeof row.record !== 'object' ||
                  Array.isArray(row.record)
                ) {
                  throw new Error('invalid live query record');
                }
              }
              for (const patch of result.patches) {
                if (result.reset || !untrack(() => rows[patch.recordKey]))
                  throw new Error('live query patch has no base row');
              }
              untrack(() =>
                batch(() => {
                  let orderChanged =
                    result.reset ||
                    result.keys !== undefined ||
                    result.removed.length > 0;
                  if (result.reset) setRows(reconcile({}));
                  for (const key of result.removed) setRows(key, undefined!);
                  for (const row of result.upserts) {
                    if (!rows[row.recordKey]) orderChanged = true;
                    setRows(
                      row.recordKey,
                      reconcile(row as LiveQueryRow<T>, {
                        key: 'id',
                        merge: true,
                      })
                    );
                  }
                  for (const patch of result.patches) {
                    setRows(
                      patch.recordKey,
                      produce((row) => {
                        for (const field of patch.fields) {
                          if (!field.path.length) {
                            row.record = field.value as T;
                            continue;
                          }
                          let parent: unknown = row.record;
                          for (const segment of field.path.slice(0, -1)) {
                            parent = (
                              parent as Record<string | number, unknown>
                            )[segment];
                          }
                          (parent as Record<string | number, unknown>)[
                            field.path[field.path.length - 1]
                          ] = field.value;
                        }
                        row.identity = patch.identity;
                      })
                    );
                  }
                  if (result.keys !== undefined) keys = result.keys;
                  if (orderChanged)
                    orderedRows = keys.flatMap((key) =>
                      rows[key] ? [rows[key]] : []
                    );
                  since = revision;
                  setData({
                    revision,
                    keys,
                    records: orderedRows,
                    retainedKeys: result.retainedKeys,
                    optimistic: result.optimistic,
                  });
                  setError(undefined);
                  setStatus('ready');
                })
              );
              outcome = 'success';
            } catch (cause) {
              if (!active || epoch !== observedEpoch) continue;
              outcome = 'error';
              setError(() => cause);
              setStatus('error');
            } finally {
              soupCacheTelemetry.record('predicate', {
                durationMs: performance.now() - startedAt,
                rows: orderedRows.length,
                upserts,
                patches,
                removed,
                error: outcome === 'error',
                discarded: outcome === 'discarded',
                incomplete: outcome === 'unsupported',
              });
            }
          }
        } finally {
          running = false;
        }
      };
      const refresh = () => {
        if (unsupported) return;
        pending = true;
        if (!running) runPromise = run();
      };
      requestRefresh = refresh;
      // Every open tab shares one cache engine. A hidden tab keeps a dirty bit
      // instead of reading on each revision; initial and explicit reads still run.
      const deferral = createHiddenDeferral(refresh);
      const unsubscribeChanges = host.onCacheChanged(
        (revision) => {
          latest = revision;
          deferral.request();
        },
        { includeHydration: true }
      );
      const unsubscribeGeneration = host.onCacheGenerationChanged(() => {
        epoch += 1;
        unsupported = false;
        since = undefined;
        latest = undefined;
        batch(() => {
          setData(undefined);
          setStatus('loading');
        });
        deferral.request();
      });
      refresh();
      onCleanup(() => {
        active = false;
        deferral.dispose();
        unsubscribeChanges();
        unsubscribeGeneration();
        // Serialize release after any pending read, so disposal cannot recreate
        // a view behind its cleanup. LRU eviction is a fallback for a lost host.
        const release = async () => {
          try {
            await runPromise;
            await host.entityFilter(args(true));
          } catch {
            /* Host may have retired. */
          }
        };
        fireAndForget(release(), 'soup-predicate-query');
      });
    })
  );
  usePending('soup.cache', () => status() === 'loading');
  return { data, status, error, refresh: () => requestRefresh() };
}