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.

refactor(web): one default reactive query API per data shape (#7823)

teo440b65f52969
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index 996c83193a..29c625fcf0 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -66,6 +66,9 @@ Then trigger the interaction and read `window.__inst.log`. `'1,2,3' → '' → '
- All API/network calls live in service-clients.
- Shared server-state queries and mutations live in `src/lib/queries`; keep
feature-specific query orchestration with its owning feature.
+- Reactive GraphQL reads use `createLiveQuery` for a document and
+ `useSoupAstItemsQuery` (backed by `createSoupLiveQuery`) for Soup lists; see
+ [choosing a reactive read](docs/graphql-normalized-cache-plan.md#choosing-a-reactive-read).
- When adding or changing a feature flag, follow the `define-feature-flag` skill.
- When adding or changing a view's feature tour, follow the `add-tour` skill.
diff --git a/apps/web/docs/graphql-cache-testing.md b/apps/web/docs/graphql-cache-testing.md
index 78a13d0576..d2de4e5983 100644
--- a/apps/web/docs/graphql-cache-testing.md
+++ b/apps/web/docs/graphql-cache-testing.md
@@ -54,7 +54,8 @@ nix develop --command env -u SQLX_OFFLINE cargo test -p cache-turso
From `apps/web`:
```sh
-nix develop --command bunx vitest run src/lib/graphql-cache src/lib/urql-solid src/lib/queries/properties
+nix develop --command bunx vitest run src/lib/graphql-cache src/lib/urql-solid src/lib/queries/properties \
+ src/lib/queries/soup/graphql/create-predicate-query.test.ts src/lib/queries/soup/create-keyed-projection.test.ts
```
By default, Proptest generates 256 sequences and fast-check generates 250. The
diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.md
index 7093572fae..728977afc7 100644
--- a/apps/web/docs/graphql-normalized-cache-plan.md
+++ b/apps/web/docs/graphql-normalized-cache-plan.md
@@ -367,6 +367,7 @@ apps/web/tauri/graphql_cache_plugin/ # tauri commands + engine thread wrapping
apps/web/src/lib/graphql-cache/ # JS glue
host/ # CacheHost interface + worker & tauri transports
exchange/ # urql normalizedCacheExchange
+ solid/ # createLiveQuery, the reactive document query
worker/ # SharedWorker entry + worker core
```
@@ -545,6 +546,24 @@ benchmark were **skipped by decision**.
## 8. Live query API
+### Choosing a reactive read
+
+Use one default per data shape:
+
+| Data shape | Default | Notes |
+| --- | --- | --- |
+| GraphQL document | `createLiveQuery` from `@graphql-cache/solid/create-live-query` | Cursor-paginated documents use `createUrqlInfiniteQuery` from `@app/lib/urql-solid`. |
+| Soup list | `createSoupLiveQuery` | Feature code reads it through `useSoupAstItemsQuery`, which adds the GraphQL Soup flag, REST fallback, grouping, and entity mapping. |
+
+`createLiveQuery` is a document-first wrapper over `createUrqlQuery`: the
+document and variables are arguments, other options pass through, and the result
+and live projection path are the same. Existing `createUrqlQuery` call sites are
+already live and need no migration; new single-document reads use
+`createLiveQuery`. Soup's maintained-view binding and keyed row projection are
+internal to `src/lib/queries/soup/`, not general query APIs.
+
+### Usage
+
Use a generated document and reactive variables. The normal urql provider can
supply the client; pass `client` when using a service-specific client.
@@ -557,13 +576,6 @@ const accountQuery = createLiveQuery(
// Access inside a reactive computation or JSX; don't destructure store fields.
const accounts = () => accountQuery.data?.user.emailLinks ?? [];
-
-const soupPage = createLiveQuery(
- SoupDocument,
- () => ({ input: { initial: { limit: 100, sortMethod: 'UPDATED_AT' } } }),
- () => ({ client: getGraphqlSoupClient() })
-);
-const items = () => soupPage.data?.user.soup.items ?? [];
```
`undefined` variables pause a query. Changing variables creates a separate cache
@@ -673,10 +685,11 @@ never starts a network request.
The generic projection reflects cached GraphQL results. It does not infer server
resolver logic, authorization, aggregates, full-text ranking, or whether an entity
belongs in an arbitrary filtered/paginated list. Such changes need a declared
-domain collection policy or server revalidation. An explicit Soup page above
-retains its server-provided membership; the existing `createSoupLiveQuery` source
-adds Soup's local membership, ordering, pagination and Mail policy through its
-predicate adapter. That policy remains outside generic cache-core.
+domain collection policy or server revalidation. A Soup page read as a plain
+document would retain its server-provided membership, which is why Soup lists
+use `createSoupLiveQuery`: it adds Soup's local membership, ordering, pagination
+and Mail policy through its predicate adapter. That policy remains outside
+generic cache-core.
Network responses must provide the schema's identity fields (usually `id`, and
`__typename` for abstract types) for normalization. They are not automatically
diff --git a/apps/web/src/features/soup/collection/row-store.ts b/apps/web/src/features/soup/collection/row-store.ts
index cb41f7697b..7d02c58539 100644
--- a/apps/web/src/features/soup/collection/row-store.ts
+++ b/apps/web/src/features/soup/collection/row-store.ts
@@ -1,4 +1,4 @@
-import { createKeyedProjection } from '@app/lib/urql-solid/create-keyed-projection';
+import { createKeyedProjection } from '@app/lib/queries/soup/create-keyed-projection';
import type { Accessor } from 'solid-js';
/** Stable row identity, with independent tracking and reconciliation per row. */
diff --git a/apps/web/src/lib/graphql-cache/exchange/live-query.test.ts b/apps/web/src/lib/graphql-cache/exchange/live-query.test.ts
index b1afccca56..af804c277f 100644
--- a/apps/web/src/lib/graphql-cache/exchange/live-query.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/live-query.test.ts
@@ -2,7 +2,7 @@ import { gql } from '@urql/core';
import fc from 'fast-check';
import { createComputed, createRoot } from 'solid-js';
import { describe, expect, it } from 'vitest';
-import { createKeyedProjection } from '../../urql-solid/create-keyed-projection';
+import { createKeyedProjection } from '../../queries/soup/create-keyed-projection';
import { supportsStoreReconciliation } from '../../urql-solid/reactive-selection';
import { LiveQuery, querySnapshot } from './live-query';
import { applyQueryPatches } from './query-patches';
diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.ts
index a1cf25d2bf..cabaa3cacc 100644
--- a/apps/web/src/lib/graphql-cache/index.ts
+++ b/apps/web/src/lib/graphql-cache/index.ts
@@ -1,6 +1,9 @@
/**
* Normalized GraphQL cache — JS glue.
* Design doc: apps/web/docs/graphql-normalized-cache-plan.md
+ *
+ * The reactive document query, `createLiveQuery`, is imported from
+ * `./solid/create-live-query`; it is not re-exported here.
*/
export {
@@ -97,8 +100,3 @@ export {
validateCacheSearchArgs,
validateRecordSelectionKeys,
} from './protocol';
-
-export {
- createLiveQuery,
- type LiveQueryOptions,
-} from './solid/create-live-query';
diff --git a/apps/web/src/lib/graphql-cache/solid/create-live-query.ts b/apps/web/src/lib/graphql-cache/solid/create-live-query.ts
index f5187864be..7e37d7c78b 100644
--- a/apps/web/src/lib/graphql-cache/solid/create-live-query.ts
+++ b/apps/web/src/lib/graphql-cache/solid/create-live-query.ts
@@ -1,3 +1,18 @@
+/**
+ * Reactive GraphQL reads have one default per data shape:
+ *
+ * - A GraphQL document: `createLiveQuery` (this module). Cursor-paginated
+ * documents use `createUrqlInfiniteQuery` from `@app/lib/urql-solid`.
+ * - A Soup list: `createSoupLiveQuery` is the GraphQL source. Feature code
+ * reads it through `useSoupAstItemsQuery`, which adds the GraphQL Soup flag,
+ * REST fallback, grouping, and entity mapping.
+ *
+ * `createLiveQuery` is a document-first wrapper over `createUrqlQuery`. Both
+ * are live through the normalized-cache exchange, so existing `createUrqlQuery`
+ * callers keep working without migration. See "8. Live query API" in
+ * apps/web/docs/graphql-normalized-cache-plan.md.
+ */
+
import type { AnyVariables, DocumentInput } from '@urql/core';
import type { Accessor } from 'solid-js';
import { createUrqlQuery } from '../../urql-solid/create-urql-query';
diff --git a/apps/web/src/lib/graphql-cache/solid/create-query-signal.test.ts b/apps/web/src/lib/graphql-cache/solid/create-query-signal.test.ts
deleted file mode 100644
index 80c8024e6f..0000000000
--- a/apps/web/src/lib/graphql-cache/solid/create-query-signal.test.ts
+++ /dev/null
@@ -1,140 +0,0 @@
-import { type Client, CombinedError, type OperationResult } from '@urql/core';
-import { createRoot, createSignal } from 'solid-js';
-import { afterEach, describe, expect, it } from 'vitest';
-import { makeSubject } from 'wonka';
-import { createQuerySignal, type QuerySignal } from './create-query-signal';
-
-type FakeResult = Omit<Partial<OperationResult>, 'data'> & {
- // GraphQL permits a root-level null response even though urql's operation
- // result type models missing data as undefined.
- data?: OperationResult['data'] | null;
-};
-
-/**
- * Fake urql client: each `query()` call returns a fresh subject the test
- * pushes results into, mimicking the long-lived sources the normalized
- * cache exchange re-emits on.
- */
-function makeFakeClient() {
- const executions: Array<{
- variables: unknown;
- next: (result: FakeResult) => void;
- }> = [];
- const client = {
- query: (_document: unknown, variables: unknown) => {
- const subject = makeSubject<FakeResult>();
- executions.push({ variables, next: subject.next });
- return subject.source;
- },
- } as unknown as Client;
- return { client, executions };
-}
-
-const DOCUMENT = {} as never;
-
-type Variables = { cursor: string | null };
-
-// Note: signal writes and result pushes must happen OUTSIDE the createRoot
-// body — solid batches the body, deferring effect re-runs until it returns.
-function setup() {
- const { client, executions } = makeFakeClient();
- let query!: QuerySignal<unknown>;
- let setVariables!: (v: Variables | undefined) => void;
- const dispose = createRoot((dispose) => {
- const [variables, setVars] = createSignal<Variables | undefined>({
- cursor: null,
- });
- setVariables = setVars;
- query = createQuerySignal({
- client: () => client,
- document: DOCUMENT,
- variables,
- });
- return dispose;
- });
- return { executions, query, setVariables, dispose };
-}
-
-let dispose: (() => void) | undefined;
-afterEach(() => {
- dispose?.();
- dispose = undefined;
-});
-
-describe('createQuerySignal', () => {
- it('tracks results pushed over the operation lifetime', () => {
- const harness = setup();
- dispose = harness.dispose;
- const { query, executions } = harness;
-
- expect(query.fetching()).toBe(true);
- expect(query.data()).toBeUndefined();
- expect(executions).toHaveLength(1);
-
- // Stale cache hit first…
- executions[0]?.next({ data: { from: 'cache' }, stale: true });
- expect(query.data()).toEqual({ from: 'cache' });
- expect(query.stale()).toBe(true);
- expect(query.fetching()).toBe(false);
-
- // …then the network result, then a cache-pushed re-execution.
- executions[0]?.next({ data: { from: 'network' }, stale: false });
- expect(query.data()).toEqual({ from: 'network' });
- executions[0]?.next({ data: { from: 'optimistic' }, stale: false });
- expect(query.data()).toEqual({ from: 'optimistic' });
- });
-
- it('retains valid data and reports errors when GraphQL data is null', () => {
- const harness = setup();
- dispose = harness.dispose;
- const { query, executions } = harness;
- const error = new CombinedError({
- graphQLErrors: ['root non-null field failed'],
- });
-
- executions[0]?.next({ data: null, error });
- expect(query.data()).toBeUndefined();
- expect(query.error()).toBe(error);
-
- executions[0]?.next({ data: { page: 1 } });
- executions[0]?.next({ data: null, error });
- expect(query.data()).toEqual({ page: 1 });
- expect(query.error()).toBe(error);
- });
-
- it('resubscribes when variables change and ignores the old source', () => {
- const harness = setup();
- dispose = harness.dispose;
- const { query, executions, setVariables } = harness;
-
- executions[0]?.next({ data: { page: 1 } });
- expect(query.data()).toEqual({ page: 1 });
-
- setVariables({ cursor: 'next' });
- expect(query.fetching()).toBe(true);
- expect(executions).toHaveLength(2);
- expect(executions[1]?.variables).toEqual({ cursor: 'next' });
-
- // The unsubscribed first execution must not clobber the signal.
- executions[0]?.next({ data: { page: 'stale-old' } });
- expect(query.data()).toEqual({ page: 1 });
- executions[1]?.next({ data: { page: 2 } });
- expect(query.data()).toEqual({ page: 2 });
- });
-
- it('pauses on undefined variables, keeping the last data', () => {
- const harness = setup();
- dispose = harness.dispose;
- const { query, executions, setVariables } = harness;
-
- executions[0]?.next({ data: { page: 1 } });
- setVariables(undefined);
- expect(query.fetching()).toBe(false);
- expect(query.data()).toEqual({ page: 1 });
- expect(executions).toHaveLength(1);
-
- // Old subscription is torn down: late results are ignored.
- executions[0]?.next({ data: { page: 'late' } });
- expect(query.data()).toEqual({ page: 1 });
- });
-});
diff --git a/apps/web/src/lib/graphql-cache/solid/create-query-signal.ts b/apps/web/src/lib/graphql-cache/solid/create-query-signal.ts
deleted file mode 100644
index aec335d428..0000000000
--- a/apps/web/src/lib/graphql-cache/solid/create-query-signal.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-/**
- * Minimal Solid binding over a urql query: signals that track the latest
- * operation result for as long as the owner scope lives.
- *
- * Unlike an imperative `.toPromise()` call, the underlying source stays
- * subscribed, so results *pushed* by the normalized cache exchange
- * (optimistic mutations, sibling writes, other tabs) re-render consumers
- * immediately — this is the primitive that lets UI flow through urql
- * instead of TanStack invalidation.
- *
- * Deliberately kept out of `@graphql-cache/index`: it depends on solid-js,
- * which the transport-level consumers of that barrel must not pull in.
- */
-
-import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
-import type {
- AnyVariables,
- Client,
- CombinedError,
- RequestPolicy,
-} from '@urql/core';
-import {
- type Accessor,
- batch,
- createRenderEffect,
- createSignal,
- onCleanup,
- untrack,
-} from 'solid-js';
-import { pipe, subscribe } from 'wonka';
-
-export type QuerySignal<TData> = {
- /** Latest result data; retains the previous value across re-executions. */
- data: Accessor<TData | undefined>;
- error: Accessor<CombinedError | undefined>;
- /** True from (re)subscription until the first result arrives. */
- fetching: Accessor<boolean>;
- /** True while the emitted result is a stale cache hit being revalidated. */
- stale: Accessor<boolean>;
-};
-
-export type CreateQuerySignalOptions<TData, TVariables extends AnyVariables> = {
- client: Accessor<Client>;
- document: TypedDocumentNode<TData, TVariables>;
- /**
- * Reactive variables; `undefined` pauses the query (unsubscribes and
- * reports `fetching: false` while keeping the last data).
- */
- variables: Accessor<TVariables | undefined>;
- requestPolicy?: RequestPolicy;
-};
-
-export function createQuerySignal<TData, TVariables extends AnyVariables>(
- options: CreateQuerySignalOptions<TData, TVariables>
-): QuerySignal<TData> {
- const [data, setData] = createSignal<TData | undefined>(undefined);
- const [error, setError] = createSignal<CombinedError | undefined>(undefined);
- const [fetching, setFetching] = createSignal(false);
- const [stale, setStale] = createSignal(false);
-
- // Render effect: subscribes synchronously so consumers created in the
- // same reactive scope observe `fetching` immediately.
- createRenderEffect(() => {
- const variables = options.variables();
- if (variables === undefined) {
- setFetching(false);
- return;
- }
- const client = options.client();
- setFetching(true);
- const subscription = untrack(() =>
- pipe(
- client.query(options.document, variables, {
- requestPolicy: options.requestPolicy,
- }),
- subscribe((result) => {
- batch(() => {
- // GraphQL responses may contain `data: null` at runtime when a
- // non-null field error propagates to the operation root, even
- // though urql's static type only includes `undefined`. Keep the
- // last valid result and expose the CombinedError to the caller.
- if (result.data != null) setData(() => result.data);
- setError(result.error);
- setStale(result.stale);
- setFetching(false);
- });
- })
- )
- );
- onCleanup(subscription.unsubscribe);
- });
-
- return { data, error, fetching, stale };
-}
diff --git a/apps/web/src/lib/urql-solid/create-keyed-projection.test.ts b/apps/web/src/lib/queries/soup/create-keyed-projection.test.ts
similarity index 100%
rename from apps/web/src/lib/urql-solid/create-keyed-projection.test.ts
rename to apps/web/src/lib/queries/soup/create-keyed-projection.test.ts
diff --git a/apps/web/src/lib/urql-solid/create-keyed-projection.ts b/apps/web/src/lib/queries/soup/create-keyed-projection.ts
similarity index 90%
rename from apps/web/src/lib/urql-solid/create-keyed-projection.ts
rename to apps/web/src/lib/queries/soup/create-keyed-projection.ts
index 1357b3bf62..9c8838e4e0 100644
--- a/apps/web/src/lib/urql-solid/create-keyed-projection.ts
+++ b/apps/web/src/lib/queries/soup/create-keyed-projection.ts
@@ -36,7 +36,12 @@ function equalSnapshot(value: unknown, previous: unknown): boolean {
);
}
-/** Tracks and reconciles each projected item independently, retaining keyed identity. */
+/**
+ * Tracks and reconciles each projected item independently, retaining keyed identity.
+ *
+ * Soup row projection over records a query has already read; it does not read
+ * data itself. Soup list sources and `createSoupRowStore` use it.
+ */
export function createKeyedProjection<T, K, U>(
items: Accessor<readonly T[]>,
key: (item: T, index: number) => K,
diff --git a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.test.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
similarity index 96%
rename from apps/web/src/lib/graphql-cache/solid/create-predicate-query.test.ts
rename to apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
index b2557c0ec5..b5bd3a1c4d 100644
--- a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
@@ -2,15 +2,18 @@ import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { gql } from '@urql/core';
import { createComputed, createRoot, createSignal } from 'solid-js';
import { afterEach, expect, it } from 'vitest';
-import { selectRecords } from '../exchange/record-selection';
-import { createNoopCacheHost } from '../host/noop-host';
-import type { CacheChangeListener, CacheHost } from '../host/types';
+import { selectRecords } from '../../../graphql-cache/exchange/record-selection';
+import { createNoopCacheHost } from '../../../graphql-cache/host/noop-host';
+import type {
+ CacheChangeListener,
+ CacheHost,
+} from '../../../graphql-cache/host/types';
import {
type EntityFilterCacheArgs,
type EntityFilterCacheResult,
type LiveQueryUpdate,
parseCacheRevision,
-} from '../protocol';
+} from '../../../graphql-cache/protocol';
import { createPredicateQuery } from './create-predicate-query';
type Row = {
diff --git a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
similarity index 94%
rename from apps/web/src/lib/graphql-cache/solid/create-predicate-query.ts
rename to apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
index 41ebb9f13b..7464bb750c 100644
--- a/apps/web/src/lib/graphql-cache/solid/create-predicate-query.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
@@ -9,13 +9,13 @@ import {
untrack,
} from 'solid-js';
import { createStore, produce, reconcile } from 'solid-js/store';
-import type { RecordSelection } from '../exchange/record-selection';
-import type { CacheHost } from '../host/types';
+import type { RecordSelection } from '../../../graphql-cache/exchange/record-selection';
+import type { CacheHost } from '../../../graphql-cache/host/types';
import {
type CacheRevision,
type EntityFilterCacheArgs,
parseCacheRevision,
-} from '../protocol';
+} from '../../../graphql-cache/protocol';
/** A declared source and generated fragment; no mutation-specific query updates. */
export type PredicateQueryRequest<T> = {
@@ -44,7 +44,13 @@ type LiveQueryHost = Pick<
'entityFilter' | 'onCacheChanged' | 'onCacheGenerationChanged'
>;
-/** Owns subscription, coalescing, generation recovery, and keyed Solid rows. */
+/**
+ * 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>;
diff --git a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
index d8c8179718..37f8092db2 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
@@ -19,7 +19,6 @@ import { querySnapshot } from '../../../graphql-cache/exchange/live-query';
import { normalizedCacheResultMetadata } from '../../../graphql-cache/exchange/normalized-cache-exchange';
import { selectRecords } from '../../../graphql-cache/exchange/record-selection';
import type { CacheRevision } from '../../../graphql-cache/protocol';
-import { createPredicateQuery } from '../../../graphql-cache/solid/create-predicate-query';
import {
ChannelListItemFieldsFragmentDoc,
ChannelListSoupDocument,
@@ -42,6 +41,7 @@ import { createUrqlInfiniteQuery } from '../../../urql-solid/create-urql-infinit
import type { UrqlInfiniteData } from '../../../urql-solid/types';
import { registerChannelNotificationRefresh } from '../../channel/register-notification-refresh';
import { registerGraphqlSoupRevalidations } from './active-queries';
+import { createPredicateQuery } from './create-predicate-query';
import { isCachedMailView } from './mail-view';
import {
usePendingGraphqlSoupDeleteIds,
@@ -78,6 +78,8 @@ const hasSoupPage = (page: SoupQuery | ChannelListSoupQuery): boolean =>
/** Owns network pages, live cache records, Mail cursors, and fallback selection.
* Data is a non-suspending accessor of reactive GraphQL records, before UI mapping.
+ * This is the one GraphQL Soup list source; feature code reads it through
+ * `useSoupAstItemsQuery`.
*/
export function createSoupLiveQuery(
request: Accessor<SoupLiveQueryInput | undefined>,
diff --git a/apps/web/src/lib/queries/soup/graphql/grouped-projection.ts b/apps/web/src/lib/queries/soup/graphql/grouped-projection.ts
index 9a34ff166c..c2341b92cb 100644
--- a/apps/web/src/lib/queries/soup/graphql/grouped-projection.ts
+++ b/apps/web/src/lib/queries/soup/graphql/grouped-projection.ts
@@ -5,7 +5,7 @@ import {
type GraphqlSoupItem,
mapGraphqlSoupItem,
} from '../../../service-clients/service-storage/graphql-soup';
-import { createKeyedProjection } from '../../../urql-solid/create-keyed-projection';
+import { createKeyedProjection } from '../create-keyed-projection';
import { makeGroupComparator, resolveGroupMetaForKey } from '../grouped/api';
import type { GroupByField, GroupMeta } from '../grouped/types';
import type { SoupAstItemsData } from '../items';
diff --git a/apps/web/src/lib/queries/soup/graphql/items.ts b/apps/web/src/lib/queries/soup/graphql/items.ts
index 516adfc4e2..dfb0ed754f 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.ts
@@ -6,8 +6,8 @@ import {
type GraphqlSoupItem,
mapGraphqlSoupItem,
} from '../../../service-clients/service-storage/graphql-soup';
-import { createKeyedProjection } from '../../../urql-solid/create-keyed-projection';
import { useInstructionsMdIdQuery } from '../../storage/instructions-md';
+import { createKeyedProjection } from '../create-keyed-projection';
import { soupQueryExcludesDone } from '../excludes-done';
import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from '../items';
import { soupEntityTimestamp } from '../page-timestamp';
diff --git a/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.ts b/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.ts
index d8531d30cf..95a4599bd8 100644
--- a/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.ts
+++ b/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.ts
@@ -1,6 +1,6 @@
import { createUrqlInfiniteQuery } from '@app/lib/urql-solid';
-import { createKeyedProjection } from '@app/lib/urql-solid/create-keyed-projection';
import type { EntityData } from '@entity';
+import { createKeyedProjection } from '@queries/soup/create-keyed-projection';
import {
makeGraphqlGroupedSoupContinuationInput,
makeGraphqlGroupedSoupInput,
diff --git a/apps/web/src/lib/urql-solid/create-urql-query.ts b/apps/web/src/lib/urql-solid/create-urql-query.ts
index 433f472295..cb802df350 100644
--- a/apps/web/src/lib/urql-solid/create-urql-query.ts
+++ b/apps/web/src/lib/urql-solid/create-urql-query.ts
@@ -4,7 +4,12 @@ import { createBaseQuery } from './create-base-query';
import { createQueryObserver } from './query-observer';
import type { UrqlQueryOptions, UrqlQueryResult } from './types';
-/** Creates a live Solid binding over one urql query observer. */
+/**
+ * Creates a live Solid binding over one urql query observer.
+ *
+ * New single-document reads use `createLiveQuery`, a document-first wrapper
+ * over this binding. Existing callers are already live and need no migration.
+ */
export function createUrqlQuery<
QueryData = unknown,
Variables extends AnyVariables = AnyVariables,
diff --git a/crates/client/README.md b/crates/client/README.md
index b131f1750f..bf4e12ce91 100644
--- a/crates/client/README.md
+++ b/crates/client/README.md
@@ -130,6 +130,11 @@ invalidations and gaps in that bounded journal conservatively rebuild the view.
Views are released on unsubscribe and bounded by an LRU; eviction is safe because
a subscriber with an unavailable cursor receives a full replacement.
+Web code has one default reactive read per data shape: `createSoupLiveQuery` for
+Soup lists, which feature code reaches through `useSoupAstItemsQuery`, and
+`createLiveQuery` for other GraphQL documents. See
+[choosing a reactive read](../../apps/web/docs/graphql-normalized-cache-plan.md#choosing-a-reactive-read).
+
For Soup, `createSoupLiveQuery` owns network fetching, server pagination, cache
baselines, and local fallback selection. Its non-suspending `data()` accessor
returns reactive GraphQL records; callers do not coordinate cache revisions:
@@ -157,20 +162,10 @@ The legacy REST-shaped Soup facade translates its request and projects these
records into UI entities through one keyed mapper. Fetched versions remain
separate from local display versions so pagination coverage cannot drift.
-The lower-level Solid `createPredicateQuery` binding owns subscription, coalescing,
-cleanup and engine-generation recovery, preserving keyed row stores and applying
-patches in one batch. Its first source adapter is a reconciled flat Soup filter:
-
-```ts
-const items = createPredicateQuery({
- host: getGraphqlSoupCacheHost,
- query: () => ({
- source: { filters: filters(), sortMethod: 'UPDATED_AT',
- sortDirection: 'DESC', limit: 50, baseline: serverMembership() },
- select: selectRecords(SoupItemFieldsFragmentDoc),
- }),
-});
-```
+Inside `createSoupLiveQuery`, a Soup-internal binding owns subscription,
+coalescing, cleanup and engine-generation recovery, preserving keyed row stores
+and applying patches in one batch. Its only source is a reconciled flat Soup
+filter; it is not a general query API.
Mutations still use ordinary GraphQL execution and the registered local resolver.
The view requires no per-mutation update callback. This is an incremental row
@@ -190,9 +185,11 @@ const accounts = createLiveQuery(
);
```
-This uses the existing urql query contract, with cache-core tracking selected
-fields and returning response-path patches. Existing `createUrqlQuery` and
-`createUrqlInfiniteQuery` consumers benefit from the same path automatically.
+It is a document-first wrapper over `createUrqlQuery`, so it keeps the existing
+urql query contract while cache-core tracks selected fields and returns
+response-path patches. Existing `createUrqlQuery` and `createUrqlInfiniteQuery`
+consumers benefit from the same path automatically and need no migration;
+cursor-paginated documents use `createUrqlInfiniteQuery`.
Aliases, fragment types, arguments, variable defaults and conditional selections
are resolved by the core reader. Structural edits rebuild the projection;
teardown, account resets and bounded retention discard obsolete bindings. See