Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
refactor(soup): move graphql queries and transport switching (#5447)
dev-rbc1b584af3e87
diff --git a/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.test.ts b/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.test.tsindex 4413342434..b18e2f26f4 100644--- a/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.test.ts+++ b/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.test.ts@@ -45,12 +45,12 @@ vi.mock('@service-storage/graphql-soup', () => ({mapGraphqlGroupedSoupPage: mapGraphqlGroupedSoupPageMock,}));+import { createGraphqlGroupedSoupAstItemsQuery } from '@queries/soup/graphql/grouped-items';import {groupedSoupInputKey,groupedSoupLogicalViewKey,} from '@queries/soup/grouped/graphql-operation-registry';import type { GroupMeta } from '@queries/soup/grouped/types';-import { useReactiveGroupedSoupAstItemsQuery } from '@queries/soup/reactive-grouped-items';import type { GroupSoupQueryVariables } from '@service-storage/graphql/generated/graphql';import { createGraphqlGroupedSoupQueries } from './create-graphql-grouped-soup-queries';@@ -151,7 +151,7 @@ function setup() {let grouped!: ReturnType<typeof createGraphqlGroupedSoupQueries>;const dispose = createRoot((rootDispose) => {- const parent = useReactiveGroupedSoupAstItemsQuery(+ const parent = createGraphqlGroupedSoupAstItemsQuery(() => ({params: { limit: 2, sort_method: 'updated_at' },body: {},diff --git a/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.ts b/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.tsindex 93666ed99d..3c0743840a 100644--- a/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.ts+++ b/apps/web/src/features/next-soup/soup-view/create-graphql-grouped-soup-queries.ts@@ -3,7 +3,7 @@ import type { EntityData } from '@entity';import {makeGraphqlGroupedSoupContinuationInput,makeGraphqlGroupedSoupInput,-} from '@queries/soup/graphql-ast';+} from '@queries/soup/graphql/ast';import { registerGroupedSoupContinuation } from '@queries/soup/grouped/graphql-operation-registry';import type { GroupByField, GroupMeta } from '@queries/soup/grouped/types';import type {diff --git a/apps/web/src/features/next-soup/soup-view/soup-view-context.tsx b/apps/web/src/features/next-soup/soup-view/soup-view-context.tsxindex a43eec3fb8..ca263b5763 100644--- a/apps/web/src/features/next-soup/soup-view/soup-view-context.tsx+++ b/apps/web/src/features/next-soup/soup-view/soup-view-context.tsx@@ -49,8 +49,6 @@ import { useEntryState } from '@components/app/split-layout/entry-state';import { useSplitPanelOrThrow } from '@components/app/split-layout/layoutUtils';import {ENABLE_FEATURED_SEARCH_RESULTS,- ENABLE_GRAPHQL_SOUP_FLAG,- ENABLE_GRAPHQL_SOUP_OVERRIDE,ENABLE_NEW_INBOX_FLAG,ENABLE_NEW_INBOX_OVERRIDE,ENABLE_SUPPORTED_SOUP_FOREIGN_ENTITIES_FLAG,@@ -77,12 +75,9 @@ import type {import type { SoupParams } from '@queries/soup/items';import { useSoupAstItemsQuery } from '@queries/soup/items';import { soupKeys } from '@queries/soup/keys';-import { useReactiveGroupedSoupAstItemsQuery } from '@queries/soup/reactive-grouped-items';-import { useReactiveSoupAstItemsQuery } from '@queries/soup/reactive-items';import { mapApiSoupItemToEntity } from '@queries/soup/transform-utils';-import type { SoupApiItem, SoupPage } from '@service-storage/generated/schemas';+import type { SoupApiItem } from '@service-storage/generated/schemas';import { makePersisted } from '@solid-primitives/storage';-import type { InfiniteData } from '@tanstack/solid-query';import {type Accessor,batch,@@ -295,9 +290,6 @@ export const SoupViewContextProvider: FlowComponent<const queryClient = useQueryClient();const [filterPersistenceEnabled] = useSoupFilterPersistence();- const useGraphqlSoupFF = useFeatureFlag(ENABLE_GRAPHQL_SOUP_FLAG, {- enabledOverride: ENABLE_GRAPHQL_SOUP_OVERRIDE,- });const panel = useSplitPanelOrThrow();const activeListView = createMemo<ListView | undefined>(() => {@@ -379,28 +371,8 @@ export const SoupViewContextProvider: FlowComponent<onCleanup(predicatesCaptorTeardown);const resetToInitialPage = () => {- const groupBy = serverGroupByField();-- reactiveItemsQuery.resetToInitialPage();- reactiveGroupedItemsQuery.resetToInitialPage();+ itemsQuery.resetToInitialPage();groupQueries.resetToInitialPage();-- queryClient.setQueryData(- soupKeys.astItems({- params: soupParams(),- body: soupBody(),- groupBy,- transport: reactiveActive() ? 'graphql' : undefined,- }).queryKey,- (prev: InfiniteData<SoupPage> | SoupPage | undefined) => {- if (!prev) return;- if ('pages' in prev) {- prev.pages.splice(1, prev.pages.length);- return prev;- }- return prev;- }- );};// Keep filters per list view and tab so refreshing or returning to a tab@@ -941,65 +913,18 @@ export const SoupViewContextProvider: FlowComponent<);};- // Reactive urql path (same `enable-graphql-soup` flag as the transport):- // flat and server-grouped GraphQL views retain live operation sources, so- // normalized-cache pushes update every loaded page directly. Unsupported- // ASTs and REST transport continue through the TanStack fallback.- const reactiveEligible = () => useGraphqlSoupFF().enabled;-- const reactiveItemsQuery = useReactiveSoupAstItemsQuery(- () => ({ params: soupParams(), body: soupBody() }),- () => ({- enabled:- enabled() &&- !search.isSearching() &&- reactiveEligible() &&- !serverGroupByField(),- showSupportedForeignEntities: showSupportedForeignEntitiesFF().enabled,- })- );- const reactiveGroupedItemsQuery = useReactiveGroupedSoupAstItemsQuery(+ // The Soup query facade owns GraphQL eligibility and REST fallback. Its urql+ // implementation keeps loaded pages subscribed to the normalized cache.+ const itemsQuery = useSoupAstItemsQuery(() => ({params: soupParams(),body: soupBody(),groupBy: serverGroupByField(),}),- () => ({- enabled:- enabled() &&- !search.isSearching() &&- reactiveEligible() &&- serverGroupByField() !== undefined,- showSupportedForeignEntities: showSupportedForeignEntitiesFF().enabled,- })- );-- const reactiveFlatActive = () =>- reactiveEligible() &&- !serverGroupByField() &&- reactiveItemsQuery.isSupported();- const reactiveGroupedActive = () =>- reactiveEligible() &&- serverGroupByField() !== undefined &&- reactiveGroupedItemsQuery.isSupported();- const reactiveActive = () => reactiveFlatActive() || reactiveGroupedActive();- const activeReactiveItemsQuery = () =>- reactiveGroupedActive() ? reactiveGroupedItemsQuery : reactiveItemsQuery;-- const itemsQuery = useSoupAstItemsQuery(- () => {- const groupBy = serverGroupByField();- return {- params: soupParams(),- body: soupBody(),- groupBy,- transport: reactiveActive() ? 'graphql' : undefined,- };- },() => {const view = activeListView();return {- enabled: enabled() && !search.isSearching() && !reactiveActive(),+ enabled: enabled() && !search.isSearching(),showSupportedForeignEntities: showSupportedForeignEntitiesFF().enabled,meta: {itemFilter: (item) => soupItemMatchesActiveFilters(item, view),@@ -1008,45 +933,21 @@ export const SoupViewContextProvider: FlowComponent<});- // Reading `.data` on a query with no data yet suspends the nearest- // <Suspense> until the fetch settles. Branch on the loading state first- // so a cold initial soup call leaves the view shell rendered and only- // the list region waits on data.+ // Reading `.data` on a cold TanStack query suspends the nearest <Suspense>.+ // Read loading first so REST fallback leaves the view shell rendered.const itemsQueryData = () =>itemsQuery.isLoading ? undefined : itemsQuery.data;- /** Unified reactive-GraphQL or TanStack fallback Soup surface. */const itemsSource = {- data: () =>- reactiveActive() ? activeReactiveItemsQuery().data() : itemsQueryData(),- isLoading: () =>- reactiveActive()- ? activeReactiveItemsQuery().isLoading()- : itemsQuery.isLoading,- isFetching: () =>- reactiveActive()- ? activeReactiveItemsQuery().isFetching()- : itemsQuery.isFetching,- isPlaceholderData: () =>- reactiveActive() ? false : itemsQuery.isPlaceholderData,- isFetchingNextPage: () =>- reactiveActive()- ? activeReactiveItemsQuery().isFetchingNextPage()- : itemsQuery.isFetchingNextPage,- isEnabled: () =>- reactiveActive()- ? enabled() && !search.isSearching()- : itemsQuery.isEnabled,- hasNextPage: () =>- reactiveActive()- ? activeReactiveItemsQuery().hasNextPage()- : itemsQuery.hasNextPage,+ data: itemsQueryData,+ isLoading: () => itemsQuery.isLoading,+ isFetching: () => itemsQuery.isFetching,+ isPlaceholderData: () => itemsQuery.isPlaceholderData,+ isFetchingNextPage: () => itemsQuery.isFetchingNextPage,+ isEnabled: () => itemsQuery.isEnabled,+ hasNextPage: () => itemsQuery.hasNextPage,fetchNextPage: () => {- if (reactiveActive()) {- activeReactiveItemsQuery().fetchNextPage();- } else {- itemsQuery.fetchNextPage();- }+ void itemsQuery.fetchNextPage();},};@@ -1167,7 +1068,8 @@ export const SoupViewContextProvider: FlowComponent<groupByField: serverGroupByField,soupParams,soupBody,- graphqlReactive: reactiveGroupedActive,+ graphqlReactive: () =>+ itemsQuery.transport === 'graphql' && serverGroupByField() !== undefined,queryOptions: () => {const view = activeListView();return {@@ -1504,10 +1406,9 @@ export const SoupViewContextProvider: FlowComponent<// instead of retracting as if the refresh succeeded.{ throwOnError: true }),- // The reactive urql page refetches from the network directly;- // it is outside the TanStack cache the invalidation reaches.- reactiveActive()- ? activeReactiveItemsQuery().refresh()+ // urql pages are outside the TanStack cache invalidation above.+ itemsQuery.transport === 'graphql'+ ? itemsQuery.refresh(): Promise.resolve(),invalidateUserNotifications(),]);diff --git a/apps/web/src/lib/queries/soup/graphql-ast.test.ts b/apps/web/src/lib/queries/soup/graphql/ast.test.tssimilarity index 81%rename from apps/web/src/lib/queries/soup/graphql-ast.test.tsrename to apps/web/src/lib/queries/soup/graphql/ast.test.tsindex b85964e405..7fb5b456ee 100644--- a/apps/web/src/lib/queries/soup/graphql-ast.test.ts+++ b/apps/web/src/lib/queries/soup/graphql/ast.test.ts@@ -7,7 +7,7 @@ import {makeGraphqlGroupedSoupContinuationInput,makeGraphqlGroupedSoupInput,makeGraphqlSoupInput,-} from './graphql-ast';+} from './ast';const UPDATED_AT = '2026-01-01T00:00:00.000Z';@@ -213,6 +213,50 @@ describe('makeGraphqlSoupInput', () => {).toThrow('Unsupported GraphQL Soup AST');});+ it('throws for REST-only top-level filters instead of silently widening the query', () => {+ for (const body of [+ { calf: { l: { id: 'event-1' } } },+ { eca: ['[email protected]'] },+ { ecd: ['example.com'] },+ ]) {+ expect(() =>+ makeGraphqlSoupInput({+ params: { limit: 100, sort_method: 'updated_at' },+ body: body as never,+ })+ ).toThrow('Unsupported GraphQL Soup AST');+ }+ });++ it('rejects REST-only top-level filters for grouped queries too', () => {+ expect(() =>+ makeGraphqlGroupedSoupInput({+ params: { limit: 100, sort_method: 'updated_at' },+ body: { ecd: ['example.com'] } as never,+ groupBy: { type: 'entity_type' },+ })+ ).toThrow('Unsupported GraphQL Soup AST');+ });++ it('rejects email views for grouped queries instead of dropping them', () => {+ expect(() =>+ makeGraphqlGroupedSoupInput({+ params: { limit: 100, sort_method: 'updated_at' },+ body: { emailView: 'inbox' } as never,+ groupBy: { type: 'entity_type' },+ })+ ).toThrow('Unsupported GraphQL Soup AST');+ });++ it('rejects unknown email views instead of using the GraphQL default', () => {+ expect(() =>+ makeGraphqlSoupInput({+ params: { limit: 100, sort_method: 'updated_at' },+ body: { emailView: 'unknown' } as never,+ })+ ).toThrow('Unsupported GraphQL Soup AST');+ });+it('throws for frecency sort so callers can fall back', () => {expect(() =>makeGraphqlSoupInput({diff --git a/apps/web/src/lib/queries/soup/graphql-ast.ts b/apps/web/src/lib/queries/soup/graphql/ast.tssimilarity index 94%rename from apps/web/src/lib/queries/soup/graphql-ast.tsrename to apps/web/src/lib/queries/soup/graphql/ast.tsindex db5c916111..60558d84c8 100644--- a/apps/web/src/lib/queries/soup/graphql-ast.ts+++ b/apps/web/src/lib/queries/soup/graphql/ast.ts@@ -37,8 +37,8 @@ type GraphqlExprInput<TLiteral> =| { not: GraphqlExprInput<TLiteral> }| { literal: TLiteral };-import type { GroupByField } from './grouped/types';-import type { SoupAstBody, SoupParams } from './items';+import type { GroupByField } from '../grouped/types';+import type { SoupAstBody, SoupParams } from '../items';type RestAst =| { '&': [RestAst, RestAst] }@@ -59,6 +59,10 @@ type TargetAstKey =| 'propf';type AstBody = Partial<Record<TargetAstKey, RestAst>> & {+ /** Calendar, CRM-address, and CRM-domain filters are REST-only today. */+ calf?: unknown;+ eca?: string[];+ ecd?: string[];emailView?: 'inbox' | 'drafts' | 'sent' | 'all';};@@ -489,10 +493,29 @@ function mapEmailView(return 'ALL';case undefined:return undefined;+ default:+ return unsupported(`email view ${view}`);+ }+}++function assertGraphqlCompatibleBody(body: AstBody): void {+ if (body.calf !== undefined) {+ unsupported('calendar filters are not supported by GraphQL Soup yet');+ }+ if (body.eca !== undefined) {+ unsupported(+ 'CRM-scoped email address filters are not supported by GraphQL Soup yet'+ );+ }+ if (body.ecd !== undefined) {+ unsupported(+ 'CRM-scoped email domain filters are not supported by GraphQL Soup yet'+ );}}function makeGraphqlFilters(body: AstBody): GraphqlEntityFilterAstInput {+ assertGraphqlCompatibleBody(body);const filters: GraphqlEntityFilterAstInput = {};if (body.df)@@ -532,6 +555,7 @@ export function makeGraphqlSoupInput(args: {cursor?: string | null;}): GraphqlSoupInput {const body = args.body as AstBody;+ assertGraphqlCompatibleBody(body);const emailView = mapEmailView(body.emailView);if (args.cursor != null) {@@ -576,12 +600,18 @@ export function makeGraphqlGroupedSoupInput(args: {body: SoupAstBody;groupBy: GroupByField;}): GraphqlGroupedSoupInput {+ const body = args.body as AstBody;+ assertGraphqlCompatibleBody(body);+ if (body.emailView !== undefined) {+ unsupported('email views are not supported by grouped GraphQL Soup yet');+ }+return {initial: {groupBy: makeGraphqlGroupByInput(args.groupBy),limit: args.params.limit ?? undefined,sortMethod: mapSortMethod(args.params.sort_method),- filters: makeGraphqlFilters(args.body as AstBody),+ filters: makeGraphqlFilters(body),},};}diff --git a/apps/web/src/lib/queries/soup/reactive-grouped-items.ts b/apps/web/src/lib/queries/soup/graphql/grouped-items.tssimilarity index 81%rename from apps/web/src/lib/queries/soup/reactive-grouped-items.tsrename to apps/web/src/lib/queries/soup/graphql/grouped-items.tsindex 43eb35a366..b67843966a 100644--- a/apps/web/src/lib/queries/soup/reactive-grouped-items.ts+++ b/apps/web/src/lib/queries/soup/graphql/grouped-items.ts@@ -4,6 +4,7 @@* rows and group membership without a TanStack invalidation round-trip.*/+import { createUrqlQuery } from '@app/lib/urql-solid';import { Telemetry } from '@macro-inc/observability';import {makeGroupComparator,@@ -22,24 +23,23 @@ import {} from '@service-storage/graphql-soup';import type { CombinedError } from '@urql/core';import { type Accessor, createComputed, createMemo, on } from 'solid-js';-import { createUrqlQuery } from '../../urql-solid';-import { makeGraphqlGroupedSoupInput } from './graphql-ast';-import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from './items';-import type { ReactiveSoupAstItemsQuery } from './reactive-items';-import { mapSoupPageToEntityList } from './transform-utils';+import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from '../items';+import { mapSoupPageToEntityList } from '../transform-utils';+import { makeGraphqlGroupedSoupInput } from './ast';+import type { GraphqlSoupAstItemsQuery } from './items';-export type ReactiveGroupedSoupAstItemsQueryArgs = {+export type GraphqlGroupedSoupAstItemsQueryArgs = {params: SoupAstParams;body: SoupAstBody;groupBy: GroupByField | undefined;};-export type ReactiveGroupedSoupAstItemsQueryOptions = {+export type GraphqlGroupedSoupAstItemsQueryOptions = {enabled: boolean;showSupportedForeignEntities?: boolean;};-function mapReactiveGroupedSoupData(+function mapGraphqlGroupedSoupData(data: GroupSoupQuery,groupBy: GroupByField,options: Parameters<typeof mapSoupPageToEntityList>[1]@@ -77,11 +77,11 @@ function mapReactiveGroupedSoupData(};}-/** Creates the live parent operation that discovers grouped Soup bins. */-export function useReactiveGroupedSoupAstItemsQuery(- args: Accessor<ReactiveGroupedSoupAstItemsQueryArgs>,- options: Accessor<ReactiveGroupedSoupAstItemsQueryOptions>-): ReactiveSoupAstItemsQuery {+/** Creates the live urql parent query for a grouped Soup AST request. */+export function createGraphqlGroupedSoupAstItemsQuery(+ args: Accessor<GraphqlGroupedSoupAstItemsQueryArgs>,+ options: Accessor<GraphqlGroupedSoupAstItemsQueryOptions>+): GraphqlSoupAstItemsQuery {const instructionsIdQuery = useInstructionsMdIdQuery();const input = createMemo(() => {const { params, body, groupBy } = args();@@ -89,7 +89,7 @@ export function useReactiveGroupedSoupAstItemsQuery(try {return makeGraphqlGroupedSoupInput({ params, body, groupBy });} catch {- // Unsupported GraphQL Soup AST — consumers fall back to TanStack/REST.+ // Unsupported GraphQL Soup AST — the public facade falls back to REST.return undefined;}});@@ -110,7 +110,7 @@ export function useReactiveGroupedSoupAstItemsQuery(requestPolicy: 'cache-and-network' as const,keepPreviousData: false,select: (data: GroupSoupQuery) =>- mapReactiveGroupedSoupData(data, groupBy!, {+ mapGraphqlGroupedSoupData(data, groupBy!, {instructionsIdQuery,showSupportedForeignEntities:queryOptions.showSupportedForeignEntities,@@ -141,11 +141,12 @@ export function useReactiveGroupedSoupAstItemsQuery(data: () => query.data,error,isSupported,+ isEnabled: () => query.isEnabled,isLoading: () => query.isLoading,isFetching: () => query.isFetching,isFetchingNextPage: () => false,hasNextPage: () => false,- fetchNextPage: () => undefined,+ fetchNextPage: async () => undefined,resetToInitialPage: () => undefined,refresh: async () => {if (input() === undefined) return;diff --git a/apps/web/src/lib/queries/soup/reactive-items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.tssimilarity index 92%rename from apps/web/src/lib/queries/soup/reactive-items.test.tsrename to apps/web/src/lib/queries/soup/graphql/items.test.tsindex 5cfb8de5a8..074b0ab404 100644--- a/apps/web/src/lib/queries/soup/reactive-items.test.ts+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts@@ -28,15 +28,15 @@ vi.mock('@service-storage/graphql-soup', () => ({mapGraphqlSoupPage: mapGraphqlSoupPageMock,}));-vi.mock('./graphql-ast', () => ({+vi.mock('./ast', () => ({makeGraphqlSoupInput: vi.fn(() => ({ initial: { limit: 50 } })),}));-vi.mock('./transform-utils', () => ({+vi.mock('../transform-utils', () => ({mapSoupPageToEntityList: mapSoupPageToEntityListMock,}));-import { useReactiveSoupAstItemsQuery } from './reactive-items';+import { createGraphqlSoupAstItemsQuery } from './items';type FakeExecution = {next(data: unknown): void;@@ -75,7 +75,7 @@ function makeFakeClient(): {};}-describe('useReactiveSoupAstItemsQuery', () => {+describe('createGraphqlSoupAstItemsQuery', () => {beforeEach(() => {vi.clearAllMocks();});@@ -89,7 +89,7 @@ describe('useReactiveSoupAstItemsQuery', () => {getGraphqlSoupClientMock.mockReturnValue(fake.client);createRoot((dispose) => {- const query = useReactiveSoupAstItemsQuery(+ const query = createGraphqlSoupAstItemsQuery(() => ({ params: {}, body: {} }) as never,() => ({ enabled: true }));diff --git a/apps/web/src/lib/queries/soup/reactive-items.ts b/apps/web/src/lib/queries/soup/graphql/items.tssimilarity index 77%rename from apps/web/src/lib/queries/soup/reactive-items.tsrename to apps/web/src/lib/queries/soup/graphql/items.tsindex 3db26266b8..193f2ce8e8 100644--- a/apps/web/src/lib/queries/soup/reactive-items.ts+++ b/apps/web/src/lib/queries/soup/graphql/items.ts@@ -1,13 +1,10 @@/*- * Reactive urql-backed Soup items: the flagged alternative to the TanStack- * `useSoupAstItemsQuery` path. Every loaded page remains subscribed to its- * normalized GraphQL cache operation so cache writes update the list directly.- *- * Scope matches the GraphQL transport: flat views whose filter AST has a- * GraphQL translation. Consumers check `isSupported` and fall back to the- * TanStack path otherwise.+ * Reactive urql-backed Soup items. Every loaded page remains subscribed to+ * its normalized GraphQL cache operation so cache writes update the list+ * directly. The public REST/GraphQL facade lives in ../items.ts.*/+import { createUrqlInfiniteQuery } from '@app/lib/urql-solid';import { Telemetry } from '@macro-inc/observability';import { useInstructionsMdIdQuery } from '@queries/storage/instructions-md';import {@@ -22,42 +19,43 @@ import {} from '@service-storage/graphql-soup';import type { CombinedError } from '@urql/core';import { type Accessor, createComputed, createMemo, on } from 'solid-js';-import { createUrqlInfiniteQuery } from '../../urql-solid';-import { makeGraphqlSoupInput } from './graphql-ast';-import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from './items';-import { mapSoupPageToEntityList } from './transform-utils';+import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from '../items';+import { mapSoupPageToEntityList } from '../transform-utils';+import { makeGraphqlSoupInput } from './ast';-export type ReactiveSoupAstItemsQueryArgs = {+export type GraphqlSoupAstItemsQueryArgs = {params: SoupAstParams;body: SoupAstBody;};-export type ReactiveSoupAstItemsQueryOptions = {+export type GraphqlSoupAstItemsQueryOptions = {enabled: boolean;showSupportedForeignEntities?: boolean;};-export type ReactiveSoupAstItemsQuery = {+export type GraphqlSoupAstItemsQuery = {data: Accessor<SoupAstItemsData | undefined>;/** Latest GraphQL transport or application error. */error: Accessor<CombinedError | undefined>;/** False when the filter AST has no GraphQL translation. */isSupported: Accessor<boolean>;+ isEnabled: Accessor<boolean>;isLoading: Accessor<boolean>;isFetching: Accessor<boolean>;isFetchingNextPage: Accessor<boolean>;hasNextPage: Accessor<boolean>;- fetchNextPage: () => void;+ fetchNextPage: () => Promise<void>;/** Discards loaded continuation pages while retaining the initial page. */resetToInitialPage: () => void;/** Refetches the currently loaded page chain from the network. */refresh: () => Promise<void>;};-export function useReactiveSoupAstItemsQuery(- args: Accessor<ReactiveSoupAstItemsQueryArgs>,- options: Accessor<ReactiveSoupAstItemsQueryOptions>-): ReactiveSoupAstItemsQuery {+/** Creates the live urql query for a flat Soup AST request. */+export function createGraphqlSoupAstItemsQuery(+ args: Accessor<GraphqlSoupAstItemsQueryArgs>,+ options: Accessor<GraphqlSoupAstItemsQueryOptions>+): GraphqlSoupAstItemsQuery {const instructionsIdQuery = useInstructionsMdIdQuery();const inputForCursor = (@@ -67,7 +65,7 @@ export function useReactiveSoupAstItemsQuery(try {return makeGraphqlSoupInput({ params, body, cursor });} catch {- // Unsupported GraphQL Soup AST — consumers fall back to TanStack.+ // Unsupported GraphQL Soup AST — the public facade falls back to REST.return undefined;}};@@ -126,12 +124,13 @@ export function useReactiveSoupAstItemsQuery(data: () => query.data,error,isSupported,+ isEnabled: () => query.isEnabled,isLoading: () => query.isLoading,isFetching: () => query.isFetching,isFetchingNextPage: () => query.isFetchingNextPage,hasNextPage: () => query.hasNextPage,- fetchNextPage: () => {- void query.fetchNextPage();+ fetchNextPage: async () => {+ await query.fetchNextPage();},resetToInitialPage: query.resetToInitialPage,refresh: async () => {diff --git a/apps/web/src/lib/queries/soup/items.ts b/apps/web/src/lib/queries/soup/items.tsindex 45fe3e7e15..67dc676cf4 100644--- a/apps/web/src/lib/queries/soup/items.ts+++ b/apps/web/src/lib/queries/soup/items.ts@@ -1,10 +1,14 @@import { filterSoupItemByRequestBody } from '@app/features/next-soup/filters/query-filters';+import { useFeatureFlag } from '@app/lib/analytics/posthog';+import {+ ENABLE_GRAPHQL_SOUP_FLAG,+ ENABLE_GRAPHQL_SOUP_OVERRIDE,+} from '@core/constant/featureFlags';import { throwOnErr } from '@core/util/result';import type { EntityData } from '@entity';import {makeGroupComparator,parseGroupMeta,- resolveGroupMetaForKey,serializeGroupByField,} from '@queries/soup/grouped/api';import type { GroupByField, GroupMeta } from '@queries/soup/grouped/types';@@ -24,15 +28,14 @@ import type { Params } from '@service-storage/generated/schemas/params';import type { PostSoupAstRequestAllOf } from '@service-storage/generated/schemas/postSoupAstRequestAllOf';import type { PostSoupRequest } from '@service-storage/generated/schemas/postSoupRequest';import {- fetchGraphqlGroupedSoup,- fetchGraphqlSoup,-} from '@service-storage/graphql-soup';-import { type StaleTime, useInfiniteQuery } from '@tanstack/solid-query';+ type InfiniteData,+ type StaleTime,+ useInfiniteQuery,+} from '@tanstack/solid-query';import type { Accessor } from 'solid-js';-import {- makeGraphqlGroupedSoupInput,- makeGraphqlSoupInput,-} from './graphql-ast';+import { queryClient } from '../client';+import { createGraphqlGroupedSoupAstItemsQuery } from './graphql/grouped-items';+import { createGraphqlSoupAstItemsQuery } from './graphql/items';export type SoupParams = Params;@@ -145,7 +148,8 @@ export const useSoupItemsQuery = (}));};-export const useSoupAstItemsQuery = (+/** REST implementation kept private behind {@link useSoupAstItemsQuery}. */+const useRestSoupAstItemsQuery = (args: Accessor<SoupAstItemsQueryArgs>,options?: Accessor<SoupItemsQueryOptions>) => {@@ -186,49 +190,7 @@ export const useSoupAstItemsQuery = (};};- const fetchGraphql = async () => {- const response = await fetchGraphqlGroupedSoup(- makeGraphqlGroupedSoupInput({- params: { ...params, sort_method },- body,- groupBy,- })- );-- return {- items: response.items,- groups: response.groups.map((group): GroupMeta => {- const firstItem = response.items[group.itemIds[0] ?? ''];- const resolved = resolveGroupMetaForKey(- groupBy,- group.key,- firstItem- );- return {- key: group.key,- label: resolved?.label ?? group.key,- displayOrder: resolved?.displayOrder ?? null,- totalCount: group.totalCount,- itemIds: group.itemIds,- nextCursor: group.nextCursor,- };- }),- };- };-- const response =- transport === 'graphql'- ? await fetchGraphql().catch((error: unknown) => {- if (- error instanceof Error &&- error.message.startsWith('Unsupported GraphQL Soup AST:')- ) {- console.warn(error.message);- return fetchRest();- }- throw error;- })- : await fetchRest();+ const response = await fetchRest();return {kind: 'grouped',@@ -252,28 +214,7 @@ export const useSoupAstItemsQuery = (}));- const fetchGraphql = async () =>- await fetchGraphqlSoup(- makeGraphqlSoupInput({- params,- body,- cursor: ctx.pageParam,- })- );-- const response =- transport === 'graphql'- ? await fetchGraphql().catch((error: unknown) => {- if (- error instanceof Error &&- error.message.startsWith('Unsupported GraphQL Soup AST:')- ) {- console.warn(error.message);- return fetchRest();- }- throw error;- })- : await fetchRest();+ const response = await fetchRest();return {kind: 'flat',@@ -360,3 +301,167 @@ export const useSoupAstItemsQuery = (};});};++/** Transport selected by the Soup AST query facade. */+export type SoupAstItemsQueryTransport = 'rest' | 'graphql';++/** Stable query surface shared by the REST and urql-solid implementations. */+export type SoupAstItemsQuery = {+ readonly data: SoupAstItemsData | undefined;+ readonly error: Error | null;+ readonly isLoading: boolean;+ readonly isFetching: boolean;+ readonly isPlaceholderData: boolean;+ readonly isFetchingNextPage: boolean;+ readonly isEnabled: boolean;+ readonly hasNextPage: boolean;+ readonly transport: SoupAstItemsQueryTransport;+ fetchNextPage(): Promise<void>;+ refetch(): Promise<void>;+ /** Discards continuation pages while retaining the initial page. */+ resetToInitialPage(): void;+ /** Forces the selected transport to refetch from the network. */+ refresh(): Promise<void>;+};++/**+ * Queries Soup through urql-solid when the feature is enabled and the current+ * AST has a complete GraphQL translation. Unsupported requests retain the REST+ * behavior. Explicit `rest` and `graphql` transport values remain available+ * for rollout controls; forced GraphQL still falls back safely when unsupported.+ */+export function useSoupAstItemsQuery(+ args: Accessor<SoupAstItemsQueryArgs>,+ options?: Accessor<SoupItemsQueryOptions>+): SoupAstItemsQuery {+ const graphqlSoupFlag = useFeatureFlag(ENABLE_GRAPHQL_SOUP_FLAG, {+ enabledOverride: ENABLE_GRAPHQL_SOUP_OVERRIDE,+ });++ const queryEnabled = () => options?.().enabled !== false;+ const graphqlRequested = () => {+ const requestedTransport = args().transport;+ if (requestedTransport === 'rest') return false;+ if (requestedTransport === 'graphql') return true;+ return graphqlSoupFlag().enabled;+ };++ const graphqlFlatQuery = createGraphqlSoupAstItemsQuery(+ () => ({ params: args().params, body: args().body }),+ () => ({+ enabled:+ graphqlRequested() && queryEnabled() && args().groupBy === undefined,+ showSupportedForeignEntities: options?.().showSupportedForeignEntities,+ })+ );+ const graphqlGroupedQuery = createGraphqlGroupedSoupAstItemsQuery(+ () => ({+ params: args().params,+ body: args().body,+ groupBy: args().groupBy,+ }),+ () => ({+ enabled:+ graphqlRequested() && queryEnabled() && args().groupBy !== undefined,+ showSupportedForeignEntities: options?.().showSupportedForeignEntities,+ })+ );++ const activeGraphqlQuery = () =>+ args().groupBy === undefined ? graphqlFlatQuery : graphqlGroupedQuery;+ const usesGraphql = () =>+ graphqlRequested() && activeGraphqlQuery().isSupported();++ const restQuery = useRestSoupAstItemsQuery(args, () => {+ const currentOptions = options?.();+ return {+ ...currentOptions,+ enabled: queryEnabled() && !usesGraphql(),+ };+ });++ const resetRestToInitialPage = () => {+ const { params, body, groupBy, transport } = args();+ queryClient.setQueryData<InfiniteData<SoupAstItemsPage, string | null>>(+ soupKeys.astItems({ params, body, groupBy, transport }).queryKey,+ (previous) => {+ if (!previous || previous.pages.length <= 1) return previous;+ return {+ ...previous,+ pages: previous.pages.slice(0, 1),+ pageParams: previous.pageParams.slice(0, 1),+ };+ }+ );+ };++ return {+ get data() {+ return usesGraphql() ? activeGraphqlQuery().data() : restQuery.data;+ },+ get error() {+ return usesGraphql()+ ? (activeGraphqlQuery().error() ?? null)+ : (restQuery.error ?? null);+ },+ get isLoading() {+ return usesGraphql()+ ? activeGraphqlQuery().isLoading()+ : restQuery.isLoading;+ },+ get isFetching() {+ return usesGraphql()+ ? activeGraphqlQuery().isFetching()+ : restQuery.isFetching;+ },+ get isPlaceholderData() {+ return usesGraphql() ? false : restQuery.isPlaceholderData;+ },+ get isFetchingNextPage() {+ return usesGraphql()+ ? activeGraphqlQuery().isFetchingNextPage()+ : restQuery.isFetchingNextPage;+ },+ get isEnabled() {+ return usesGraphql()+ ? activeGraphqlQuery().isEnabled()+ : restQuery.isEnabled;+ },+ get hasNextPage() {+ return usesGraphql()+ ? activeGraphqlQuery().hasNextPage()+ : (restQuery.hasNextPage ?? false);+ },+ get transport() {+ return usesGraphql() ? 'graphql' : 'rest';+ },+ async fetchNextPage() {+ if (usesGraphql()) {+ await activeGraphqlQuery().fetchNextPage();+ } else {+ await restQuery.fetchNextPage();+ }+ },+ async refetch() {+ if (usesGraphql()) {+ await activeGraphqlQuery().refresh();+ } else {+ await restQuery.refetch();+ }+ },+ resetToInitialPage() {+ // Reset both urql bindings: a grouping switch can reactivate a flat page+ // chain (or vice versa) that was loaded before the current view.+ graphqlFlatQuery.resetToInitialPage();+ graphqlGroupedQuery.resetToInitialPage();+ if (!usesGraphql()) resetRestToInitialPage();+ },+ async refresh() {+ if (usesGraphql()) {+ await activeGraphqlQuery().refresh();+ } else {+ await restQuery.refetch({ throwOnError: true });+ }+ },+ };+}