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
import { filterSoupItemByRequestBody } from '@app/features/next-soup/filters/query-filters';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
import { enableGraphqlSoup } from '@core/constant/featureFlags';
import { throwOnErr } from '@core/util/result';
import type { EntityData } from '@entity';
import {
groupedSortMethod,
makeGroupComparator,
parseGroupMeta,
serializeGroupByField,
} from '@queries/soup/grouped/api';
import type { GroupByField, GroupMeta } from '@queries/soup/grouped/types';
import { soupKeys } from '@queries/soup/keys';
import {
isDisplayableSoupItem,
mapApiSoupItemToEntity,
mapSoupPageToEntityList,
} from '@queries/soup/transform-utils';
import { storageServiceClient } from '@service-storage/client';
import type { SoupApiItem } from '@service-storage/generated/schemas';
import type { ApiEntityFilterAst } from '@service-storage/generated/schemas/apiEntityFilterAst';
import type { EntityFilters } from '@service-storage/generated/schemas/entityFilters';
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 {
type InfiniteData,
infiniteQueryOptions,
keepPreviousData,
type StaleTime,
useInfiniteQuery,
} from '@tanstack/solid-query';
import { type Accessor, onCleanup } from 'solid-js';
import type { QueryRevalidation } from '../../graphql-cache/exchange/optimistic';
import { queryClient } from '../client';
import { registerActiveGraphqlSoupQuery } from './graphql/active-queries';
import type { PredicateQueryStatus } from './graphql/create-predicate-query';
import type { SoupEntityRef } from './graphql/entity-input';
import { createGraphqlGroupedSoupAstItemsQuery } from './graphql/grouped-items';
import { createGraphqlSoupAstItemsQuery } from './graphql/items';
import { soupPageTimestamp } from './page-timestamp';
import {
createSoupRequestSignal,
SOUP_NETWORK_QUERY_OPTIONS,
} from './request-timeout';
export type SoupParams = Params;
export type SoupBody = Omit<PostSoupRequest, keyof SoupParams>;
export type SoupItemsQueryFilters = EntityFilters;
export type SoupItemsQueryArgs = {
params: SoupParams;
body: SoupBody;
};
export type SoupAstParams = Params;
export type SoupAstBody = ApiEntityFilterAst & PostSoupAstRequestAllOf;
export type SoupAstItemsQueryArgs = {
params: SoupAstParams;
body: SoupAstBody;
groupBy?: GroupByField;
transport?: 'rest' | 'graphql';
};
export type SoupApiItemFilter = (item: SoupApiItem) => boolean;
interface SoupItemsQueryOptions {
networkPaused?: boolean;
keepPreviousData?: boolean;
enabled?: boolean;
staleTime?: StaleTime;
/** Channel navigation reads bounded unread evidence, not notification history. */
graphqlProjection?: 'channel-list';
/** Known entity identities for cache-first lookups. */
graphqlCacheFirstEntities?: readonly SoupEntityRef[];
/** Seed mixed lists from indexed non-email members; keep the full server query. */
graphqlLocalReconciliation?: 'without-email';
meta?: {
/** Keep view-specific REST previews out of the shared entity normalizer. */
normalize?: boolean;
groupBy?: GroupByField;
groupKey?: string;
itemFilter?: (item: SoupApiItem) => boolean;
/** Gates optimistic cache inserts only — fetched rows never run through it. */
insertFilter?: (item: SoupApiItem) => boolean;
};
showSupportedForeignEntities?: boolean;
/** Resets view-owned GraphQL state before a mutation-driven network refresh. */
onBeforeGraphqlRefresh?: () => void;
}
/**
* Cached page for `useSoupAstItemsQuery`. Discriminated by `kind`:
* - `grouped`: items pool keyed by id, `groups[].itemIds` describes order.
* Parent never paginates when grouped — per-group queries handle load-more.
* - `flat`: items array; standard infinite-query pagination.
*/
export type SoupAstItemsPage = SoupAstItemsGroupedPage | SoupAstItemsFlatPage;
export type SoupAstItemsGroupedPage = {
kind: 'grouped';
items: Record<string, SoupApiItem>;
groups: GroupMeta[];
nextCursor: null;
};
export type SoupAstItemsFlatPage = {
kind: 'flat';
items: SoupApiItem[];
nextCursor: string | null;
oldestFetchedTimestamp?: number;
};
export type SoupAstItemsData = {
/** Local Mail results cover synchronized metadata, not the entire mailbox. */
cachedMail?: boolean;
entities: EntityData[];
/** Descending page coverage, independent of optimistic/local row membership. */
oldestFetchedTimestamp?: number;
groups: GroupMeta[] | undefined;
/** Raw API item pool. Only present when query is grouped. */
itemsById?: SoupAstItemsGroupedPage['items'];
};
// Cached options outlive the view. Keep its accessors and query proxies out.
function soupItemsQueryOptions(
args: SoupItemsQueryArgs,
enabled: boolean | undefined,
staleTime: StaleTime | undefined,
showSupportedForeignEntities: boolean | undefined
) {
const { params, body } = args;
return infiniteQueryOptions({
queryKey: soupKeys.items(args).queryKey,
queryFn: (ctx) =>
throwOnErr(() =>
storageServiceClient.getSoupItems({
params: { cursor: ctx.pageParam },
body: { ...body, ...params },
})
),
initialPageParam: null as string | null,
getNextPageParam: (lastPage) => lastPage.next_cursor,
select: (data) =>
data.pages.flatMap((page) =>
mapSoupPageToEntityList(page, { showSupportedForeignEntities })
),
enabled,
staleTime,
placeholderData: keepPreviousData,
meta: {
itemFilter: (item: SoupApiItem) =>
!body || filterSoupItemByRequestBody(item, body),
normalize: true,
},
});
}
export const useSoupItemsQuery = (
args: Accessor<SoupItemsQueryArgs>,
options?: Accessor<SoupItemsQueryOptions>
) => {
return useInfiniteQuery(() =>
soupItemsQueryOptions(
args(),
options?.().enabled,
options?.().staleTime,
options?.().showSupportedForeignEntities
)
);
};
type RestSoupAstItemsMeta = SoupItemsQueryOptions['meta'];
async function fetchRestSoupAstItemsPage(
{ params, body, groupBy }: SoupAstItemsQueryArgs,
cursor: string | null,
requestSignal: AbortSignal
): Promise<SoupAstItemsPage> {
const signal = createSoupRequestSignal(requestSignal);
if (groupBy) {
const sort_method = groupedSortMethod(params.sort_method);
const response = await throwOnErr(
async () =>
await storageServiceClient.getGroupedSoupAstItems({
params: {
group_by: serializeGroupByField(groupBy),
per_group_limit: params.limit,
sort_method,
sort_property_definition_id: params.sort_property_definition_id,
sort_direction: params.sort_direction,
},
body,
signal,
})
);
return {
kind: 'grouped',
items: response.items,
groups: response.groups.map(parseGroupMeta),
nextCursor: null,
};
}
const response = await throwOnErr(
async () =>
await storageServiceClient.getSoupAstItems({
params: { cursor },
body: {
...body,
...params,
},
signal,
})
);
return {
kind: 'flat',
items: response.items,
nextCursor: response.next_cursor ?? null,
oldestFetchedTimestamp: soupPageTimestamp(
response.items.map(mapApiSoupItemToEntity),
params.sort_method
),
};
}
function getNextRestSoupAstPageParam(
lastPage: SoupAstItemsPage
): string | null {
if (lastPage.kind === 'grouped') return null;
return lastPage.nextCursor;
}
// Cached options outlive the view. Only plain snapshots enter here: no view
// accessors, option accessors, or query proxies.
function restSoupAstItemsQueryOptions(
args: SoupAstItemsQueryArgs,
enabled: boolean | undefined,
staleTime: StaleTime | undefined,
meta: RestSoupAstItemsMeta,
showSupportedForeignEntities: boolean | undefined,
keepPrevious: boolean | undefined
) {
const { params, body, groupBy, transport } = args;
return infiniteQueryOptions({
queryKey: soupKeys.astItems({ params, body, groupBy, transport }).queryKey,
queryFn: (ctx) =>
fetchRestSoupAstItemsPage(args, ctx.pageParam, ctx.signal),
initialPageParam: null as string | null,
getNextPageParam: getNextRestSoupAstPageParam,
select: (data): SoupAstItemsData => {
const firstPage = data.pages[0];
if (firstPage?.kind === 'grouped') {
const groups = firstPage.groups
.slice()
.sort(makeGroupComparator(groupBy));
const itemsById = firstPage.items;
const entities: EntityData[] = [];
for (const g of groups) {
for (const id of g.itemIds) {
const item = itemsById[id];
const displayable =
item.tag !== 'foreignEntity' ||
(showSupportedForeignEntities === true &&
item.data.foreignEntitySource === 'github_pull_request');
if (displayable && isDisplayableSoupItem(item)) {
const mapped = mapApiSoupItemToEntity(item);
entities.push(mapped);
}
}
}
return { entities, groups, itemsById };
}
const entities = data.pages.flatMap((page) => {
if (page.kind !== 'flat') return [];
return mapSoupPageToEntityList(
{ items: page.items, next_cursor: null },
{ showSupportedForeignEntities }
);
});
const pageTimestamps = data.pages.flatMap((page) =>
page.kind === 'flat' && page.oldestFetchedTimestamp !== undefined
? [page.oldestFetchedTimestamp]
: []
);
return {
entities,
groups: undefined,
oldestFetchedTimestamp:
pageTimestamps.length > 0 ? Math.min(...pageTimestamps) : undefined,
};
},
enabled,
// Do not spin through background retries while the explicit load-error
// state is visible. NWPathMonitor lets TanStack pause an offline query
// and resume it automatically when the path becomes available again.
...SOUP_NETWORK_QUERY_OPTIONS,
// A timed-out native request should reach the view's load-error state.
// Retry remains available explicitly from that state.
staleTime,
placeholderData: (prev, prevQuery) => {
if (keepPrevious === false) return undefined;
// Keep the previous rows on screen while params/filters change, but
// not across a grouping switch — the old groups would render under
// the new grouping (e.g. status groups while assignee groups load).
const prevGroupBy = (
prevQuery?.meta as SoupItemsQueryOptions['meta'] | undefined
)?.groupBy;
if (JSON.stringify(prevGroupBy) !== JSON.stringify(groupBy)) {
return undefined;
}
return prev;
},
meta: {
...meta,
groupBy,
normalize: meta?.normalize ?? true,
},
});
}
/** REST implementation kept private behind {@link useSoupAstItemsQuery}. */
const useRestSoupAstItemsQuery = (
args: Accessor<SoupAstItemsQueryArgs>,
options?: Accessor<SoupItemsQueryOptions>
) => {
return useInfiniteQuery(() =>
restSoupAstItemsQueryOptions(
args(),
options?.().enabled !== false && !options?.().networkPaused,
options?.().staleTime,
options?.().meta,
options?.().showSupportedForeignEntities,
options?.().keepPreviousData
)
);
};
/** 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 groupedPaging?: import('./graphql/create-grouped-soup-live-query').GroupedSoupPaging;
readonly data: SoupAstItemsData | undefined;
readonly error: Error | null;
readonly fetchError?: Error | null;
/** Includes paused initial requests, whose data resource is not readable yet. */
readonly isPending: boolean;
readonly isLoading: boolean;
readonly isFetching: boolean;
readonly isPlaceholderData: boolean;
readonly isFetchingNextPage: boolean;
/**
* The current error came from loading a continuation page; the loaded pages
* are still current. Any other error means the query itself failed.
*/
readonly isFetchNextPageError: boolean;
readonly isEnabled: boolean;
readonly hasNextPage: boolean;
readonly transport: SoupAstItemsQueryTransport;
readonly cacheStatus?: PredicateQueryStatus;
/** GraphQL reads used by transport-specific revalidation subscribers. */
readonly revalidationQueries?: readonly QueryRevalidation[];
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(enableGraphqlSoup);
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,
networkPaused: options?.().networkPaused,
keepPreviousData: options?.().keepPreviousData,
projection: options?.().graphqlProjection,
cacheFirstEntities: options?.().graphqlCacheFirstEntities,
localReconciliation: options?.().graphqlLocalReconciliation,
showSupportedForeignEntities: options?.().showSupportedForeignEntities,
})
);
const graphqlGroupedQuery = createGraphqlGroupedSoupAstItemsQuery(
() => ({
params: args().params,
body: args().body,
groupBy: args().groupBy,
}),
() => ({
enabled:
graphqlRequested() && queryEnabled() && args().groupBy !== undefined,
networkPaused: options?.().networkPaused,
keepPreviousData: options?.().keepPreviousData,
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(),
};
});
onCleanup(
registerActiveGraphqlSoupQuery({
isEnabled: () =>
usesGraphql() &&
activeGraphqlQuery().isEnabled() &&
!options?.().networkPaused,
// The refresh refetches every loaded page in cursor order and keeps the
// old pages on screen until their replacements arrive, so a mutation
// never collapses a scrolled list to its first page.
refresh: async () => {
if (args().groupBy === undefined)
options?.().onBeforeGraphqlRefresh?.();
await activeGraphqlQuery().refresh();
},
body: () => ({
...args().body,
params: args().params,
groupBy: args().groupBy,
}),
// Grouped lists don't report it yet, so writes still read them again.
cacheMaintained: () => activeGraphqlQuery().cacheMaintained?.() ?? false,
})
);
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 groupedPaging() {
return usesGraphql() ? activeGraphqlQuery().groupedPaging : undefined;
},
get data() {
return usesGraphql() ? activeGraphqlQuery().data() : restQuery.data;
},
get error() {
return usesGraphql()
? (activeGraphqlQuery().error() ?? null)
: (restQuery.error ?? null);
},
get fetchError() {
if (!usesGraphql()) return restQuery.error ?? null;
const query = activeGraphqlQuery();
return query.fetchError?.() ?? query.error() ?? null;
},
get isPending() {
if (!usesGraphql()) return restQuery.isPending;
const query = activeGraphqlQuery();
return (
query.isLoading() ||
(query.isEnabled() && query.data() === undefined && !query.error())
);
},
get isLoading() {
return usesGraphql()
? activeGraphqlQuery().isLoading()
: restQuery.isLoading;
},
get isFetching() {
return usesGraphql()
? activeGraphqlQuery().isFetching()
: restQuery.isFetching;
},
get isPlaceholderData() {
return usesGraphql()
? activeGraphqlQuery().isPlaceholderData()
: restQuery.isPlaceholderData;
},
get isFetchingNextPage() {
return usesGraphql()
? activeGraphqlQuery().isFetchingNextPage()
: restQuery.isFetchingNextPage;
},
get isFetchNextPageError() {
return usesGraphql()
? activeGraphqlQuery().isFetchNextPageError()
: restQuery.isFetchNextPageError;
},
get isEnabled() {
return usesGraphql()
? activeGraphqlQuery().isEnabled()
: restQuery.isEnabled;
},
get hasNextPage() {
return usesGraphql()
? activeGraphqlQuery().hasNextPage()
: (restQuery.hasNextPage ?? false);
},
get transport() {
return usesGraphql() ? 'graphql' : 'rest';
},
get cacheStatus() {
return usesGraphql()
? (activeGraphqlQuery().cacheStatus?.() ?? 'unsupported')
: 'unsupported';
},
get revalidationQueries() {
return usesGraphql()
? (activeGraphqlQuery().revalidationQueries?.() ?? [])
: [];
},
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 });
}
},
};
}