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(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.ts
index 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.ts
index 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.tsx
index 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.ts
similarity index 81%
rename from apps/web/src/lib/queries/soup/graphql-ast.test.ts
rename to apps/web/src/lib/queries/soup/graphql/ast.test.ts
index 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.ts
similarity index 94%
rename from apps/web/src/lib/queries/soup/graphql-ast.ts
rename to apps/web/src/lib/queries/soup/graphql/ast.ts
index 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.ts
similarity index 81%
rename from apps/web/src/lib/queries/soup/reactive-grouped-items.ts
rename to apps/web/src/lib/queries/soup/graphql/grouped-items.ts
index 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.ts
similarity index 92%
rename from apps/web/src/lib/queries/soup/reactive-items.test.ts
rename to apps/web/src/lib/queries/soup/graphql/items.test.ts
index 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.ts
similarity index 77%
rename from apps/web/src/lib/queries/soup/reactive-items.ts
rename to apps/web/src/lib/queries/soup/graphql/items.ts
index 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.ts
index 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 });
+ }
+ },
+ };
+}