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.

Seanaye/perf/soup cache (#5478)

Sean Ayeb6544061e12d
diff --git a/Cargo.lock b/Cargo.lock
index 0143ec4775..c7a3d346e8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2445,7 +2445,7 @@ dependencies = [
[[package]]
name = "cache-wasm"
-version = "0.3.1"
+version = "0.3.2"
dependencies = [
"async-lock",
"cache-core",
diff --git a/apps/web/biome.jsonc b/apps/web/biome.jsonc
index e02728c156..60b2c9c824 100644
--- a/apps/web/biome.jsonc
+++ b/apps/web/biome.jsonc
@@ -15,6 +15,7 @@
"!chrome-extension-vite",
"!infra/web-app/output",
"!scripts",
+ "!.direnv",
"src/lib/service-clients/**/generated/**",
// graphql-codegen output; regenerated wholesale by `bun gen-graphql`
"!src/lib/service-clients/service-storage/graphql/generated",
diff --git a/apps/web/src/lib/graphql-cache/exchange/inspection.test.ts b/apps/web/src/lib/graphql-cache/exchange/inspection.test.ts
index aa5ef1dd35..4b9c3cf5f7 100644
--- a/apps/web/src/lib/graphql-cache/exchange/inspection.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/inspection.test.ts
@@ -6,7 +6,7 @@ import {
import { describe, expect, expectTypeOf, it, vi } from 'vitest';
import { createNoopCacheHost } from '../host/noop-host';
import type { CacheHost } from '../host/types';
-import { inspect, selectAll } from './inspection';
+import { inspect, inspectVariants, selectAll } from './inspection';
const input = {
initial: {
@@ -19,6 +19,27 @@ const input = {
};
describe('typed generated query inspection', () => {
+ it('discovers typed variables without materializing query values', async () => {
+ const inspectQueryVariants = async (request: unknown) => {
+ expect(request).toMatchObject({
+ operationName: 'GroupSoupMembership',
+ path: [{ field: 'user' }, { field: 'groupSoup' }],
+ });
+ expect(request).not.toHaveProperty('variables');
+ expect(request).not.toHaveProperty('variableFilters');
+ return [{ variables: { input } }];
+ };
+ const host = { inspectQueryVariants } as unknown as CacheHost;
+
+ const result = await inspectVariants(
+ host,
+ selectAll(GroupSoupMembershipDocument).field('user').field('groupSoup')
+ );
+
+ expect(result).toEqual([{ variables: { input } }]);
+ expect(result[0]).not.toHaveProperty('value');
+ });
+
it('serializes the document, field path, and typed variable filters', async () => {
const inspectQuery = async (request: unknown) => {
expect(request).toMatchObject({
@@ -81,11 +102,15 @@ describe('typed generated query inspection', () => {
// @ts-expect-error Lists cannot be traversed by v1 inspection paths.
selected.field('bins').field('length');
+ const variants = await inspectVariants(host, selected);
const results = await inspect(host, selected, {
variableFilters: [{ input: { initial: { limit: 20 } } }],
});
// @ts-expect-error Filters are typed from the generated operation variables.
inspect(host, selected, { variableFilters: [{ missing: true }] });
+ expectTypeOf(
+ variants[0]!.variables
+ ).toEqualTypeOf<GroupSoupMembershipQueryVariables>();
expectTypeOf(
results[0]!.variables
).toEqualTypeOf<GroupSoupMembershipQueryVariables>();
@@ -104,10 +129,13 @@ describe('typed generated query inspection', () => {
it('returns no selections through the no-op host', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
try {
- const result = await inspect(
- createNoopCacheHost('test'),
- selectAll(GroupSoupMembershipDocument).field('user').field('groupSoup')
- );
+ const host = createNoopCacheHost('test');
+ const selection = selectAll(GroupSoupMembershipDocument)
+ .field('user')
+ .field('groupSoup');
+ const variants = await inspectVariants(host, selection);
+ const result = await inspect(host, selection);
+ expect(variants).toEqual([]);
expect(result).toEqual([]);
} finally {
warn.mockRestore();
@@ -115,14 +143,18 @@ describe('typed generated query inspection', () => {
});
it('rejects malformed host results', async () => {
+ const selection = selectAll(GroupSoupMembershipDocument)
+ .field('user')
+ .field('groupSoup');
const host = {
inspectQuery: async () => [{ variables: null }],
+ inspectQueryVariants: async () => [{ variables: null }],
} as unknown as CacheHost;
- await expect(
- inspect(
- host,
- selectAll(GroupSoupMembershipDocument).field('user').field('groupSoup')
- )
- ).rejects.toThrow('invalid cache query inspection instance');
+ await expect(inspectVariants(host, selection)).rejects.toThrow(
+ 'invalid cache query inspection variant'
+ );
+ await expect(inspect(host, selection)).rejects.toThrow(
+ 'invalid cache query inspection instance'
+ );
});
});
diff --git a/apps/web/src/lib/graphql-cache/exchange/inspection.ts b/apps/web/src/lib/graphql-cache/exchange/inspection.ts
index 891292010b..d360f34bab 100644
--- a/apps/web/src/lib/graphql-cache/exchange/inspection.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/inspection.ts
@@ -2,15 +2,18 @@
* Generated-operation cache inspection.
*
* Callers select one response field without supplying concrete variables.
- * Cache-core discovers cached argument variants, filters them before
- * materialization when requested, and returns generated variables plus the
- * selected effective value when the complete query is available.
+ * They can recover typed cached variable variants without materialization, or
+ * request selected effective values for complete cached queries.
*/
import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { type AnyVariables, stringifyDocument } from '@urql/core';
import type { CacheHost } from '../host/types';
-import type { CachedQueryInstanceWire, QueryVariableFilter } from '../protocol';
+import type {
+ CachedQueryInstanceWire,
+ CachedQueryVariantWire,
+ QueryVariableFilter,
+} from '../protocol';
import {
documentOperationName,
type ObjectFieldKey,
@@ -41,9 +44,13 @@ export type InspectionSelection<TValue, TVariables> =
): InspectionSelection<Present<TValue>[K], TVariables>;
});
-/** One cached generated operation-variable instance and selected value. */
-export type CachedSelection<TValue, TVariables> = {
+/** One cached generated operation-variable variant. */
+export type CachedVariant<TVariables> = {
variables: TVariables;
+};
+
+/** One cached generated operation-variable instance and selected value. */
+export type CachedSelection<TValue, TVariables> = CachedVariant<TVariables> & {
/** Absent when the field exists but the complete generated query is a miss. */
value?: TValue;
};
@@ -89,6 +96,18 @@ function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
+function validateVariants(value: unknown): CachedQueryVariantWire[] {
+ if (!Array.isArray(value)) {
+ throw new Error('invalid cache query variant inspection result');
+ }
+ return value.map((variant) => {
+ if (!isRecord(variant) || !isRecord(variant.variables)) {
+ throw new Error('invalid cache query inspection variant');
+ }
+ return { variables: variant.variables };
+ });
+}
+
function validateInstances(value: unknown): CachedQueryInstanceWire[] {
if (!Array.isArray(value)) {
throw new Error('invalid cache query inspection result');
@@ -104,6 +123,26 @@ function validateInstances(value: unknown): CachedQueryInstanceWire[] {
});
}
+/**
+ * Recovers every cached variable variant without materializing selected
+ * values. Only the serialized document, operation name, and response-key path
+ * cross the host boundary.
+ */
+export async function inspectVariants<TValue, TVariables extends AnyVariables>(
+ host: CacheHost,
+ selection: InspectionSelection<TValue, TVariables>
+): Promise<CachedVariant<TVariables>[]> {
+ if (selection.path.length === 0) {
+ throw new Error('cache query inspection requires a selected field');
+ }
+ const result: unknown = await host.inspectQueryVariants({
+ query: stringifyDocument(selection.document),
+ operationName: documentOperationName(selection.document),
+ path: [...selection.path],
+ });
+ return validateVariants(result) as CachedVariant<TVariables>[];
+}
+
/**
* Enumerates matching cached argument variants of one generated selected
* field. Only the serialized document, operation name, response-key path, and
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
index 3c6a19d9d4..6b92dff8af 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts
@@ -220,6 +220,9 @@ function makeFakeHost(): FakeHost {
reset: false,
};
},
+ async inspectQueryVariants() {
+ return [];
+ },
async inspectQuery() {
return [];
},
diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.ts
index 4e61c4d8a5..8f14c1ea5b 100644
--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts
@@ -37,6 +37,9 @@ export function createNoopCacheHost(reason: string): CacheHost {
async beginOptimisticWrite(): Promise<OptimisticWriteResult> {
throw new Error('normalized GraphQL cache is unavailable');
},
+ async inspectQueryVariants() {
+ return [];
+ },
async inspectQuery() {
return [];
},
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
index 24d58ce63e..a1fd1d3c44 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
@@ -187,29 +187,42 @@ describe('createTauriCacheHost', () => {
);
});
- it('inspects generated query variants through the native command', async () => {
- const instances = [
- {
- variables: { input: { initial: { limit: 20 } } },
- value: { bins: [] },
- },
- ];
+ it('inspects generated query variants through the native commands', async () => {
+ const variants = [{ variables: { input: { initial: { limit: 20 } } } }];
+ const instances = variants.map((variant) => ({
+ ...variant,
+ value: { bins: [] },
+ }));
invokeMock.mockImplementation((command: string) =>
Promise.resolve(
- command === 'graphql_cache_inspect_query' ? instances : null
+ command === 'graphql_cache_inspect_query'
+ ? instances
+ : command === 'graphql_cache_inspect_query_variants'
+ ? variants
+ : null
)
);
const host = createTauriCacheHost({ scope: 'scope-1' });
- const request = {
+ const variantRequest = {
query:
'query Views($input: GroupedSoupInput!) { user { groupSoup(input: $input) { bins { key } } } }',
operationName: 'Views',
path: [{ field: 'user' }, { field: 'groupSoup' }],
+ };
+ const request = {
+ ...variantRequest,
variableFilters: [
{ input: { initial: { groupBy: { field: 'PROPERTY' } } } },
],
};
+ await expect(host.inspectQueryVariants(variantRequest)).resolves.toEqual(
+ variants
+ );
+ expect(invokeMock).toHaveBeenCalledWith(
+ 'graphql_cache_inspect_query_variants',
+ variantRequest
+ );
await expect(host.inspectQuery(request)).resolves.toEqual(instances);
expect(invokeMock).toHaveBeenCalledWith(
'graphql_cache_inspect_query',
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
index dc568fd1c3..d121f0c833 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -11,6 +11,7 @@ import { invoke } from '@tauri-apps/api/core';
import { listen, type UnlistenFn } from '@tauri-apps/api/event';
import {
type CachedQueryInstanceWire,
+ type CachedQueryVariantWire,
type ClaimedMutation,
type MutationClaim,
type MutationSettlement,
@@ -27,6 +28,7 @@ import type {
CacheReadArgs,
CacheWriteArgs,
InspectQueryArgs,
+ InspectQueryVariantsArgs,
} from './types';
/** Keep in sync with `OPS_AFFECTED_EVENT` in graphql_cache_plugin. */
@@ -197,6 +199,20 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
);
},
+ async inspectQueryVariants(
+ args: InspectQueryVariantsArgs
+ ): Promise<CachedQueryVariantWire[]> {
+ await ready;
+ return await request<CachedQueryVariantWire[]>(
+ 'graphql_cache_inspect_query_variants',
+ {
+ query: args.query,
+ operationName: args.operationName,
+ path: args.path,
+ }
+ );
+ },
+
async inspectQuery(
args: InspectQueryArgs
): Promise<CachedQueryInstanceWire[]> {
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index 52cd3729f7..6b0f0bd1be 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -7,6 +7,7 @@
import type {
CachedQueryInstanceWire,
+ CachedQueryVariantWire,
CacheReadPriority,
ClaimedMutation,
MutationClaim,
@@ -40,6 +41,12 @@ export interface InspectQueryArgs {
variableFilters?: QueryVariableFilter[];
}
+/** Variables-only inspection always discovers every cached variant. */
+export type InspectQueryVariantsArgs = Omit<
+ InspectQueryArgs,
+ 'variableFilters'
+>;
+
export interface CacheWriteArgs extends Omit<CacheReadArgs, 'priority'> {
data: unknown;
/** Opaque session tag; see protocol.ts `identity`. */
@@ -66,7 +73,11 @@ export interface CacheHost {
beginOptimisticWrite(
args: BeginOptimisticWriteArgs
): Promise<OptimisticWriteResult>;
- /** Enumerates cached variants of one generated query field selection. */
+ /** Recovers variables for cached variants without materializing values. */
+ inspectQueryVariants(
+ args: InspectQueryVariantsArgs
+ ): Promise<CachedQueryVariantWire[]>;
+ /** Enumerates and materializes cached query field variants. */
inspectQuery(args: InspectQueryArgs): Promise<CachedQueryInstanceWire[]>;
/** Claims the oldest runnable mutation; later entries are never skipped. */
claimNextMutation(
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
index f323102eb2..f7d9854067 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts
@@ -38,9 +38,11 @@ describe('createWorkerCacheHost', () => {
it('round-trips generated query inspection through the worker protocol', async () => {
const requests: unknown[] = [];
- const instances = [
- { variables: { input: { initial: { limit: 20 } } }, value: { bins: [] } },
- ];
+ const variants = [{ variables: { input: { initial: { limit: 20 } } } }];
+ const instances = variants.map((variant) => ({
+ ...variant,
+ value: { bins: [] },
+ }));
class FakeSharedWorker {
port = {
onmessage: null as ((event: MessageEvent) => void) | null,
@@ -54,7 +56,12 @@ describe('createWorkerCacheHost', () => {
data: {
id: request.id,
ok: true,
- result: request.kind === 'inspect-query' ? instances : null,
+ result:
+ request.kind === 'inspect-query'
+ ? instances
+ : request.kind === 'inspect-query-variants'
+ ? variants
+ : null,
},
} as MessageEvent);
});
@@ -63,16 +70,34 @@ describe('createWorkerCacheHost', () => {
}
vi.stubGlobal('SharedWorker', FakeSharedWorker);
const host = createWorkerCacheHost({ scope: 'scope-1' });
- const request = {
+ const variantRequest = {
query:
'query Views($input: GroupedSoupInput!) { user { groupSoup(input: $input) { bins { key } } } }',
operationName: 'Views',
path: [{ field: 'user' }, { field: 'groupSoup' }],
+ };
+ const request = {
+ ...variantRequest,
variableFilters: [
{ input: { initial: { groupBy: { field: 'PROPERTY' } } } },
],
};
+ await expect(host.inspectQueryVariants(variantRequest)).resolves.toEqual(
+ variants
+ );
+ expect(requests).toContainEqual(
+ expect.objectContaining({
+ kind: 'inspect-query-variants',
+ ...variantRequest,
+ })
+ );
+ expect(
+ requests.find(
+ (candidate) =>
+ (candidate as { kind?: string }).kind === 'inspect-query-variants'
+ )
+ ).not.toHaveProperty('variableFilters');
await expect(host.inspectQuery(request)).resolves.toEqual(instances);
expect(requests).toContainEqual(
expect.objectContaining({ kind: 'inspect-query', ...request })
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 9be4a564d5..ae5ba711ce 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -5,6 +5,7 @@
import {
type CachedQueryInstanceWire,
+ type CachedQueryVariantWire,
type CacheNotice,
type CacheRequest,
type ClaimedMutation,
@@ -26,6 +27,7 @@ import type {
CacheReadArgs,
CacheWriteArgs,
InspectQueryArgs,
+ InspectQueryVariantsArgs,
} from './types';
type Pending = {
@@ -140,7 +142,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
if (
msg.kind === 'read' ||
msg.kind === 'read-records' ||
- msg.kind === 'inspect-query'
+ msg.kind === 'inspect-query' ||
+ msg.kind === 'inspect-query-variants'
) {
entry.timer = setTimeout(() => {
if (pending.delete(id)) {
@@ -227,6 +230,18 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
})) as OptimisticWriteResult;
},
+ async inspectQueryVariants(
+ args: InspectQueryVariantsArgs
+ ): Promise<CachedQueryVariantWire[]> {
+ await ready;
+ return (await request({
+ kind: 'inspect-query-variants',
+ query: args.query,
+ operationName: args.operationName,
+ path: args.path,
+ })) as CachedQueryVariantWire[];
+ },
+
async inspectQuery(
args: InspectQueryArgs
): Promise<CachedQueryInstanceWire[]> {
diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.ts
index cbbf9607cb..f86e3fbbf6 100644
--- a/apps/web/src/lib/graphql-cache/index.ts
+++ b/apps/web/src/lib/graphql-cache/index.ts
@@ -5,8 +5,10 @@
export {
type CachedSelection,
+ type CachedVariant,
type InspectionSelection,
inspect,
+ inspectVariants,
selectAll,
} from './exchange/inspection';
export {
@@ -36,10 +38,12 @@ export type {
CacheReadArgs,
CacheWriteArgs,
InspectQueryArgs,
+ InspectQueryVariantsArgs,
} from './host/types';
export { createWorkerCacheHost } from './host/worker-host';
export type {
CachedQueryInstanceWire,
+ CachedQueryVariantWire,
CachePush,
CacheReadPriority,
CacheRequest,
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 1f0f05b9a1..96f38638b7 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -80,8 +80,11 @@ export type OptimisticLinkPatchWire = {
| { kind: 'prependUnique'; entityKey: string };
};
-export type CachedQueryInstanceWire = {
+export type CachedQueryVariantWire = {
variables: Record<string, unknown>;
+};
+
+export type CachedQueryInstanceWire = CachedQueryVariantWire & {
/** Selected value; omitted when the reconstructed query is a cache miss. */
value?: unknown;
};
@@ -224,6 +227,13 @@ export type CacheRequest = { id: number } & (
/** OR-ed recursive partial matches applied before result materialization. */
variableFilters?: QueryVariableFilter[];
}
+ | {
+ kind: 'inspect-query-variants';
+ query: string;
+ operationName?: string;
+ /** Response-key field path from the query root. */
+ path: Array<{ field: string }>;
+ }
| { kind: 'teardown'; opId: string }
/** External invalidation (e.g. websocket push): evict + report ops. */
| { kind: 'invalidate'; keys: string[] }
diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
index d1056bc1fc..5325df8fdb 100644
--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts
@@ -10,6 +10,7 @@
import type {
CachedQueryInstanceWire,
+ CachedQueryVariantWire,
ClaimedMutation,
OptimisticLinkPatchWire,
OptimisticWriteResult,
@@ -52,6 +53,11 @@ export interface CacheEngine {
revalidations: QueryRevalidationWire[] | undefined,
createdAtMs: number
): Promise<OptimisticWriteResult>;
+ inspectQueryVariants(
+ query: string,
+ operationName: string | undefined,
+ path: Array<{ field: string }>
+ ): Promise<CachedQueryVariantWire[]>;
inspectQuery(
query: string,
operationName: string | undefined,
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
index 569547d23e..83bdfa6d3d 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts
@@ -274,6 +274,36 @@ describe('CacheWorkerCore', () => {
).toHaveLength(2);
});
+ it('dispatches variables-only inspection to the wasm engine', async () => {
+ const variants = [{ variables: { input: { initial: { limit: 20 } } } }];
+ const inspectQueryVariants = vi.fn().mockResolvedValue(variants);
+ loadCacheWasmMock.mockResolvedValue({
+ openCache: vi.fn().mockResolvedValue({ inspectQueryVariants }),
+ });
+ const messages: unknown[] = [];
+ const port = { postMessage: (message: unknown) => messages.push(message) };
+ const core = new CacheWorkerCore();
+ const query =
+ 'query Views($input: GroupedSoupInput!) { user { groupSoup(input: $input) { bins { key } } } }';
+ const path = [{ field: 'user' }, { field: 'groupSoup' }];
+
+ await core.handleRequest(port, {
+ id: 1,
+ kind: 'init',
+ scope: 'scope-1',
+ });
+ await core.handleRequest(port, {
+ id: 2,
+ kind: 'inspect-query-variants',
+ query,
+ operationName: 'Views',
+ path,
+ });
+
+ expect(inspectQueryVariants).toHaveBeenCalledWith(query, 'Views', path);
+ expect(messages.at(-1)).toEqual({ id: 2, ok: true, result: variants });
+ });
+
it('pushes cache changes even without affected operations', async () => {
const writeResult = {
changed: ['GraphqlSoupDocument:doc-1'],
diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
index 237977bc9d..057e402d58 100644
--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts
+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts
@@ -238,6 +238,13 @@ export class CacheWorkerCore {
this.fanOut(result, true);
return result;
})
+ .with({ kind: 'inspect-query-variants' }, async (request) => {
+ return await this.requireEngine().inspectQueryVariants(
+ request.query,
+ request.operationName,
+ request.path
+ );
+ })
.with({ kind: 'inspect-query' }, async (request) => {
return await this.requireEngine().inspectQuery(
request.query,
diff --git a/apps/web/src/lib/queries/history/history.ts b/apps/web/src/lib/queries/history/history.ts
index 5019d70e08..b4efcaf194 100644
--- a/apps/web/src/lib/queries/history/history.ts
+++ b/apps/web/src/lib/queries/history/history.ts
@@ -7,7 +7,6 @@ import { catchToResult, throwOnErr } from '@core/util/result';
import { type MutationCallbacks, withCallbacks } from '@queries/utils';
import { type ItemType, storageServiceClient } from '@service-storage/client';
import { getGraphqlSoupCacheHost } from '@service-storage/graphql-soup';
-import { debounce } from '@solid-primitives/scheduled';
import {
type QueryClient,
type QueryKey,
@@ -15,9 +14,8 @@ import {
type Updater,
useMutation,
useQuery,
- useQueryClient,
} from '@tanstack/solid-query';
-import { type Accessor, createEffect, onCleanup, type Setter } from 'solid-js';
+import type { Accessor, Setter } from 'solid-js';
import { queryClient } from '../client';
import { readCachedGraphqlHistoryItems } from './graphql';
import { historyKeys } from './keys';
@@ -29,7 +27,7 @@ export type { HistoryItem } from './types';
const HISTORY_STALE_TIME = 5 * 60 * 1000;
const HISTORY_GC_TIME = 10 * 60 * 1000;
-const HISTORY_CACHE_REFRESH_DEBOUNCE_MS = 250;
+const _HISTORY_CACHE_REFRESH_DEBOUNCE_MS = 250;
type HistoryQueryFnResult = HistoryItem[];
@@ -94,31 +92,12 @@ export function useHistoryQuery() {
const graphqlSoupFlag = useFeatureFlag(ENABLE_GRAPHQL_SOUP_FLAG, {
enabledOverride: ENABLE_GRAPHQL_SOUP_OVERRIDE,
});
- const activeQueryClient = useQueryClient();
const graphqlCacheHost = () => {
if (!graphqlSoupFlag().enabled) return undefined;
const cacheHost = getGraphqlSoupCacheHost();
return cacheHost?.disabled ? undefined : cacheHost;
};
- createEffect(() => {
- const cacheHost = graphqlCacheHost();
- if (!cacheHost) return;
-
- const scheduleCacheRefresh = debounce(() => {
- void activeQueryClient.invalidateQueries({
- queryKey: historyKeys.graphqlList.queryKey,
- });
- }, HISTORY_CACHE_REFRESH_DEBOUNCE_MS);
- const unsubscribeCacheChanges =
- cacheHost.onCacheChanged(scheduleCacheRefresh);
-
- onCleanup(() => {
- unsubscribeCacheChanges();
- scheduleCacheRefresh.clear();
- });
- });
-
return useQuery<HistoryQueryFnResult, Error, HistoryQueryFnResult, QueryKey>(
() => {
const cacheHost = graphqlCacheHost();
diff --git a/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.test.ts b/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.test.ts
index 5a8e13556a..e18bb332b0 100644
--- a/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.test.ts
+++ b/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.test.ts
@@ -1,28 +1,39 @@
-import type { CacheHost, InspectQueryArgs } from '@graphql-cache/host/types';
+import type {
+ CacheHost,
+ CacheReadArgs,
+ InspectQueryVariantsArgs,
+} from '@graphql-cache/host/types';
import { describe, expect, it, vi } from 'vitest';
import { registerGroupedSoupContinuation } from './graphql-operation-registry';
import { buildOptimisticGroupedPropertyUpdates } from './graphql-optimistic';
-const input = {
- initial: {
- groupBy: {
- field: 'PROPERTY' as const,
- propertyDefinitionId: 'status-def',
+function initialInput(propertyDefinitionId: string) {
+ return {
+ initial: {
+ groupBy: {
+ field: 'PROPERTY' as const,
+ propertyDefinitionId,
+ },
+ limit: 20,
},
- limit: 20,
- },
-};
+ };
+}
-const continuationInput = {
- continuation: {
- groupBy: {
- field: 'PROPERTY' as const,
- propertyDefinitionId: 'status-def',
+function continuationInput(propertyDefinitionId: string) {
+ return {
+ continuation: {
+ groupBy: {
+ field: 'PROPERTY' as const,
+ propertyDefinitionId,
+ },
+ groupKey: 'in-progress',
+ cursor: 'cursor-1',
},
- groupKey: 'in-progress',
- cursor: 'cursor-1',
- },
-};
+ };
+}
+
+const input = initialInput('status-def');
+const continuation = continuationInput('status-def');
function host(args?: {
destination?: boolean;
@@ -30,9 +41,13 @@ function host(args?: {
continuation?: boolean;
initialContainsItem?: boolean;
miss?: boolean;
- onInspect?: (request: InspectQueryArgs) => void;
+ onDiscover?: (propertyDefinitionIds: string[]) => void;
+ onInspect?: (request: InspectQueryVariantsArgs) => void;
+ onRead?: (request: CacheReadArgs) => void;
+ relevantPropertyDefinitionId?: string;
sourceKey?: string;
typename?: 'GraphqlSoupCall' | 'GraphqlSoupDocument';
+ unrelatedPropertyDefinitionIds?: readonly string[];
}): CacheHost {
const value = (containsItem: boolean) => ({
bins: [
@@ -61,12 +76,20 @@ function host(args?: {
]),
],
});
+ const relevantPropertyDefinitionId =
+ args?.relevantPropertyDefinitionId ?? 'status-def';
+ const relevantInput = initialInput(relevantPropertyDefinitionId);
+ const relevantContinuation = continuationInput(relevantPropertyDefinitionId);
const instances: Array<{
- variables: { input: typeof input | typeof continuationInput };
+ variables: {
+ input:
+ | ReturnType<typeof initialInput>
+ | ReturnType<typeof continuationInput>;
+ };
value?: ReturnType<typeof value>;
}> = [
{
- variables: { input },
+ variables: { input: relevantInput },
...(args?.miss
? {}
: { value: value(args?.initialContainsItem !== false) }),
@@ -74,32 +97,47 @@ function host(args?: {
];
if (args?.continuation) {
instances.push({
- variables: { input: continuationInput },
+ variables: { input: relevantContinuation },
value: value(true),
});
}
- if (args?.includeUnrelated) {
+ const unrelatedPropertyDefinitionIds = [
+ ...(args?.includeUnrelated ? ['priority-def'] : []),
+ ...(args?.unrelatedPropertyDefinitionIds ?? []),
+ ];
+ for (const propertyDefinitionId of unrelatedPropertyDefinitionIds) {
instances.push({
- variables: {
- input: {
- initial: {
- groupBy: {
- field: 'PROPERTY',
- propertyDefinitionId: 'priority-def',
- },
- limit: 20,
- },
- },
- },
+ variables: { input: initialInput(propertyDefinitionId) },
value: value(true),
});
}
return {
clientId: 'test',
- async inspectQuery(request: InspectQueryArgs) {
+ async inspectQueryVariants(request: InspectQueryVariantsArgs) {
args?.onInspect?.(request);
- return instances;
+ args?.onDiscover?.(
+ instances.map(({ variables }) => {
+ const page =
+ 'initial' in variables.input
+ ? variables.input.initial
+ : variables.input.continuation;
+ return String(page.groupBy.propertyDefinitionId);
+ })
+ );
+ return instances.map(({ variables }) => ({ variables }));
+ },
+ async readQuery(request: CacheReadArgs) {
+ args?.onRead?.(request);
+ const instance = instances.find(
+ ({ variables }) =>
+ JSON.stringify(variables) === JSON.stringify(request.variables)
+ );
+ if (!instance?.value) return { kind: 'miss' as const };
+ return {
+ kind: 'hit' as const,
+ data: { user: { groupSoup: instance.value } },
+ };
},
} as unknown as CacheHost;
}
@@ -107,8 +145,9 @@ function host(args?: {
describe('buildOptimisticGroupedPropertyUpdates', () => {
it('builds source removal then destination prepend for a status move', async () => {
const onInspect = vi.fn();
+ const onRead = vi.fn();
const result = await buildOptimisticGroupedPropertyUpdates({
- host: host({ includeUnrelated: true, onInspect }),
+ host: host({ includeUnrelated: true, onInspect, onRead }),
entityId: 'task-1',
propertyDefinitionId: 'status-def',
oldGroupKeys: ['in-progress'],
@@ -139,30 +178,54 @@ describe('buildOptimisticGroupedPropertyUpdates', () => {
expect(result.revalidations).toHaveLength(1);
expect(onInspect).toHaveBeenCalledWith(
expect.objectContaining({
- variableFilters: [
- {
- input: {
- initial: {
- groupBy: {
- field: 'PROPERTY',
- propertyDefinitionId: 'status-def',
- },
- },
- },
- },
- {
- input: {
- continuation: {
- groupBy: {
- field: 'PROPERTY',
- propertyDefinitionId: 'status-def',
- },
- },
- },
- },
- ],
+ operationName: 'GroupSoupMembership',
+ path: [{ field: 'user' }, { field: 'groupSoup' }],
})
);
+ expect(onInspect.mock.calls[0]?.[0]).not.toHaveProperty('variableFilters');
+ expect(onRead).toHaveBeenCalledTimes(1);
+ expect(onRead).toHaveBeenCalledWith(
+ expect.objectContaining({
+ variables: { input },
+ priority: 'user-visible',
+ })
+ );
+ });
+
+ it('discovers unrelated status, assignee, and priority variants without reading them', async () => {
+ const onDiscover = vi.fn();
+ const onRead = vi.fn();
+ const result = await buildOptimisticGroupedPropertyUpdates({
+ host: host({
+ onDiscover,
+ onRead,
+ relevantPropertyDefinitionId: 'target-def',
+ unrelatedPropertyDefinitionIds: [
+ 'status-def',
+ 'assignee-def',
+ 'priority-def',
+ ],
+ }),
+ entityId: 'task-1',
+ propertyDefinitionId: 'target-def',
+ oldGroupKeys: ['in-progress'],
+ newGroupKeys: ['completed'],
+ });
+
+ expect(result.updates).toHaveLength(2);
+ expect(onDiscover).toHaveBeenCalledWith([
+ 'target-def',
+ 'status-def',
+ 'assignee-def',
+ 'priority-def',
+ ]);
+ expect(onRead).toHaveBeenCalledTimes(1);
+ expect(
+ onRead.mock.calls.map(
+ ([request]) =>
+ request.variables.input.initial.groupBy.propertyDefinitionId
+ )
+ ).toEqual(['target-def']);
});
it('derives the normalized key from the inspected typename and id', async () => {
@@ -194,9 +257,14 @@ describe('buildOptimisticGroupedPropertyUpdates', () => {
});
it('removes from a registered continuation and prepends to its initial page', async () => {
- registerGroupedSoupContinuation(input, continuationInput);
+ registerGroupedSoupContinuation(input, continuation);
+ const onRead = vi.fn();
const result = await buildOptimisticGroupedPropertyUpdates({
- host: host({ continuation: true, initialContainsItem: false }),
+ host: host({
+ continuation: true,
+ initialContainsItem: false,
+ onRead,
+ }),
entityId: 'task-1',
propertyDefinitionId: 'status-def',
oldGroupKeys: ['in-progress'],
@@ -208,7 +276,10 @@ describe('buildOptimisticGroupedPropertyUpdates', () => {
(update) =>
(JSON.parse(update.variablesJson) as { input: unknown }).input
)
- ).toEqual([continuationInput, input]);
+ ).toEqual([continuation, input]);
+ expect(
+ onRead.mock.calls.map(([request]) => request.variables.input)
+ ).toEqual([input, continuation]);
expect(result.updates.map((patch) => patch.operation.kind)).toEqual([
'remove',
'prependUnique',
@@ -245,8 +316,9 @@ describe('buildOptimisticGroupedPropertyUpdates', () => {
});
it('revalidates a relevant cached variant whose complete query is a miss', async () => {
+ const onRead = vi.fn();
const result = await buildOptimisticGroupedPropertyUpdates({
- host: host({ miss: true }),
+ host: host({ miss: true, onRead }),
entityId: 'task-1',
propertyDefinitionId: 'status-def',
oldGroupKeys: ['in-progress'],
@@ -256,6 +328,7 @@ describe('buildOptimisticGroupedPropertyUpdates', () => {
expect(result.updates).toEqual([]);
expect(result.revalidations).toHaveLength(1);
expect(result.revalidations[0]?.variables).toEqual({ input });
+ expect(onRead).toHaveBeenCalledOnce();
});
it('skips inspection when group-key sets are equivalent', async () => {
@@ -273,8 +346,9 @@ describe('buildOptimisticGroupedPropertyUpdates', () => {
});
it('returns revalidation only for unsupported values', async () => {
+ const onRead = vi.fn();
const result = await buildOptimisticGroupedPropertyUpdates({
- host: host(),
+ host: host({ onRead }),
entityId: 'task-1',
propertyDefinitionId: 'status-def',
oldGroupKeys: [],
@@ -284,5 +358,6 @@ describe('buildOptimisticGroupedPropertyUpdates', () => {
expect(result.updates).toEqual([]);
expect(result.revalidations).toHaveLength(1);
+ expect(onRead).not.toHaveBeenCalled();
});
});
diff --git a/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.ts b/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.ts
index fe55732e75..bcfe73dc2c 100644
--- a/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.ts
+++ b/apps/web/src/lib/queries/soup/grouped/graphql-optimistic.ts
@@ -1,4 +1,5 @@
-import { inspect, selectAll } from '@graphql-cache/exchange/inspection';
+import { documentOperationName } from '@graphql-cache/exchange/generated-selection';
+import { inspectVariants, selectAll } from '@graphql-cache/exchange/inspection';
import {
type OptimisticUpdate,
prependUnique,
@@ -8,6 +9,7 @@ import {
update,
} from '@graphql-cache/exchange/optimistic';
import type { CacheHost } from '@graphql-cache/host/types';
+import { stringifyDocument } from '@urql/core';
import {
type GroupedSoupInput,
GroupSoupMembershipDocument,
@@ -101,27 +103,14 @@ export async function buildOptimisticGroupedPropertyUpdates(
return { updates: [], revalidations: [] };
}
- const relevantGroupBy = {
- field: 'PROPERTY' as const,
- propertyDefinitionId: args.propertyDefinitionId,
- };
- const cachedViews = await inspect(
- args.host,
- selectAll(GroupSoupMembershipDocument).field('user').field('groupSoup'),
- {
- // Filter inside cache-core before each variant is denormalized. Without
- // this, editing one property reads every cached grouped view first and
- // discards unrelated groupings only after crossing the worker boundary.
- variableFilters: [
- { input: { initial: { groupBy: relevantGroupBy } } },
- { input: { continuation: { groupBy: relevantGroupBy } } },
- ],
- }
- );
- const relevantViews = cachedViews.filter(({ variables }) =>
+ const selection = selectAll(GroupSoupMembershipDocument)
+ .field('user')
+ .field('groupSoup');
+ const variants = await inspectVariants(args.host, selection);
+ const relevantVariants = variants.filter(({ variables }) =>
isRelevantPropertyGrouping(variables.input, args.propertyDefinitionId)
);
- const revalidations: QueryRevalidation[] = relevantViews.map(
+ const revalidations: QueryRevalidation[] = relevantVariants.map(
({ variables }) => ({
document: GroupSoupMembershipDocument,
variables,
@@ -131,10 +120,23 @@ export async function buildOptimisticGroupedPropertyUpdates(
return { updates: [], revalidations };
}
+ const query = stringifyDocument(selection.document);
+ const operationName = documentOperationName(selection.document);
+ const loadedPages = await Promise.all(
+ relevantVariants.map(async ({ variables }): Promise<GroupPage | null> => {
+ const result = await args.host.readQuery({
+ query,
+ operationName,
+ variables,
+ priority: 'user-visible',
+ });
+ if (result.kind === 'miss') return null;
+ const data = result.data as GroupSoupMembershipQuery;
+ return { input: variables.input, bins: data.user.groupSoup.bins };
+ })
+ );
const views = groupPagesByLogicalView(
- relevantViews.flatMap(({ variables, value }) =>
- value ? [{ input: variables.input, bins: value.bins }] : []
- )
+ loadedPages.filter((page): page is GroupPage => page !== null)
);
const { removed, added } = changes;
const updates: OptimisticUpdate[] = [];
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
index 3921ba4846..a43b83d276 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
@@ -16,7 +16,7 @@ use crate::{
CacheState, InitializedCache, emit_cache_changed, emit_mutation_settled, emit_ops_affected,
};
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
-use cache_core::query_inspection::CachedQueryInstance;
+use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant};
use cache_core::record_selection::{RecordCursor, SelectedRecordPage};
use cache_sqlite::SqliteStorage;
use serde::Deserialize;
@@ -175,7 +175,24 @@ pub struct InspectionPathSegment {
pub field: String,
}
-/// Enumerates cached variants of one generated query field.
+/// Recovers cached query variables without materializing each variant.
+#[tauri::command]
+pub async fn graphql_cache_inspect_query_variants(
+ state: State<'_, CacheState>,
+ query: String,
+ operation_name: Option<String>,
+ path: Vec<InspectionPathSegment>,
+) -> Result<Vec<CachedQueryVariant>, String> {
+ engine_handle(&state)?
+ .inspect_query_variants(
+ query,
+ operation_name,
+ path.into_iter().map(|segment| segment.field).collect(),
+ )
+ .await
+}
+
+/// Enumerates and materializes cached variants of one generated query field.
#[tauri::command]
pub async fn graphql_cache_inspect_query(
state: State<'_, CacheState>,
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
index b5a41bfbbd..6900cf546b 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
@@ -14,7 +14,7 @@
use cache_core::deps::OpId;
use cache_core::engine::{BeginOptimisticWrite, Engine, ReadResult, WriteResult};
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
-use cache_core::query_inspection::{CachedQueryInstance, QueryInspection};
+use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant, QueryInspection};
use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};
use cache_core::record_selection::{RecordCursor, RecordSelection, SelectedRecordPage};
use cache_core::value::EntityKey;
@@ -215,8 +215,8 @@ impl EngineHandle {
cursor: Option<RecordCursor>,
limit: u32,
) -> Result<SelectedRecordPage, String> {
- let selection = RecordSelection::parse(&document, &fragment_name)
- .map_err(|error| error.to_string())?;
+ let selection =
+ RecordSelection::parse(&document, &fragment_name).map_err(|error| error.to_string())?;
self.inner
.lock()
.await
@@ -226,7 +226,28 @@ impl EngineHandle {
.map_err(|error| error.to_string())
}
- /// Enumerates cached variants of one generated query field.
+ /// Recovers cached query variables without materializing each variant.
+ pub async fn inspect_query_variants(
+ &self,
+ query: String,
+ operation_name: Option<String>,
+ path: Vec<String>,
+ ) -> Result<Vec<CachedQueryVariant>, String> {
+ self.inner
+ .lock()
+ .await
+ .engine
+ .inspect_query_variants(&QueryInspection {
+ query,
+ operation_name,
+ path,
+ variable_filters: Vec::new(),
+ })
+ .await
+ .map_err(|error| error.to_string())
+ }
+
+ /// Enumerates and materializes cached variants of one generated query field.
pub async fn inspect_query(
&self,
query: String,
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
index 2622167b0e..5a2734eeda 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
@@ -169,6 +169,25 @@ fn query_inspection_serializes_generated_variables_and_value() {
);
}
+#[test]
+fn query_variant_inspection_serializes_only_generated_variables() {
+ let handle = spawn_handle();
+ write(&handle, None, soup_data(false), None);
+
+ let variants = block_on(handle.inspect_query_variants(
+ QUERY.to_string(),
+ Some("Soup".to_string()),
+ vec!["user".to_string(), "soup".to_string()],
+ ))
+ .unwrap();
+ assert_eq!(variants.len(), 1);
+ assert_eq!(variants[0].variables, variables());
+ assert_eq!(
+ serde_json::to_value(&variants).unwrap(),
+ serde_json::json!([{"variables": {"input": {"limit": 1}}}])
+ );
+}
+
#[test]
fn registered_op_is_affected_by_later_writes() {
let handle = spawn_handle();
diff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rs
index 9bb622cd69..16bc5ed851 100644
--- a/apps/web/tauri/src-tauri/src/lib.rs
+++ b/apps/web/tauri/src-tauri/src/lib.rs
@@ -247,6 +247,7 @@ pub fn run() {
graphql_cache_plugin::commands::graphql_cache_read_records,
graphql_cache_plugin::commands::graphql_cache_write,
graphql_cache_plugin::commands::graphql_cache_begin_optimistic_write,
+ graphql_cache_plugin::commands::graphql_cache_inspect_query_variants,
graphql_cache_plugin::commands::graphql_cache_inspect_query,
graphql_cache_plugin::commands::graphql_cache_claim_next_mutation,
graphql_cache_plugin::commands::graphql_cache_defer_optimistic_write,
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index 6e52851e79..668a8a2ac4 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -13,8 +13,9 @@ use crate::link_patch::{
};
use crate::normalize::{NormalizeError, RecordUpdates, normalize};
use crate::query_inspection::{
- CachedQueryInstance, OwnerResolution, QueryInspection, QueryInspectionError,
- matches_variable_filters, prepare, recover_variants, resolve_owner, selected_result_value,
+ CachedQueryInstance, CachedQueryVariant, OwnerResolution, QueryInspection,
+ QueryInspectionError, matches_variable_filters, prepare, recover_variants, resolve_owner,
+ selected_result_value,
};
use crate::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,
@@ -1091,15 +1092,14 @@ impl<S: Storage> Engine<S> {
Ok(out)
}
- /// Enumerates cached argument variants of one generated query field.
+ /// Recovers cached argument variants of one generated query field.
///
- /// Normalized owners, canonical field keys, cold records, and optimistic
- /// layers remain internal. Every recovered variable set is read through
- /// the ordinary denormalizer so inspection has cache-only read semantics.
- pub async fn inspect_query(
+ /// Only records needed to resolve the selected field's normalized owner
+ /// are loaded. The recovered variants are not denormalized.
+ pub async fn inspect_query_variants(
&mut self,
inspection: &QueryInspection,
- ) -> Result<Vec<CachedQueryInstance>, EngineError<S::Error>> {
+ ) -> Result<Vec<CachedQueryVariant>, EngineError<S::Error>> {
self.hydrate_optimistic().await?;
let operation = Self::document(&mut self.docs, &inspection.query)?
.operation(inspection.operation_name.as_deref())?
@@ -1120,9 +1120,25 @@ impl<S: Storage> Engine<S> {
OwnerResolution::NeedRecord(_) => return Ok(Vec::new()),
}
};
- let variables = recover_variants(&owner, &prepared)?;
- let mut instances = Vec::with_capacity(variables.len());
- for variables in variables {
+ Ok(recover_variants(&owner, &prepared)?
+ .into_iter()
+ .map(|variables| CachedQueryVariant { variables })
+ .collect())
+ }
+
+ /// Enumerates and materializes cached argument variants of one generated
+ /// query field.
+ ///
+ /// Normalized owners, canonical field keys, cold records, and optimistic
+ /// layers remain internal. Every recovered variable set is read through
+ /// the ordinary denormalizer so inspection has cache-only read semantics.
+ pub async fn inspect_query(
+ &mut self,
+ inspection: &QueryInspection,
+ ) -> Result<Vec<CachedQueryInstance>, EngineError<S::Error>> {
+ let variants = self.inspect_query_variants(inspection).await?;
+ let mut instances = Vec::with_capacity(variants.len());
+ for CachedQueryVariant { variables } in variants {
if !matches_variable_filters(&variables, &inspection.variable_filters) {
continue;
}
diff --git a/crates/client/cache-core/src/query_inspection.rs b/crates/client/cache-core/src/query_inspection.rs
index d43c16c322..5ac93f9936 100644
--- a/crates/client/cache-core/src/query_inspection.rs
+++ b/crates/client/cache-core/src/query_inspection.rs
@@ -39,6 +39,14 @@ pub struct QueryInspection {
/// One cached argument variant reconstructed as generated query variables.
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
+pub struct CachedQueryVariant {
+ /// Variables recovered from the selected field's normalized arguments.
+ pub variables: serde_json::Map<String, Json>,
+}
+
+/// One materialized cached argument variant.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
pub struct CachedQueryInstance {
/// Variables recovered from the selected field's normalized arguments.
pub variables: serde_json::Map<String, Json>,
diff --git a/crates/client/cache-core/tests/query_inspection.rs b/crates/client/cache-core/tests/query_inspection.rs
index c74b09a04d..75674feab5 100644
--- a/crates/client/cache-core/tests/query_inspection.rs
+++ b/crates/client/cache-core/tests/query_inspection.rs
@@ -5,8 +5,12 @@ use cache_core::link_patch::{
LinkOperation, LinkPathSegment, ListItemByScalar, OptimisticLinkPatch,
};
use cache_core::query_inspection::{MAX_INSPECTED_VARIANTS, QueryInspection, QueryInspectionError};
-use cache_core::store::InMemoryStorage;
-use cache_core::value::EntityKey;
+use cache_core::queue::{
+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,
+ QueuedMutation,
+};
+use cache_core::store::{InMemoryStorage, Storage};
+use cache_core::value::{EntityKey, Record};
use pollster::block_on;
use serde_json::{Value as Json, json};
@@ -78,6 +82,132 @@ async fn write_group(
.unwrap();
}
+#[derive(Clone, Debug)]
+struct OwnerOnlyStorage(InMemoryStorage);
+
+impl Storage for OwnerOnlyStorage {
+ type Error = std::convert::Infallible;
+
+ async fn get_batch(&self, keys: &[EntityKey]) -> Result<Vec<Option<Record>>, Self::Error> {
+ assert!(
+ keys.iter()
+ .all(|key| key.is_root() || key.0 == "GraphqlUser:user-1"),
+ "variables-only inspection loaded a non-owner record: {keys:?}"
+ );
+ self.0.get_batch(keys).await
+ }
+
+ async fn put_batch(&mut self, entries: Vec<(EntityKey, Record)>) -> Result<(), Self::Error> {
+ self.0.put_batch(entries).await
+ }
+
+ async fn delete_batch(&mut self, keys: &[EntityKey]) -> Result<(), Self::Error> {
+ self.0.delete_batch(keys).await
+ }
+
+ async fn scan_records(
+ &self,
+ type_names: &[String],
+ after: Option<&EntityKey>,
+ limit: usize,
+ ) -> Result<Vec<(EntityKey, Record)>, Self::Error> {
+ self.0.scan_records(type_names, after, limit).await
+ }
+
+ async fn enqueue_mutation(
+ &mut self,
+ entry: NewQueuedMutation,
+ ) -> Result<MutationId, Self::Error> {
+ self.0.enqueue_mutation(entry).await
+ }
+
+ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {
+ self.0.load_mutation_queue().await
+ }
+
+ async fn claim_next_mutation(
+ &mut self,
+ request: MutationClaimRequest,
+ ) -> Result<Option<ClaimedMutation>, Self::Error> {
+ self.0.claim_next_mutation(request).await
+ }
+
+ async fn defer_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ next_attempt_at_ms: i64,
+ error: String,
+ ) -> Result<bool, Self::Error> {
+ self.0
+ .defer_mutation(id, claim, next_attempt_at_ms, error)
+ .await
+ }
+
+ async fn complete_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ entries: Vec<(EntityKey, Record)>,
+ ) -> Result<bool, Self::Error> {
+ self.0.complete_mutation(id, claim, entries).await
+ }
+
+ async fn discard_mutation(
+ &mut self,
+ id: MutationId,
+ claim: MutationClaimToken,
+ ) -> Result<bool, Self::Error> {
+ self.0.discard_mutation(id, claim).await
+ }
+
+ async fn clear(&mut self) -> Result<(), Self::Error> {
+ self.0.clear().await
+ }
+}
+
+#[test]
+fn variants_only_recovers_pages_without_loading_items() {
+ block_on(async {
+ let mut writer = Engine::new(InMemoryStorage::new());
+ let initial_variables = initial(20);
+ let continuation_variables = continuation("cursor-1");
+ write_group(
+ &mut writer,
+ GROUP_QUERY,
+ &initial_variables,
+ &page("task-1", None),
+ )
+ .await;
+ write_group(
+ &mut writer,
+ GROUP_QUERY,
+ &continuation_variables,
+ &page("task-2", Some("cursor-2")),
+ )
+ .await;
+
+ let storage = OwnerOnlyStorage(writer.storage().clone());
+ let mut reopened = Engine::new(storage);
+ let variants = reopened
+ .inspect_query_variants(&inspection(GROUP_QUERY, &["user", "groupSoup"]))
+ .await
+ .unwrap();
+
+ assert_eq!(variants.len(), 2);
+ assert!(
+ variants
+ .iter()
+ .any(|variant| variant.variables == initial_variables)
+ );
+ assert!(
+ variants
+ .iter()
+ .any(|variant| variant.variables == continuation_variables)
+ );
+ });
+}
+
#[test]
fn enumerates_variants_aliases_and_misses_in_canonical_order() {
block_on(async {
diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.toml
index 82e501bfb2..6a652eda70 100644
--- a/crates/client/cache-wasm/Cargo.toml
+++ b/crates/client/cache-wasm/Cargo.toml
@@ -2,7 +2,7 @@
edition = "2024"
name = "cache-wasm"
publish = false
-version = "0.3.1"
+version = "0.3.2"
[lib]
crate-type = ["cdylib", "rlib"]
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index 333f3de8fe..4b42b32cf9 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -207,6 +207,22 @@ fn parse_vec<T: serde::de::DeserializeOwned>(value: JsValue) -> Result<Vec<T>, J
serde_wasm_bindgen::from_value(value).map_err(err_js)
}
+fn parse_query_inspection(
+ query: String,
+ operation_name: Option<String>,
+ path: JsValue,
+ variable_filters: Vec<serde_json::Map<String, serde_json::Value>>,
+) -> Result<QueryInspection, JsValue> {
+ let path: Vec<JsInspectionPathSegment> =
+ serde_wasm_bindgen::from_value(path).map_err(err_js)?;
+ Ok(QueryInspection {
+ query,
+ operation_name,
+ path: path.into_iter().map(|segment| segment.field).collect(),
+ variable_filters,
+ })
+}
+
#[wasm_bindgen]
impl CacheEngine {
/// Returns the opaque identity bound to this cache, or `null` when no
@@ -369,7 +385,28 @@ impl CacheEngine {
})
}
- /// Enumerates cached variants of one generated query field.
+ /// Recovers cached query variables without materializing each variant.
+ #[wasm_bindgen(js_name = inspectQueryVariants)]
+ pub fn inspect_query_variants(
+ &self,
+ query: String,
+ operation_name: Option<String>,
+ path: JsValue,
+ ) -> js_sys::Promise {
+ let engine = self.engine.clone();
+ future_to_promise(async move {
+ let inspection = parse_query_inspection(query, operation_name, path, Vec::new())?;
+ let variants = engine
+ .lock()
+ .await
+ .inspect_query_variants(&inspection)
+ .await
+ .map_err(err_js)?;
+ to_js(&variants)
+ })
+ }
+
+ /// Enumerates and materializes cached variants of one generated query field.
#[wasm_bindgen(js_name = inspectQuery)]
pub fn inspect_query(
&self,
@@ -380,16 +417,8 @@ impl CacheEngine {
) -> js_sys::Promise {
let engine = self.engine.clone();
future_to_promise(async move {
- let path: Vec<JsInspectionPathSegment> =
- serde_wasm_bindgen::from_value(path).map_err(err_js)?;
- let variable_filters: Vec<serde_json::Map<String, serde_json::Value>> =
- serde_wasm_bindgen::from_value(variable_filters).map_err(err_js)?;
- let inspection = QueryInspection {
- query,
- operation_name,
- path: path.into_iter().map(|segment| segment.field).collect(),
- variable_filters,
- };
+ let variable_filters = parse_vec(variable_filters)?;
+ let inspection = parse_query_inspection(query, operation_name, path, variable_filters)?;
let instances = engine
.lock()
.await
diff --git a/crates/client/cache-wasm/tests/web.rs b/crates/client/cache-wasm/tests/web.rs
index e909e82410..b474cd3fd0 100644
--- a/crates/client/cache-wasm/tests/web.rs
+++ b/crates/client/cache-wasm/tests/web.rs
@@ -91,8 +91,20 @@ async fn write_then_read_through_js_boundary() {
assert_eq!(read["kind"], "hit");
assert_eq!(read["data"], data);
- // Generated-query inspection crosses the wasm boundary with one wire
- // shape and recovers the operation variables from the normalized field.
+ // Variables-only inspection crosses the wasm boundary without
+ // materializing the selected value.
+ let variants = JsFuture::from(engine.inspect_query_variants(
+ QUERY.into(),
+ Some("Soup".into()),
+ js(serde_json::json!([{"field": "user"}, {"field": "soup"}])),
+ ))
+ .await
+ .unwrap();
+ let variants: serde_json::Value = serde_wasm_bindgen::from_value(variants).unwrap();
+ assert_eq!(variants[0]["variables"], vars);
+ assert!(variants[0].get("value").is_none());
+
+ // Full generated-query inspection also materializes the selected value.
let inspected = JsFuture::from(engine.inspect_query(
QUERY.into(),
Some("Soup".into()),
diff --git a/nix-support/node_modules-hashes.json b/nix-support/node_modules-hashes.json
index 4cdaf1ab2a..e9e1101d80 100644
--- a/nix-support/node_modules-hashes.json
+++ b/nix-support/node_modules-hashes.json
@@ -1,6 +1,6 @@
{
"nodeModules": {
- "aarch64-darwin": "sha256-9faTf5jCfZqQ6iZQJZ+l6uMtiZxGdBwA7LLvJiI1RTU=",
- "x86_64-linux": "sha256-nIFUdH7qp4wf8a/IObVpLWZSKP/n2RSJ64cOPfDzG3s="
+ "aarch64-darwin": "sha256-gq79YeOfdlBbZJ0/WdoVtqpQq54SJFxtFaSQnkbgJls=",
+ "x86_64-linux": "sha256-XEgtdhzfBGs24hD/30mFUDcwvWZe8q1vlOYyyfIQ3Y4="
}
}