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 {
SaveEmailDraftDocument,
SetEmailThreadArchivedDocument,
SoupDocument,
UpdateNotificationsDocument,
} from '@service-storage/graphql/generated/graphql';
import {
markGraphqlEmailThreadSeen,
markGraphqlEmailThreadUnread,
} from '@service-storage/graphql-email-read-state';
import { executeGraphqlSetFavoriteMutation } from '@service-storage/graphql-favorites';
import { shouldRetryGraphqlMutation } from '@service-storage/graphql-mutation-retry';
import {
type Client,
CombinedError,
createClient,
createRequest,
fetchExchange,
gql,
makeOperation,
type Operation,
type OperationResult,
stringifyDocument,
} from '@urql/core';
import { createComputed, createRoot } from 'solid-js';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import {
makeSubject,
map,
mergeMap,
pipe,
type Source,
subscribe,
} from 'wonka';
import { soupOptimisticResolvers } from '../../queries/optimistic-resolvers';
import { resolveCrmExternalWriteTypes } from '../../queries/soup/graphql/external-write-scope';
import { createUrqlQuery } from '../../urql-solid/create-urql-query';
import { CacheNavigationError } from '../host/navigation-error';
import { createRetirableCacheHost } from '../host/retirable-host';
import type {
AffectedOperationsListener,
CacheGenerationChange,
CacheHost,
} from '../host/types';
import {
ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
type ClaimedMutation,
type CommitOptimisticWriteResult,
type EnqueueOptimisticMutationResult,
INITIAL_CACHE_REVISION,
type MutationClaim,
type MutationSettlement,
OWNER_LOCK_UNAVAILABLE_ERROR_CODE,
parseCacheRevision,
type QueryUpdate,
type ReadResult,
type WriteResult,
} from '../protocol';
import { entityFromArgument } from './entity-resolvers';
import { recordExternalWrite } from './external-writes';
import { liveQueryData } from './live-query';
import { NOOP_MUTATION_QUEUE_TELEMETRY } from './mutation-queue-telemetry';
import {
HYDRATE_ONLY_CONTEXT_KEY,
type NormalizedCacheExchangeOptions,
normalizedCacheExchange,
normalizedCacheResultMetadata,
} from './normalized-cache-exchange';
import {
executeOptimisticMutation,
optimisticContextOf,
optimisticMutationDispositionOf,
} from './optimistic';
import { optimisticResolversExchange } from './optimistic-resolvers';
const QUERY = gql`
query Soup($input: SoupInput!) {
soup(input: $input) {
nextCursor
}
}
`;
const HYDRATION_QUERY = gql`
query SoupHydration($input: SoupInput!) {
soup(input: $input) {
items @cacheOnly {
id
}
nextCursor
}
}
`;
const ENTITY_RESOLVER_OPTIONS: NormalizedCacheExchangeOptions = {
entityResolvers: {
GraphqlUser: {
emailThread: entityFromArgument('GraphqlSoupEmailThread', [
'input',
'threadId',
]),
},
},
};
const EXPECTED_ENTITY_RESOLVERS = [
{
parentType: 'GraphqlUser',
fieldName: 'emailThread',
targetType: 'GraphqlSoupEmailThread',
argumentPath: ['input', 'threadId'],
},
];
const SUBSCRIPTION = gql`
subscription SoupUpdates {
soupUpdates {
__typename
... on SoupUpdated {
item {
__typename
id
displayName
}
}
... on GraphqlCacheDeletion {
graphqlTypeName
entityId
}
}
}
`;
const MUTATION = gql`
mutation SetEntityProperty($input: SetEntityPropertyInput!) {
setEntityProperty(input: $input) {
id
}
}
`;
const RENAME_MUTATION = gql`
mutation RenameEntities($inputs: [RenameEntityInput!]!) {
renameEntities(inputs: $inputs) {
results {
__typename
... on GraphqlMutationSuccess {
effects {
__typename
... on SoupUpdated {
item {
__typename
id
displayName
}
}
... on GraphqlCacheDeletion {
graphqlTypeName
entityId
}
}
}
... on GraphqlMutationError {
errorCode
message
}
}
}
}
`;
const ALIASED_RENAME_MUTATION = gql`
mutation RenameEntities($inputs: [RenameEntityInput!]!) {
renamed: renameEntities(inputs: $inputs) {
__typename
outcomes: results {
__typename
... on GraphqlMutationSuccess {
patches: effects {
__typename
... on SoupUpdated {
current: item {
__typename
id
displayName
}
}
... on GraphqlCacheDeletion {
graphqlTypeName
entityId
}
}
}
}
}
}
`;
type FakeHost = CacheHost & {
reads: Array<{
opKey?: number;
query: string;
variables?: object;
priority?: 'user-visible';
entityResolvers?: readonly unknown[];
}>;
writes: Array<{
opKey?: number;
data: unknown;
identity?: string;
registerDependencies?: boolean;
entityResolvers?: readonly unknown[];
}>;
begins: Array<{
query: string;
data: unknown;
linkPatches?: unknown[];
}>;
commits: Array<{ transactionId: string; query: string; data: unknown }>;
rollbacks: string[];
defers: Array<{ transactionId: string; error: string }>;
claims: string[];
invalidations: string[][];
cacheActions: Array<{ kind: 'write' | 'delete'; value: unknown }>;
teardowns: number[];
scriptRead: (result: ReadResult) => void;
seedQueued: (
args: Parameters<CacheHost['enqueueOptimisticMutation']>[0],
serverFailureCount?: number
) => void;
pushAffected: AffectedOperationsListener;
pushGeneration: (change: CacheGenerationChange) => void;
resetStorage: () => void;
};
function makeFakeHost(): FakeHost {
let nextTransaction = 0;
let readResult: ReadResult = { kind: 'miss' };
const subscribers = new Set<AffectedOperationsListener>();
const generationSubscribers = new Set<
(change: CacheGenerationChange) => void
>();
const queue: Array<{
transactionId: string;
args: Parameters<CacheHost['enqueueOptimisticMutation']>[0];
attemptCount: number;
serverFailureCount: number;
leased: boolean;
leaseExpiresAtMs?: number;
nextAttemptAtMs?: number;
}> = [];
function claimQueueHead(
nowMs: number,
leaseExpiresAtMs: number
): ClaimedMutation | undefined {
const head = queue[0];
if (
!head ||
(head.leased && (head.leaseExpiresAtMs ?? Infinity) > nowMs) ||
(head.nextAttemptAtMs !== undefined && head.nextAttemptAtMs > nowMs)
) {
return undefined;
}
head.leased = true;
head.leaseExpiresAtMs = leaseExpiresAtMs;
head.nextAttemptAtMs = undefined;
head.attemptCount += 1;
host.claims.push(head.transactionId);
return {
transactionId: head.transactionId,
uuid: head.args.uuid,
clientMetadata: head.args.clientMetadata,
superseded: false,
requiresConfirmation: false,
leaseGeneration: String(head.attemptCount),
query: head.args.query,
operationName: head.args.operationName,
variables: head.args.variables ?? {},
attemptCount: head.attemptCount,
serverFailureCount: head.serverFailureCount,
};
}
const host: FakeHost = {
clientId: 'test-client',
resetStorage() {
queue.length = 0;
nextTransaction = 0;
readResult = { kind: 'miss' };
host.pushGeneration({ storage: 'reset' });
},
reads: [],
writes: [],
begins: [],
commits: [],
rollbacks: [],
defers: [],
claims: [],
invalidations: [],
cacheActions: [],
teardowns: [],
scriptRead: (r) => {
readResult = r;
},
seedQueued: (args, serverFailureCount = 0) => {
queue.push({
transactionId: String(++nextTransaction),
args,
attemptCount: 0,
serverFailureCount,
leased: false,
});
},
pushAffected: (opKeys, changes) => {
for (const cb of subscribers) cb(opKeys, changes);
},
pushGeneration: (change) => {
for (const cb of generationSubscribers) cb(change);
},
async currentRevision() {
return INITIAL_CACHE_REVISION;
},
async currentStorageGeneration() {
return '00000000-0000-4000-8000-000000000001';
},
async readQuery(args) {
host.reads.push({
opKey: args.opKey,
query: args.query,
variables: args.variables,
priority: args.priority,
entityResolvers: args.entityResolvers,
});
return readResult;
},
async readRecordsByKeys() {
return { revision: INITIAL_CACHE_REVISION, records: [] };
},
async search() {
return { documents: [], nextCursor: null };
},
async entityFilter() {
return { kind: 'unsupported' };
},
async calendarRange() {
return { kind: 'unsupported' };
},
async calendarCommit() {
return { kind: 'unsupported' };
},
async writeQuery(args): Promise<WriteResult> {
host.writes.push({
opKey: args.opKey,
data: args.data,
identity: args.identity,
registerDependencies: args.registerDependencies,
entityResolvers: args.entityResolvers,
});
host.cacheActions.push({ kind: 'write', value: args.data });
return {
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
};
},
async hydrateQuery(args) {
host.writes.push({ data: args.data, identity: args.identity });
host.cacheActions.push({ kind: 'write', value: args.data });
return {
kind: 'data',
data: args.data,
revision: INITIAL_CACHE_REVISION,
};
},
async enqueueOptimisticMutation(
args,
claim
): Promise<EnqueueOptimisticMutationResult> {
host.begins.push({
query: args.query,
data: args.data,
linkPatches: args.linkPatches,
});
const transactionId = String(++nextTransaction);
queue.push({
transactionId,
args,
attemptCount: 0,
serverFailureCount: 0,
leased: false,
});
const mutation = claimQueueHead(claim.nowMs, claim.leaseExpiresAtMs);
return {
transactionId,
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
upsertKind: { kind: 'inserted' },
initialClaim: mutation
? { kind: 'claimed', mutation }
: { kind: 'not-runnable' },
};
},
async inspectQueryVariants() {
return [];
},
async inspectQuery() {
return [];
},
async claimNextMutation(
_owner,
nowMs,
leaseExpiresAtMs
): Promise<ClaimedMutation | undefined> {
return claimQueueHead(nowMs, leaseExpiresAtMs);
},
async deferOptimisticWrite(
transactionId,
_claim: MutationClaim,
nextAttemptAtMs,
error,
serverFailure = false
) {
host.defers.push({ transactionId, error });
const head = queue[0];
if (head?.transactionId === transactionId) {
head.leased = false;
head.nextAttemptAtMs = nextAttemptAtMs;
if (serverFailure) head.serverFailureCount += 1;
}
return { kind: 'deferred' };
},
async commitOptimisticWrite(
transactionId,
_claim,
args
): Promise<CommitOptimisticWriteResult> {
host.commits.push({ transactionId, query: args.query, data: args.data });
const revalidations = queue[0]?.args.revalidations;
if (queue[0]?.transactionId === transactionId) queue.shift();
return {
kind: 'committed',
revalidations,
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
};
},
async rollbackOptimisticWrite(transactionId, _claim) {
host.rollbacks.push(transactionId);
const revalidations = queue[0]?.args.revalidations;
if (queue[0]?.transactionId === transactionId) queue.shift();
return {
kind: 'rolled-back' as const,
revalidations,
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
};
},
async invalidate() {
return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
},
async deleteRecords(keys) {
host.invalidations.push(keys);
host.cacheActions.push({ kind: 'delete', value: keys });
return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
},
async teardown(opKey) {
host.teardowns.push(opKey);
},
async clear() {
return INITIAL_CACHE_REVISION;
},
onOpsAffected(cb) {
subscribers.add(cb);
return () => subscribers.delete(cb);
},
onCacheChanged() {
return () => undefined;
},
onCacheGenerationChanged(cb) {
generationSubscribers.add(cb);
return () => generationSubscribers.delete(cb);
},
onMutationSettled() {
return () => undefined;
},
dispose() {},
};
return host;
}
function makeOp(
key: number,
requestPolicy:
| 'cache-first'
| 'cache-and-network'
| 'network-only'
| 'cache-only' = 'cache-first'
): Operation {
return makeOperation(
'query',
{ key, query: QUERY, variables: { input: { limit: 2 } } },
{ requestPolicy, url: 'http://test', suspense: false } as never
);
}
function makeHydrationOp(key: number): Operation {
return makeOperation(
'query',
{
key,
query: HYDRATION_QUERY,
variables: { input: { limit: 2 } },
},
{
requestPolicy: 'network-only',
url: 'http://test',
suspense: false,
[HYDRATE_ONLY_CONTEXT_KEY]: true,
} as never
);
}
function makeSubscriptionOp(key: number): Operation {
return makeOperation(
'subscription',
{ key, query: SUBSCRIPTION, variables: {} },
{
requestPolicy: 'cache-first',
url: 'http://test',
suspense: false,
} as never
);
}
function teardownOf(op: Operation): Operation {
return makeOperation('teardown', op, op.context);
}
/**
* Builds a mutation operation, optionally carrying the optimistic response
* in the private context slot `executeOptimisticMutation` uses.
*/
function makeMutationOp(key: number, optimisticResponse?: unknown): Operation {
return makeOperation(
'mutation',
{ key, query: MUTATION, variables: { input: {} } },
{
requestPolicy: 'cache-first',
url: 'http://test',
suspense: false,
...(optimisticResponse === undefined
? {}
: {
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse,
},
}),
} as never
);
}
function makeRenameMutationOp(key: number, aliased = false): Operation {
return makeOperation(
'mutation',
{
key,
query: aliased ? ALIASED_RENAME_MUTATION : RENAME_MUTATION,
variables: {
inputs: [
{
entity: { type: 'DOCUMENT', id: 'document-1' },
displayName: 'Renamed',
},
],
},
},
{
requestPolicy: 'cache-first',
url: 'http://test',
suspense: false,
} as never
);
}
/** Runs the exchange over a manual operation stream. */
function harness(
host: CacheHost,
resultFor?: (op: Operation) => Partial<OperationResult>,
options: NormalizedCacheExchangeOptions = {}
) {
const ops = makeSubject<Operation>();
const client = {
reexecuteOperation: vi.fn(),
query: vi.fn((_query, _variables, _context) => ({
toPromise: () => Promise.resolve({ data: {} }),
})),
createRequestOperation: vi.fn((kind, request, context) =>
makeOperation(kind, request, context)
),
executeRequestOperation: vi.fn((_operation) => ({
toPromise: () => Promise.resolve({ data: {} }),
})),
mutation: vi.fn((query, variables, context) => ({
toPromise: () => {
const request = createRequest(query, variables);
ops.next(
makeOperation('mutation', request, {
requestPolicy: 'network-only',
url: 'http://test',
suspense: false,
...context,
} as never)
);
return Promise.resolve({ error: undefined });
},
})),
} as unknown as Client;
const forwarded: Operation[] = [];
const forward = (ops$: Source<Operation>): Source<OperationResult> =>
pipe(
ops$,
map((op) => {
forwarded.push(op);
return {
operation: op,
data:
op.kind === 'query' || op.kind === 'mutation'
? { from: 'network' }
: undefined,
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
...resultFor?.(op),
};
})
);
const results: OperationResult[] = [];
const exchangeIo = normalizedCacheExchange(
host,
options
)({
forward,
client,
dispatchDebug: () => undefined,
});
pipe(
exchangeIo(ops.source),
subscribe((r) => results.push(r))
);
return { ops, results, forwarded, client };
}
function controlledQueryHarness(
host: CacheHost,
options: NormalizedCacheExchangeOptions = {}
) {
const ops = makeSubject<Operation>();
const network = makeSubject<OperationResult>();
const forwarded: Operation[] = [];
const results: OperationResult[] = [];
const client = {
reexecuteOperation: vi.fn((operation: Operation) => ops.next(operation)),
} as unknown as Client;
const forward = (ops$: Source<Operation>): Source<OperationResult> => {
pipe(
ops$,
subscribe((operation) => forwarded.push(operation))
);
return network.source;
};
pipe(
normalizedCacheExchange(
host,
options
)({
forward,
client,
dispatchDebug: () => undefined,
})(ops.source),
subscribe((result) => results.push(result))
);
return { ops, network, forwarded, results, client };
}
const tick = () => new Promise((resolve) => setTimeout(resolve, 10));
function deferred<T>() {
let resolve!: (value: T) => void;
let reject!: (error: Error) => void;
const promise = new Promise<T>((res, rej) => {
resolve = res;
reject = rej;
});
return { promise, resolve, reject };
}
function queryResult(
operation: Operation,
data: unknown = { from: 'network' }
): OperationResult {
return {
operation,
data,
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
};
}
describe('normalizedCacheExchange', () => {
let host: FakeHost;
beforeEach(() => {
host = makeFakeHost();
});
it.each(['constructor', 'prototype', '__proto__'])(
'updates the %s alias through the Solid query adapter without mutating snapshots',
async (alias) => {
const query = gql(
`query Reserved { ${alias}: name nested { ${alias}: name } }`
);
const original = { [alias]: 'old', nested: { [alias]: 'old' } };
host.scriptRead({ kind: 'hit', data: original });
const client = createClient({
url: '/graphql',
exchanges: [normalizedCacheExchange(host)],
});
const { state, dispose } = createRoot((dispose) => ({
state: createUrqlQuery(() => ({
client,
query,
variables: {},
requestPolicy: 'cache-only' as const,
})),
dispose,
}));
try {
await vi.waitFor(() => expect(state.isSuccess).toBe(true));
expect(JSON.parse(JSON.stringify(state.data))).toEqual(original);
for (const data of [
{ [alias]: 'new', nested: { [alias]: 'new' } },
{ name: 'ordinary', nested: { name: 'ordinary' } },
{ [alias]: 'returned', nested: { [alias]: 'returned' } },
]) {
host.scriptRead({ kind: 'hit', data });
host.pushAffected([host.reads[0].opKey!]);
await vi.waitFor(() =>
expect(JSON.parse(JSON.stringify(state.data))).toEqual(data)
);
}
expect(original).toEqual({
[alias]: 'old',
nested: { [alias]: 'old' },
});
} finally {
dispose();
}
}
);
it('keeps mounted live data when a refresh of the same query fails with partial data', async () => {
type Page = {
user: { soup: { items: { __typename: string; id: string }[] } | null };
};
const soup = gql<Page>`query Soup { user { soup { items { __typename id } } } }`;
const responses: Pick<OperationResult, 'data' | 'error'>[] = [
{ data: { user: { soup: { items: [{ __typename: 'Doc', id: '1' }] } } } },
{
data: { user: { soup: null } },
error: new CombinedError({
graphQLErrors: [
{ message: 'pool timed out while waiting for an open connection' },
],
}),
},
];
const client = createClient({
url: '/graphql',
exchanges: [
normalizedCacheExchange(host),
() => (source) =>
pipe(
source,
map((operation) => ({
operation,
stale: false,
hasNext: false,
...responses.shift(),
}))
),
],
});
const { mounted, dispose } = createRoot((dispose) => ({
mounted: createUrqlQuery(() => ({
client,
query: soup,
variables: {},
requestPolicy: 'network-only' as const,
})),
dispose,
}));
try {
await vi.waitFor(() => expect(mounted.isSuccess).toBe(true));
const page = mounted.data!;
const refresh = await client
.query(soup, {}, { requestPolicy: 'network-only' })
.toPromise();
expect(refresh.error?.message).toContain('pool timed out');
expect(page.user.soup?.items.map((item) => item.id)).toEqual(['1']);
} finally {
dispose();
}
});
it('keeps the mounted live view through a refresh that fails without data', async () => {
type Page = { rows: { __typename: string; id: string }[] };
const rows = gql<Page>`query Rows { rows { __typename id } }`;
const responses: Pick<OperationResult, 'data' | 'error'>[] = [
{ data: { rows: [{ __typename: 'Thread', id: '1' }] } },
{
data: undefined,
error: new CombinedError({ networkError: new Error('offline') }),
},
{ data: { rows: [{ __typename: 'Thread', id: '2' }] } },
];
const client = createClient({
url: '/graphql',
exchanges: [
normalizedCacheExchange(host),
() => (source) =>
pipe(
source,
map((operation) => ({
operation,
stale: false,
hasNext: false,
...responses.shift(),
}))
),
],
});
const { mounted, dispose } = createRoot((dispose) => ({
mounted: createUrqlQuery(() => ({
client,
query: rows,
variables: {},
requestPolicy: 'network-only' as const,
})),
dispose,
}));
try {
await vi.waitFor(() => expect(mounted.isSuccess).toBe(true));
const page = mounted.data!;
const refresh = () =>
client.query(rows, {}, { requestPolicy: 'network-only' }).toPromise();
expect((await refresh()).error?.networkError?.message).toBe('offline');
expect(page.rows.map((row) => row.id)).toEqual(['1']);
await refresh();
expect(page.rows.map((row) => row.id)).toEqual(['2']);
} finally {
dispose();
}
});
it('applies a cache hit that carries an earlier network failure', async () => {
type Page = { rows: { __typename: string; id: string }[] };
const rows = gql<Page>`query Rows { rows { __typename id } }`;
const failure = () => ({
data: { rows: [] },
error: new CombinedError({
graphQLErrors: [{ message: 'database unavailable' }],
}),
});
host.scriptRead({
kind: 'hit',
data: { rows: [{ __typename: 'Thread', id: '1' }] },
});
const client = createClient({
url: '/graphql',
exchanges: [
normalizedCacheExchange(host),
() => (source) =>
pipe(
source,
map((operation) => ({
operation,
stale: false,
hasNext: false,
...failure(),
}))
),
],
});
const { mounted, dispose } = createRoot((dispose) => ({
mounted: createUrqlQuery(() => ({
client,
query: rows,
variables: {},
requestPolicy: 'cache-and-network' as const,
})),
dispose,
}));
try {
await vi.waitFor(() => expect(mounted.error).toBeTruthy());
expect(mounted.data?.rows.map((row) => row.id)).toEqual(['1']);
host.scriptRead({
kind: 'hit',
data: { rows: [{ __typename: 'Thread', id: '2' }] },
});
await client
.query(rows, {}, { requestPolicy: 'cache-and-network' })
.toPromise();
await vi.waitFor(() =>
expect(mounted.data?.rows.map((row) => row.id)).toEqual(['2'])
);
} finally {
dispose();
}
});
it('keeps live objects reactive through full reads on older cache hosts', async () => {
type Rows = { rows: { __typename: string; id: string; isRead: boolean }[] };
const first = gql<Rows>`query First { rows { __typename id isRead } }`;
const second = gql<Rows>`query Second { rows { __typename id isRead } }`;
const snapshot = {
rows: [{ __typename: 'Thread', id: '17', isRead: false }],
};
host.scriptRead({ kind: 'hit', data: snapshot });
const network = vi.fn();
const client = createClient({
url: '/graphql',
exchanges: [
normalizedCacheExchange(host),
() => (source) =>
pipe(
source,
map((operation) => {
network();
return { operation, data: {}, stale: false, hasNext: false };
})
),
],
});
const observed: boolean[] = [];
const { a, b, selected, dispose } = createRoot((dispose) => {
const a = createUrqlQuery(() => ({
client,
query: first,
variables: {},
requestPolicy: 'cache-only' as const,
}));
const b = createUrqlQuery(() => ({
client,
query: second,
variables: {},
requestPolicy: 'cache-only' as const,
}));
const selected = createUrqlQuery(() => ({
client,
query: first,
variables: {},
requestPolicy: 'cache-only' as const,
select: (data: Rows) =>
data.rows.filter((row) => !row.isRead).map((row) => row.id),
}));
createComputed(() => {
if (a.isSuccess) observed.push(a.data!.rows[0].isRead);
});
return { a, b, selected, dispose };
});
try {
await vi.waitFor(() =>
expect(a.isSuccess && b.isSuccess && selected.isSuccess).toBe(true)
);
const row = a.data!.rows[0];
const reads = host.reads.length;
const keys = host.reads.flatMap((read) =>
read.opKey === undefined ? [] : [read.opKey]
);
host.scriptRead({
kind: 'hit',
data: { rows: [{ __typename: 'Thread', id: '17', isRead: true }] },
});
host.pushAffected(keys, [
{ kind: 'fields', key: 'Thread:17', fields: { isRead: true } },
]);
await vi.waitFor(() => expect(b.data!.rows[0].isRead).toBe(true));
expect(a.data!.rows[0]).toBe(row);
expect(b.data!.rows[0].isRead).toBe(true);
expect(selected.data).toEqual([]);
expect(snapshot.rows[0].isRead).toBe(false);
host.scriptRead({ kind: 'hit', data: snapshot });
host.pushAffected(keys, [
{ kind: 'fields', key: 'Thread:17', fields: { isRead: false } },
]);
await vi.waitFor(() => expect(selected.data).toEqual(['17']));
expect(observed).toEqual([false, true, false]);
await tick();
expect(host.reads.length).toBeGreaterThan(reads);
expect(network).not.toHaveBeenCalled();
// A scalar push arriving before a structural reread must not cancel it.
host.scriptRead({
kind: 'hit',
data: {
rows: [
{ __typename: 'Thread', id: '17', isRead: true },
{ __typename: 'Thread', id: '18', isRead: false },
],
},
});
host.pushAffected(keys, [{ kind: 'invalidate', key: 'Thread:17' }]);
host.pushAffected(keys, [
{ kind: 'fields', key: 'Thread:17', fields: { isRead: true } },
]);
await vi.waitFor(() => expect(a.data?.rows).toHaveLength(2));
expect(selected.data).toEqual(['18']);
expect(host.reads.length).toBeGreaterThan(reads);
} finally {
dispose();
}
});
it('publishes a network result it was asked not to persist without writing it', async () => {
const { ops, results } = harness(host, () => ({
data: { user: { emailThread: null } },
}));
const op = makeOp(902, 'network-only');
ops.next(
makeOperation('query', op, { ...op.context, persistResult: false })
);
await tick();
expect(host.cacheActions).toEqual([]);
expect(results.at(-1)?.data).toEqual({ user: { emailThread: null } });
});
it('evicts inferred missing records after writing the network response', async () => {
const deletedRecordKeys = vi.fn(() => ['GraphqlSoupEmailThread:gone']);
const { ops, results } = harness(
host,
() => ({ data: { user: { emailThread: null } } }),
{ deletedRecordKeys }
);
ops.next(makeOp(901, 'network-only'));
await tick();
expect(host.cacheActions.map((action) => action.kind)).toEqual([
'write',
'delete',
]);
expect(host.invalidations).toEqual([['GraphqlSoupEmailThread:gone']]);
expect(results.at(-1)?.data).toEqual({ user: { emailThread: null } });
});
it('does not infer deletions from GraphQL errors with partial data', async () => {
const deletedRecordKeys = vi.fn(() => ['GraphqlSoupEmailThread:keep']);
const { ops } = harness(
host,
() => ({
data: { user: { emailThread: null } },
error: new CombinedError({
graphQLErrors: [{ message: 'database unavailable' }],
}),
}),
{ deletedRecordKeys }
);
ops.next(makeOp(902, 'network-only'));
await tick();
expect(deletedRecordKeys).not.toHaveBeenCalled();
expect(host.invalidations).toEqual([]);
expect(host.writes).toEqual([]);
});
it('normalizes ordinary buffered subscription data without inspecting event types', async () => {
const patches = ['document-1', 'document-2'].map((id) => ({
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id,
displayName: `Updated ${id}`,
},
}));
const data = { soupUpdates: patches };
const { ops, results } = harness(host, (op) =>
op.kind === 'subscription' ? { data } : {}
);
ops.next(makeSubscriptionOp(21));
await tick();
expect(host.writes).toHaveLength(1);
expect(host.writes[0]?.data).toBe(data);
expect(results).toHaveLength(1);
expect(results[0]?.data).toBe(data);
expect(normalizedCacheResultMetadata(results[0]!)).toEqual({
source: 'live-network',
cacheEffectsApplied: true,
});
});
it('deletes the exact normalized key from subscription patches', async () => {
const data = {
soupUpdates: [
{
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'document-1',
},
],
};
const { ops, results } = harness(host, (op) =>
op.kind === 'subscription' ? { data } : {}
);
ops.next(makeSubscriptionOp(22));
await tick();
expect(host.invalidations).toEqual([['GraphqlSoupDocument:document-1']]);
expect(host.writes).toHaveLength(0);
expect(results[0]?.data).toBe(data);
});
it('applies buffered mixed patches in order', async () => {
const deleteDocument = (id: string) => ({
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: id,
});
const updateDocument = (id: string) => ({
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id,
displayName: `Document ${id}`,
},
});
const patches = [
deleteDocument('delete-then-update'),
updateDocument('delete-then-update'),
updateDocument('update-then-delete'),
deleteDocument('update-then-delete'),
];
const { ops } = harness(host, (op) =>
op.kind === 'subscription' ? { data: { soupUpdates: patches } } : {}
);
ops.next(makeSubscriptionOp(23));
await tick();
expect(host.cacheActions).toEqual([
{
kind: 'delete',
value: ['GraphqlSoupDocument:delete-then-update'],
},
{
kind: 'write',
value: { soupUpdates: [patches[1]] },
},
{
kind: 'write',
value: { soupUpdates: [patches[2]] },
},
{
kind: 'delete',
value: ['GraphqlSoupDocument:update-then-delete'],
},
]);
});
it('serializes cache effects across separate subscription emissions', async () => {
const operation = makeSubscriptionOp(24);
const networkResults = makeSubject<OperationResult>();
let cacheContainsDocument = false;
let markWriteStarted!: () => void;
let releaseWrite!: () => void;
const writeStarted = new Promise<void>((resolve) => {
markWriteStarted = resolve;
});
const writeCanFinish = new Promise<void>((resolve) => {
releaseWrite = resolve;
});
vi.spyOn(host, 'writeQuery').mockImplementation(async () => {
markWriteStarted();
await writeCanFinish;
cacheContainsDocument = true;
return {
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
};
});
vi.spyOn(host, 'deleteRecords').mockImplementation(async () => {
cacheContainsDocument = false;
return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };
});
const ops = makeSubject<Operation>();
const results: OperationResult[] = [];
const exchangeIo = normalizedCacheExchange(host)({
forward: (ops$) =>
pipe(
ops$,
mergeMap(() => networkResults.source)
),
client: {
reexecuteOperation: vi.fn(),
mutation: vi.fn(),
} as never,
dispatchDebug: () => undefined,
});
pipe(
exchangeIo(ops.source),
subscribe((result) => results.push(result))
);
ops.next(operation);
networkResults.next({
operation,
data: {
soupUpdates: [
{
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id: 'document-1',
displayName: 'Updated document',
},
},
],
},
stale: false,
hasNext: true,
});
await writeStarted;
networkResults.next({
operation,
data: {
soupUpdates: [
{
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'document-1',
},
],
},
stale: false,
hasNext: true,
});
await tick();
expect(host.deleteRecords).not.toHaveBeenCalled();
releaseWrite();
await vi.waitFor(() => expect(results).toHaveLength(2));
expect(host.deleteRecords).toHaveBeenCalledWith([
'GraphqlSoupDocument:document-1',
]);
expect(cacheContainsDocument).toBe(false);
});
it('cancels queued subscription effects on teardown even when the same key resubscribes', async () => {
const firstWrite = deferred<WriteResult>();
const write = vi
.spyOn(host, 'writeQuery')
.mockImplementationOnce(() => firstWrite.promise);
const remove = vi.spyOn(host, 'deleteRecords');
const { ops, network } = controlledQueryHarness(host);
const operation = makeSubscriptionOp(24);
ops.next(operation);
network.next(
queryResult(operation, {
soupUpdates: [
{
__typename: 'SoupUpdated',
item: { __typename: 'GraphqlSoupDocument', id: 'one' },
},
{
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'one',
},
],
})
);
network.next(
queryResult(operation, {
soupUpdates: [{ id: 'queued-before-navigation' }],
})
);
await vi.waitFor(() => expect(write).toHaveBeenCalledOnce());
ops.next(makeOperation('teardown', operation, operation.context));
ops.next(operation);
const fresh = { soupUpdates: [{ id: 'after-restore' }] };
network.next(queryResult(operation, fresh));
firstWrite.resolve({
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
});
await vi.waitFor(() => expect(write).toHaveBeenCalledTimes(2));
expect(write.mock.calls[1]?.[0].data).toBe(fresh);
expect(remove).not.toHaveBeenCalled();
});
it('reports cache failures without dropping subscription results or later patches', async () => {
const error = new Error('subscription cache write failed');
vi.spyOn(host, 'writeQuery').mockRejectedValueOnce(error);
const onCacheError = vi.fn();
const patches = [
{
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id: 'document-1',
displayName: 'Updated document',
},
},
{
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'document-2',
},
];
const data = { soupUpdates: patches };
const { ops, results } = harness(
host,
(op) => (op.kind === 'subscription' ? { data } : {}),
{ onCacheError }
);
const operation = makeSubscriptionOp(24);
ops.next(operation);
await tick();
expect(onCacheError).toHaveBeenCalledWith(error, operation);
expect(host.invalidations).toEqual([['GraphqlSoupDocument:document-2']]);
expect(results).toHaveLength(1);
expect(results[0]?.data).toBe(data);
expect(normalizedCacheResultMetadata(results[0]!)).toEqual({
source: 'live-network',
cacheEffectsApplied: false,
});
});
it('cache-first miss forwards to network and writes through', async () => {
const { ops, results, forwarded } = harness(host);
ops.next(makeOp(1));
await tick();
expect(host.reads).toHaveLength(1);
expect(host.reads[0]?.opKey).toBe(1);
expect(forwarded.map((op) => op.key)).toEqual([1]);
expect(results).toHaveLength(1);
expect(results[0]?.data).toEqual({ from: 'network' });
expect(host.writes).toHaveLength(1);
expect(host.writes[0]).toEqual(
expect.objectContaining({
data: { from: 'network' },
registerDependencies: true,
})
);
});
it('compiles entity resolvers once and forwards them to reads and registered writes', async () => {
const options = {
entityResolvers: ENTITY_RESOLVER_OPTIONS.entityResolvers,
} satisfies NormalizedCacheExchangeOptions;
const { ops, forwarded } = harness(host, undefined, options);
// Mutating the outer options after exchange construction cannot change
// the already-compiled read policy.
(options as NormalizedCacheExchangeOptions).entityResolvers = undefined;
ops.next(makeOp(1));
await tick();
expect(host.reads).toHaveLength(1);
expect(forwarded.map((operation) => operation.key)).toEqual([1]);
expect(host.reads[0]?.entityResolvers).toEqual(EXPECTED_ENTITY_RESOLVERS);
expect(host.writes[0]).toEqual(
expect.objectContaining({
registerDependencies: true,
entityResolvers: EXPECTED_ENTITY_RESOLVERS,
})
);
});
it('cache-first resolver hit emits without reaching the network', async () => {
host.scriptRead({ kind: 'hit', data: { from: 'cache' } });
const { ops, results, forwarded } = harness(
host,
undefined,
ENTITY_RESOLVER_OPTIONS
);
ops.next(makeOp(1));
await tick();
expect(host.reads[0]?.entityResolvers).toEqual(EXPECTED_ENTITY_RESOLVERS);
expect(results[0]?.data).toEqual({ from: 'cache' });
expect(forwarded).toHaveLength(0);
});
it('rejects malformed resolver options during exchange construction', () => {
expect(() =>
normalizedCacheExchange(host, {
entityResolvers: {
GraphqlUser: {
emailThread: {
kind: 'entity-from-argument',
targetType: 'GraphqlSoupEmailThread',
argumentPath: ['input', 'bad'],
},
},
} as never,
})
).toThrow('does not have ID argument path');
});
it('cache-first hit emits without network', async () => {
host.scriptRead({ kind: 'hit', data: { from: 'cache' } });
const { ops, results, forwarded } = harness(host);
ops.next(makeOp(1));
await tick();
expect(results).toHaveLength(1);
expect(results[0]?.data).toEqual({ from: 'cache' });
expect(results[0]?.stale).toBe(false);
expect(forwarded).toHaveLength(0);
expect(host.writes).toHaveLength(0);
});
it('cache-and-network starts the network before a blocked cache read settles', async () => {
const read = deferred<ReadResult>();
const originalRead = host.readQuery;
host.readQuery = async (args) => {
await originalRead(args);
return await read.promise;
};
const { ops, network, results, forwarded } = controlledQueryHarness(host);
ops.next(makeOp(1, 'cache-and-network'));
await tick();
expect(forwarded.map((op) => op.key)).toEqual([1]);
expect(results).toHaveLength(0);
read.resolve({ kind: 'hit', data: { from: 'cache' } });
await tick();
expect(results.map((result) => [result.data, result.stale])).toEqual([
[{ from: 'cache' }, true],
]);
network.next(queryResult(forwarded[0]!));
await tick();
expect(results.map((r) => [r.data, r.stale])).toEqual([
[{ from: 'cache' }, true],
[{ from: 'network' }, false],
]);
expect(results.map(normalizedCacheResultMetadata)).toEqual([
{ source: 'normalized-cache-hit' },
{ source: 'live-network', persistence: expect.any(Promise) },
]);
const metadata = normalizedCacheResultMetadata(results[1]!);
expect(metadata?.source).toBe('live-network');
if (metadata?.source === 'live-network') {
await expect(metadata.persistence).resolves.toBe(INITIAL_CACHE_REVISION);
}
expect(forwarded.map((op) => op.key)).toEqual([1]);
expect(host.writes).toHaveLength(1);
expect(host.reads).toHaveLength(1);
});
it('publishes network data before persistence and acknowledges without replaying it', async () => {
const read = deferred<ReadResult>();
const write = deferred<WriteResult>();
host.readQuery = vi.fn(() => read.promise);
host.writeQuery = vi.fn(() => write.promise);
const { ops, results, forwarded } = harness(host);
ops.next(makeOp(1, 'cache-and-network'));
await tick();
expect(forwarded).toHaveLength(1);
expect(host.writeQuery).toHaveBeenCalledOnce();
expect(results.map((result) => [result.data, result.stale])).toEqual([
[{ from: 'network' }, false],
]);
const metadata = normalizedCacheResultMetadata(results[0]!);
expect(metadata).toEqual({
source: 'live-network',
persistence: expect.any(Promise),
});
read.resolve({ kind: 'hit', data: { from: 'cache' } });
await tick();
expect(results).toHaveLength(1);
write.resolve({
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
});
await tick();
if (metadata?.source === 'live-network') {
await expect(metadata.persistence).resolves.toBe(INITIAL_CACHE_REVISION);
}
expect(results).toHaveLength(1);
});
it.each([false, true])(
'publishes later network data without waiting for an earlier write (streaming=%s)',
async (streaming) => {
const firstWrite = deferred<void>();
const originalWrite = host.writeQuery;
host.writeQuery = vi
.fn()
.mockImplementationOnce(async (args) => {
await firstWrite.promise;
return await originalWrite(args);
})
.mockImplementation(originalWrite);
const { ops, network, forwarded, results } = controlledQueryHarness(host);
ops.next(makeOp(1, 'network-only'));
network.next({
...queryResult(forwarded[0]!, { version: 'A' }),
hasNext: streaming,
});
await tick();
if (!streaming) ops.next(makeOp(1, 'network-only'));
network.next(queryResult(forwarded.at(-1)!, { version: 'B' }));
await tick();
expect(results.map((result) => result.data)).toEqual([
{ version: 'A' },
{ version: 'B' },
]);
expect(results.map((result) => result.hasNext)).toEqual([
streaming,
false,
]);
expect(host.writeQuery).toHaveBeenCalledOnce();
firstWrite.resolve();
await tick();
expect(host.writes.map((write) => write.data)).toEqual([
{ version: 'A' },
{ version: 'B' },
]);
expect(results).toHaveLength(2);
}
);
it('does not let a persistence acknowledgement overwrite a newer optimistic result', async () => {
const write = deferred<void>();
const originalWrite = host.writeQuery;
host.writeQuery = async (args) => {
await write.promise;
return await originalWrite(args);
};
const { ops, results, forwarded } = harness(host);
ops.next(makeOp(1, 'network-only'));
await tick();
expect(results).toHaveLength(1);
host.scriptRead({ kind: 'hit', data: { from: 'optimistic layer' } });
host.pushAffected([1]);
await tick();
expect(results.at(-1)?.data).toEqual({ from: 'optimistic layer' });
expect(results.at(-1)?.stale).toBe(false);
write.resolve();
await tick();
expect(results.map((result) => result.data)).toEqual([
{ from: 'network' },
{ from: 'optimistic layer' },
]);
expect(forwarded).toHaveLength(1);
});
it('keeps successful network data when background persistence fails', async () => {
const write = deferred<WriteResult>();
host.writeQuery = vi.fn(() => write.promise);
const onCacheError = vi.fn();
const { ops, results } = harness(host, undefined, { onCacheError });
ops.next(makeOp(1, 'network-only'));
await tick();
expect(results[0]?.data).toEqual({ from: 'network' });
const metadata = normalizedCacheResultMetadata(results[0]!);
write.reject(new Error('disk full'));
await tick();
expect(onCacheError).toHaveBeenCalledOnce();
expect(results).toHaveLength(1);
expect(results[0]?.error).toBeUndefined();
expect(metadata?.source).toBe('live-network');
if (metadata?.source === 'live-network') {
await expect(metadata.persistence).resolves.toBeUndefined();
}
});
it('keeps the persistence acknowledgement when the global Promise is patched', async () => {
const { ops, results } = harness(host);
ops.next(makeOp(1, 'network-only'));
await tick();
class PatchedPromise<T> extends Promise<T> {}
vi.stubGlobal('Promise', PatchedPromise);
let metadata: ReturnType<typeof normalizedCacheResultMetadata>;
try {
metadata = normalizedCacheResultMetadata(results[0]!);
} finally {
vi.unstubAllGlobals();
}
expect(metadata?.source).toBe('live-network');
if (metadata?.source !== 'live-network') return;
expect(metadata.persistence).toBeDefined();
await expect(metadata.persistence).resolves.toBe(INITIAL_CACHE_REVISION);
});
it('settles persistence even when its diagnostic callback throws', async () => {
host.writeQuery = vi.fn().mockRejectedValue(new Error('disk full'));
const { ops, results } = harness(host, undefined, {
onCacheError: () => {
throw new Error('diagnostic failed');
},
});
ops.next(makeOp(1, 'network-only'));
await tick();
const metadata = normalizedCacheResultMetadata(results[0]!);
expect(metadata?.source).toBe('live-network');
if (metadata?.source === 'live-network') {
await expect(metadata.persistence).resolves.toBeUndefined();
}
ops.next(makeOp(1, 'network-only'));
await tick();
expect(host.writeQuery).toHaveBeenCalledTimes(2);
expect(results).toHaveLength(2);
});
it('publishes a network error while an earlier response is still being persisted', async () => {
const write = deferred<void>();
const originalWrite = host.writeQuery;
host.writeQuery = async (args) => {
await write.promise;
return await originalWrite(args);
};
const { ops, network, forwarded, results } = controlledQueryHarness(host);
ops.next(makeOp(1, 'network-only'));
network.next(queryResult(forwarded[0]!, { version: 'A' }));
await tick();
ops.next(makeOp(1, 'network-only'));
const error = new CombinedError({ networkError: new Error('offline') });
network.next({ ...queryResult(forwarded[1]!), data: undefined, error });
await tick();
expect(results).toHaveLength(2);
expect(results[1]?.error).toBe(error);
write.resolve();
await tick();
expect(results).toHaveLength(2);
expect(host.writes).toHaveLength(1);
});
it('preserves background write order without registering a torn-down query after remount', async () => {
const firstWrite = deferred<void>();
const originalWrite = host.writeQuery;
host.writeQuery = vi
.fn()
.mockImplementationOnce(async (args) => {
await firstWrite.promise;
return await originalWrite(args);
})
.mockImplementation(originalWrite);
const { ops, network, forwarded, results, client } =
controlledQueryHarness(host);
const first = makeOp(1, 'network-only');
ops.next(first);
network.next(queryResult(first, { version: 'A' }));
await tick();
ops.next(makeOp(1, 'network-only'));
network.next(queryResult(forwarded.at(-1)!, { version: 'B' }));
await tick();
ops.next(teardownOf(first));
ops.next(makeOp(1, 'network-only'));
network.next(queryResult(forwarded.at(-1)!, { version: 'C' }));
await tick();
expect(results.map((result) => result.data)).toEqual([
{ version: 'A' },
{ version: 'B' },
{ version: 'C' },
]);
expect(host.writeQuery).toHaveBeenCalledOnce();
firstWrite.resolve();
await tick();
expect(
host.writes.map((write) => [write.data, write.registerDependencies])
).toEqual([
[{ version: 'A' }, true],
[{ version: 'B' }, false],
[{ version: 'C' }, true],
]);
expect(results).toHaveLength(3);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
});
it('still waits for hydrate-only projection instead of exposing cache-only fields', async () => {
const hydration =
deferred<Awaited<ReturnType<CacheHost['hydrateQuery']>>>();
host.hydrateQuery = vi.fn(() => hydration.promise);
const { ops, results } = harness(host);
ops.next(makeHydrationOp(1));
await tick();
expect(results).toHaveLength(0);
hydration.resolve({ kind: 'void', revision: INITIAL_CACHE_REVISION });
await tick();
expect(results).toHaveLength(1);
expect(results[0]?.data).toBeUndefined();
});
it.each(['hit', 'miss', 'error'] as const)(
'ignores a late cache %s after a cache-and-network response',
async (outcome) => {
const read = deferred<ReadResult>();
host.readQuery = vi.fn(() => read.promise);
const onCacheError = vi.fn();
const { ops, results, forwarded } = harness(host, undefined, {
onCacheError,
});
ops.next(makeOp(1, 'cache-and-network'));
await tick();
expect(forwarded).toHaveLength(1);
expect(results.map((result) => result.data)).toEqual([
{ from: 'network' },
]);
if (outcome === 'error') read.reject(new Error('late cache failure'));
else if (outcome === 'miss') read.resolve({ kind: 'miss' });
else read.resolve({ kind: 'hit', data: { from: 'old cache' } });
await tick();
expect(forwarded).toHaveLength(1);
expect(results).toHaveLength(1);
expect(host.writes).toHaveLength(1);
expect(onCacheError).toHaveBeenCalledTimes(outcome === 'error' ? 1 : 0);
}
);
it('does not report a cache read cancelled by teardown', async () => {
const read = deferred<ReadResult>();
host.readQuery = vi.fn(() => read.promise);
const onCacheError = vi.fn();
const { ops, results } = harness(host, undefined, { onCacheError });
const op = makeOp(1);
ops.next(op);
await tick();
ops.next(teardownOf(op));
read.resolve({ kind: 'hit', data: { from: 'cache' } });
await tick();
expect(onCacheError).not.toHaveBeenCalled();
expect(results.filter((r) => r.operation.kind === 'query')).toEqual([]);
});
it('does not report a watched reread cancelled by teardown', async () => {
const reread = deferred<QueryUpdate>();
host.watchQuery = vi
.fn()
.mockResolvedValueOnce({
kind: 'hit',
revision: parseCacheRevision('1'),
data: { from: 'cache' },
})
.mockReturnValueOnce(reread.promise);
const onCacheError = vi.fn();
const { ops, results } = harness(host, undefined, { onCacheError });
const op = makeOp(1);
ops.next(op);
await tick();
expect(results.map((result) => result.data)).toEqual([{ from: 'cache' }]);
host.pushAffected([1]);
await tick();
expect(host.watchQuery).toHaveBeenCalledTimes(2);
ops.next(teardownOf(op));
reread.resolve({
kind: 'hit',
revision: parseCacheRevision('2'),
data: { from: 'newer cache' },
});
await tick();
expect(onCacheError).not.toHaveBeenCalled();
expect(
results
.filter((r) => r.operation.kind === 'query')
.map((result) => result.data)
).toEqual([{ from: 'cache' }]);
});
it.each(['miss', 'error'] as const)(
'does not forward twice when a concurrent cache read returns %s first',
async (outcome) => {
const read = deferred<ReadResult>();
host.readQuery = vi.fn(() => read.promise);
const { ops, network, forwarded, results } = controlledQueryHarness(host);
ops.next(makeOp(1, 'cache-and-network'));
expect(forwarded).toHaveLength(1);
if (outcome === 'error') read.reject(new Error('cache unavailable'));
else read.resolve({ kind: 'miss' });
await tick();
expect(forwarded).toHaveLength(1);
network.next(queryResult(forwarded[0]!));
await tick();
expect(results).toHaveLength(1);
}
);
it('still forwards cache-and-network when readQuery throws synchronously', async () => {
host.readQuery = vi.fn(() => {
throw new Error('cache unavailable');
});
const { ops, forwarded, results } = harness(host);
ops.next(makeOp(1, 'cache-and-network'));
await tick();
expect(forwarded).toHaveLength(1);
expect(results[0]?.data).toEqual({ from: 'network' });
});
it('shows a late offline cache hit without erasing the network error', async () => {
const read = deferred<ReadResult>();
host.readQuery = vi.fn(() => read.promise);
const error = new CombinedError({ networkError: new Error('offline') });
const { ops, results, forwarded } = harness(host, () => ({
data: undefined,
error,
}));
ops.next(makeOp(1, 'cache-and-network'));
await tick();
read.resolve({ kind: 'hit', data: { from: 'old cache' } });
await tick();
expect(results).toHaveLength(2);
expect(results[0]?.error).toBe(error);
expect(results[1]?.data).toEqual({ from: 'old cache' });
expect(results[1]?.error).toBe(error);
expect(results[1]?.stale).toBe(false);
expect(forwarded).toHaveLength(1);
});
it.each(['hit', 'miss', 'error'] as const)(
'fences a pending cache %s across teardown and remount of the same key',
async (outcome) => {
const read = deferred<ReadResult>();
host.readQuery = vi
.fn()
.mockImplementationOnce(() => read.promise)
.mockResolvedValue({ kind: 'hit', data: { from: 'remount' } });
const { ops, forwarded, results } = controlledQueryHarness(host);
const first = makeOp(1, 'cache-and-network');
ops.next(first);
ops.next(teardownOf(first));
ops.next(makeOp(1, 'cache-only'));
await tick();
if (outcome === 'error') read.reject(new Error('old read failed'));
else if (outcome === 'miss') read.resolve({ kind: 'miss' });
else read.resolve({ kind: 'hit', data: { from: 'unmounted query' } });
await tick();
expect(results.map((result) => result.data)).toEqual([
{ from: 'remount' },
]);
expect(forwarded.map((op) => op.kind)).toEqual(['query', 'teardown']);
}
);
it('does not let an initial cache read overwrite a newer optimistic reread', async () => {
const initialRead = deferred<ReadResult>();
host.readQuery = vi
.fn()
.mockImplementationOnce(() => initialRead.promise)
.mockResolvedValue({ kind: 'hit', data: { status: 'Completed' } });
const { ops, results, forwarded } = controlledQueryHarness(host);
ops.next(makeOp(1, 'cache-and-network'));
host.pushAffected([1]);
await tick();
initialRead.resolve({ kind: 'hit', data: { status: 'In Review' } });
await tick();
expect(results.map((result) => result.data)).toEqual([
{ status: 'Completed' },
]);
expect(normalizedCacheResultMetadata(results[0]!)).toEqual({
source: 'affected-cache-reread',
});
expect(forwarded).toHaveLength(1);
});
it.each([false, true])(
'never restores stale message membership after a newer network result (persisted: %s)',
async (persisted) => {
vi.useFakeTimers();
try {
const cached = { messages: ['first'], isRead: true };
const fresh = { messages: ['first', 'second'], isRead: true };
const affectedRead = deferred<ReadResult>();
const write = deferred<WriteResult>();
host.readQuery = vi
.fn()
.mockResolvedValueOnce({ kind: 'hit', data: cached })
.mockImplementationOnce(() => affectedRead.promise)
.mockResolvedValue({ kind: 'hit', data: fresh });
host.writeQuery = vi.fn(() => write.promise);
const { ops, results, forwarded, network } =
controlledQueryHarness(host);
ops.next(makeOp(1, 'cache-and-network'));
await vi.advanceTimersByTimeAsync(0);
host.pushAffected([1]);
await vi.advanceTimersByTimeAsync(0);
network.next(queryResult(forwarded[0]!, fresh));
await vi.advanceTimersByTimeAsync(0);
expect(results.map((result) => result.data)).toEqual([cached, fresh]);
const acknowledgeWrite = () =>
write.resolve({
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
});
if (persisted) {
acknowledgeWrite();
await vi.advanceTimersByTimeAsync(0);
}
affectedRead.resolve({ kind: 'hit', data: cached });
await vi.advanceTimersByTimeAsync(0);
if (!persisted) acknowledgeWrite();
await vi.advanceTimersByTimeAsync(0);
expect(results.map((result) => result.data)).toEqual([cached, fresh]);
expect(forwarded).toHaveLength(1);
} finally {
vi.useRealTimers();
}
}
);
it.each(['watch', 'fallback'])(
'reconciles pending edits with fresh message membership after discarding an older %s read',
async (reader) => {
vi.useFakeTimers();
try {
const cached = { messages: ['first'], isRead: false };
const fresh = { messages: ['first', 'second'], isRead: false };
const reconciled = { ...fresh, isRead: true };
const lateSnapshot = {
kind: 'hit' as const,
data: { ...cached, isRead: true },
revision: parseCacheRevision('2'),
};
const affectedRead = deferred<typeof lateSnapshot>();
const write = deferred<WriteResult>();
const read = vi
.fn()
.mockResolvedValueOnce({
kind: 'hit',
data: cached,
revision: parseCacheRevision('1'),
})
.mockImplementationOnce(() => affectedRead.promise)
.mockResolvedValue({
kind: 'hit',
data: reconciled,
revision: parseCacheRevision('3'),
});
host.watchQuery =
reader === 'watch'
? read
: vi.fn(async () => ({ kind: 'unsupported' as const }));
host.readQuery = read;
host.writeQuery = vi.fn(() => write.promise);
const { ops, results, forwarded, network } =
controlledQueryHarness(host);
ops.next(makeOp(1, 'cache-and-network'));
await vi.advanceTimersByTimeAsync(0);
host.pushAffected([1]);
await vi.advanceTimersByTimeAsync(0);
network.next(queryResult(forwarded[0]!, fresh));
await vi.advanceTimersByTimeAsync(0);
const live = liveQueryData(results.at(-1)!);
affectedRead.resolve(lateSnapshot);
await vi.advanceTimersByTimeAsync(0);
expect(live).toEqual(fresh);
write.resolve({
revision: parseCacheRevision('3'),
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
});
await vi.advanceTimersByTimeAsync(0);
expect(live).toEqual(reconciled);
expect(results.map((result) => result.data)).toEqual([cached, fresh]);
expect(forwarded).toHaveLength(1);
} finally {
vi.useRealTimers();
}
}
);
it('preserves optimistic rereads that finish after network persistence', async () => {
const write = deferred<WriteResult>();
const affectedRead = deferred<ReadResult>();
const originalWrite = host.writeQuery;
host.writeQuery = vi.fn(async (args) => {
await originalWrite(args);
return await write.promise;
});
host.readQuery = vi
.fn()
.mockResolvedValueOnce({ kind: 'miss' })
.mockImplementationOnce(() => affectedRead.promise);
const { ops, results, forwarded } = harness(host);
ops.next(makeOp(1, 'cache-and-network'));
await tick();
host.pushAffected([1]);
write.resolve({
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
});
await tick();
affectedRead.resolve({ kind: 'hit', data: { from: 'optimistic layer' } });
await tick();
expect(results.map((result) => result.data)).toEqual([
{ from: 'network' },
{ from: 'optimistic layer' },
]);
expect(forwarded).toHaveLength(1);
});
it('discards an affected reread across teardown and remount', async () => {
const affectedRead = deferred<ReadResult>();
host.readQuery = vi
.fn()
.mockResolvedValueOnce({ kind: 'miss' })
.mockImplementationOnce(() => affectedRead.promise)
.mockResolvedValueOnce({ kind: 'hit', data: { from: 'remount' } });
const { ops, results, forwarded } = controlledQueryHarness(host);
const first = makeOp(1, 'cache-and-network');
ops.next(first);
await tick();
host.pushAffected([1]);
ops.next(teardownOf(first));
ops.next(makeOp(1, 'cache-only'));
await tick();
affectedRead.resolve({
kind: 'hit',
data: { from: 'old optimistic layer' },
});
await tick();
expect(results.map((result) => result.data)).toEqual([{ from: 'remount' }]);
expect(forwarded.map((op) => op.kind)).toEqual(['query', 'teardown']);
});
it('network-only registers dependencies without reading the cache', async () => {
const { ops, results } = harness(host, undefined, ENTITY_RESOLVER_OPTIONS);
ops.next(makeOp(1, 'network-only'));
await tick();
expect(host.reads).toHaveLength(0);
expect(results[0]?.data).toEqual({ from: 'network' });
expect(host.writes).toHaveLength(1);
expect(host.writes[0]).toEqual(
expect.objectContaining({
opKey: 1,
registerDependencies: true,
entityResolvers: EXPECTED_ENTITY_RESOLVERS,
})
);
});
it('hydrate-only stores the full response and emits only the cache projection', async () => {
host.hydrateQuery = vi.fn(async (args) => {
expect(args.query).toContain('@cacheOnly');
expect(args.data).toEqual({
soup: { items: [{ id: 'doc-1' }], nextCursor: 'cursor-2' },
});
return {
kind: 'data' as const,
data: { soup: { nextCursor: 'cursor-2' } },
revision: INITIAL_CACHE_REVISION,
};
});
const { ops, network, forwarded, results } = controlledQueryHarness(host);
ops.next(makeHydrationOp(7));
await tick();
expect(host.reads).toHaveLength(0);
expect(stringifyDocument(forwarded[0]!.query)).not.toContain('@cacheOnly');
network.next({
operation: forwarded[0]!,
data: {
soup: { items: [{ id: 'doc-1' }], nextCursor: 'cursor-2' },
},
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await tick();
expect(host.hydrateQuery).toHaveBeenCalledOnce();
expect(host.reads).toHaveLength(0);
expect(results[0]?.data).toEqual({
soup: { nextCursor: 'cursor-2' },
});
expect(normalizedCacheResultMetadata(results[0]!)).toEqual({
source: 'live-network',
revision: INITIAL_CACHE_REVISION,
});
});
it('cache-only miss emits empty data and never touches the network', async () => {
const { ops, results, forwarded } = harness(
host,
undefined,
ENTITY_RESOLVER_OPTIONS
);
ops.next(makeOp(1, 'cache-only'));
await tick();
expect(results).toHaveLength(1);
expect(results[0]?.data).toBeUndefined();
expect(forwarded).toHaveLength(0);
expect(host.reads[0]?.entityResolvers).toEqual(EXPECTED_ENTITY_RESOLVERS);
});
it('cache read errors degrade to the network', async () => {
host.readQuery = async () => {
throw new Error('idb exploded');
};
const onCacheError = vi.fn();
const client = { reexecuteOperation: vi.fn() } as unknown as Client;
const ops = makeSubject<Operation>();
const results: OperationResult[] = [];
const forward = (ops$: Source<Operation>): Source<OperationResult> =>
pipe(
ops$,
map((op) => ({
operation: op,
data: { from: 'network' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
}))
);
pipe(
normalizedCacheExchange(host, { onCacheError })({
forward,
client,
dispatchDebug: () => undefined,
})(ops.source),
subscribe((r) => results.push(r))
);
ops.next(makeOp(1));
await tick();
expect(onCacheError).toHaveBeenCalledOnce();
expect(results[0]?.data).toEqual({ from: 'network' });
});
it('cache-only never touches the network, even when the cache read throws', async () => {
host.readQuery = async () => {
throw new Error('idb exploded');
};
const onCacheError = vi.fn();
const client = { reexecuteOperation: vi.fn() } as unknown as Client;
const ops = makeSubject<Operation>();
const results: OperationResult[] = [];
const forwarded: Operation[] = [];
const forward = (ops$: Source<Operation>): Source<OperationResult> =>
pipe(
ops$,
map((op) => {
forwarded.push(op);
return {
operation: op,
data: { from: 'network' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
};
})
);
pipe(
normalizedCacheExchange(host, { onCacheError })({
forward,
client,
dispatchDebug: () => undefined,
})(ops.source),
subscribe((r) => results.push(r))
);
ops.next(makeOp(1, 'cache-only'));
await tick();
expect(onCacheError).toHaveBeenCalledOnce();
expect(forwarded).toHaveLength(0);
expect(results).toHaveLength(1);
expect(results[0]?.data).toBeUndefined();
});
it('passes the extracted identity tag on write-through', async () => {
const client = { reexecuteOperation: vi.fn() } as unknown as Client;
const ops = makeSubject<Operation>();
const forward = (ops$: Source<Operation>): Source<OperationResult> =>
pipe(
ops$,
map((op) => ({
operation: op,
data: { user: { id: 'macro|[email protected]' } },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
}))
);
pipe(
normalizedCacheExchange(host, {
extractIdentity: (data) =>
(data as { user?: { id?: string } })?.user?.id,
})({ forward, client, dispatchDebug: () => undefined })(ops.source),
subscribe(() => undefined)
);
ops.next(makeOp(1));
await tick();
expect(host.writes).toHaveLength(1);
expect(host.writes[0]?.identity).toBe('macro|[email protected]');
});
it('re-executes each affected active operation once as a prioritized cache read', async () => {
host.scriptRead({ kind: 'hit', data: { from: 'cache' } });
const { ops, client } = harness(host, undefined, ENTITY_RESOLVER_OPTIONS);
const op = makeOp(7, 'cache-and-network');
ops.next(op);
await tick();
vi.mocked(client.reexecuteOperation).mockImplementation((reissued) => {
ops.next(reissued);
});
host.pushAffected([7, 999]); // 999 is not active → ignored
await tick();
const reexec = vi.mocked(client.reexecuteOperation);
expect(reexec).toHaveBeenCalledOnce();
const reissued = reexec.mock.calls[0]?.[0] as Operation;
expect(reissued.key).toBe(7);
expect(reissued.context.requestPolicy).toBe('cache-first');
expect(host.reads).toHaveLength(2);
expect(host.reads[0]?.priority).toBeUndefined();
expect(host.reads[1]?.priority).toBe('user-visible');
expect(host.reads.map((read) => read.entityResolvers)).toEqual([
EXPECTED_ENTITY_RESOLVERS,
EXPECTED_ENTITY_RESOLVERS,
]);
});
it('emits an affected cache result while an authoritative query remains in flight', async () => {
host.scriptRead({ kind: 'hit', data: { status: 'In Review' } });
const { ops, results, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(8, 'cache-and-network'));
await tick();
expect(forwarded).toHaveLength(1);
expect(results.map((result) => [result.data, result.stale])).toEqual([
[{ status: 'In Review' }, true],
]);
host.scriptRead({ kind: 'hit', data: { status: 'Completed' } });
host.pushAffected([8]);
await tick();
expect(client.reexecuteOperation).not.toHaveBeenCalled();
expect(forwarded).toHaveLength(1);
expect(host.reads.at(-1)?.priority).toBe('user-visible');
expect(results.map((result) => [result.data, result.stale])).toEqual([
[{ status: 'In Review' }, true],
[{ status: 'Completed' }, true],
]);
expect(normalizedCacheResultMetadata(results.at(-1)!)).toEqual({
source: 'affected-cache-reread',
});
});
it.each(['read', 'write'] as const)(
'recovers owner loss reported by a concurrent %s without another API request',
async (failureSource) => {
const read = deferred<ReadResult>();
const write = deferred<WriteResult>();
host.readQuery = vi.fn(() => read.promise);
const originalWrite = host.writeQuery;
host.writeQuery = vi
.fn()
.mockImplementationOnce(() => write.promise)
.mockImplementation(originalWrite);
const { ops, forwarded, results, client } = harness(host);
ops.next(makeOp(1, 'cache-and-network'));
await tick();
expect(host.writeQuery).toHaveBeenCalledOnce();
const ownerLost = Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
if (failureSource === 'read') {
read.reject(ownerLost);
await tick();
write.reject(new Error('replacement not ready'));
} else {
write.reject(ownerLost);
}
await tick();
host.pushAffected([1]);
await tick();
if (failureSource === 'write') {
read.reject(ownerLost);
await tick();
}
expect(host.writeQuery).toHaveBeenCalledTimes(2);
expect(host.writeQuery).toHaveBeenLastCalledWith(
expect.objectContaining({
opKey: 1,
data: { from: 'network' },
registerDependencies: true,
})
);
expect(host.readQuery).toHaveBeenCalledOnce();
expect(forwarded).toHaveLength(1);
expect(results).toHaveLength(1);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
}
);
it('registers a slow fallback write without a replacement reread', async () => {
let readCount = 0;
host.readQuery = async (args) => {
host.reads.push({ opKey: args.opKey, query: args.query });
readCount += 1;
if (readCount === 1) {
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
}
return { kind: 'miss' };
};
const { ops, network, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(41));
await tick();
expect(forwarded).toHaveLength(1);
host.pushAffected([41]);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
network.next({
operation: forwarded[0]!,
data: { from: 'slow-network' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await tick();
expect(forwarded).toHaveLength(1);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
expect(host.writes).toHaveLength(1);
expect(host.writes[0]?.registerDependencies).toBe(true);
expect(host.reads).toHaveLength(1);
});
it('restores a fast successful fallback after replacement without another API request', async () => {
let readCount = 0;
let cached: unknown;
host.readQuery = async (args) => {
host.reads.push({
opKey: args.opKey,
query: args.query,
variables: args.variables,
priority: args.priority,
entityResolvers: args.entityResolvers,
});
readCount += 1;
if (readCount === 1) {
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
}
return cached === undefined
? { kind: 'miss' }
: { kind: 'hit', data: cached };
};
host.writeQuery = vi
.fn()
.mockRejectedValueOnce(new Error('replacement init not ready'))
.mockImplementationOnce(async (args) => {
cached = args.data;
return {
revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
};
});
const { ops, network, forwarded, results, client } = controlledQueryHarness(
host,
ENTITY_RESOLVER_OPTIONS
);
ops.next(makeOp(42));
await tick();
network.next({
operation: forwarded[0]!,
data: { from: 'fast-network' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await tick();
expect(host.writeQuery).toHaveBeenCalledOnce();
host.pushAffected([42]);
await tick();
expect(host.writeQuery).toHaveBeenCalledTimes(2);
expect(host.writeQuery).toHaveBeenLastCalledWith(
expect.objectContaining({
opKey: 42,
data: { from: 'fast-network' },
entityResolvers: EXPECTED_ENTITY_RESOLVERS,
})
);
expect(cached).toEqual({ from: 'fast-network' });
expect(host.reads).toHaveLength(1);
expect(host.writeQuery).toHaveBeenLastCalledWith(
expect.objectContaining({
opKey: 42,
variables: { input: { limit: 2 } },
entityResolvers: EXPECTED_ENTITY_RESOLVERS,
registerDependencies: true,
})
);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
expect(forwarded).toHaveLength(1);
expect(results).toHaveLength(1);
});
it('serializes a replacement notification during write and preserves payload after retry failure', async () => {
let readCount = 0;
host.readQuery = async (args) => {
host.reads.push({ opKey: args.opKey, query: args.query });
readCount += 1;
if (readCount === 1) {
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
}
return { kind: 'hit', data: { from: 'network' } };
};
let rejectInitialWrite!: (error: Error) => void;
const initialWrite = new Promise<never>((_resolve, reject) => {
rejectInitialWrite = reject;
});
host.writeQuery = vi
.fn()
.mockImplementationOnce(async () => await initialWrite)
.mockRejectedValueOnce(new Error('replacement failed while writing'))
.mockResolvedValueOnce({
revision: INITIAL_CACHE_REVISION,
changed: [],
affectedOps: [],
reset: false,
});
const { ops, network, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(43));
await tick();
network.next({
operation: forwarded[0]!,
data: { from: 'network' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledOnce());
host.pushAffected([43]);
rejectInitialWrite(new Error('old write failed'));
await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(2));
await tick();
expect(host.reads).toHaveLength(1);
host.pushAffected([43]);
await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(3));
expect(host.reads).toHaveLength(1);
expect(host.writeQuery).toHaveBeenLastCalledWith(
expect.objectContaining({ registerDependencies: true })
);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
expect(forwarded).toHaveLength(1);
});
it('invalidates retained fallback A before newer network result B writes', async () => {
let readCount = 0;
let writeCount = 0;
let cached: unknown;
host.readQuery = async (args) => {
host.reads.push({
opKey: args.opKey,
query: args.query,
variables: args.variables,
entityResolvers: args.entityResolvers,
});
readCount += 1;
if (readCount === 1) {
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
}
return { kind: 'hit', data: cached };
};
host.writeQuery = vi.fn(async (args) => {
writeCount += 1;
if (writeCount === 1) throw new Error('initial A write failed');
if (writeCount === 2) throw new Error('replacement A write failed');
cached = args.data;
return {
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: true,
changed: [],
affectedOps: [],
reset: false,
};
});
const { ops, network, forwarded, client } = controlledQueryHarness(
host,
ENTITY_RESOLVER_OPTIONS
);
const fallbackA = makeOp(46);
ops.next(fallbackA);
await tick();
network.next({
operation: forwarded[0]!,
data: { version: 'A' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await tick();
host.pushAffected([46]);
await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(2));
await tick();
const newerB = makeOp(46, 'network-only');
ops.next(newerB);
await vi.waitFor(() =>
expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(2)
);
network.next({
operation: forwarded.findLast(({ kind }) => kind === 'query')!,
data: { version: 'B' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await vi.waitFor(() => expect(host.writeQuery).toHaveBeenCalledTimes(3));
expect(host.reads).toHaveLength(1);
expect(cached).toEqual({ version: 'B' });
expect(host.writeQuery).toHaveBeenLastCalledWith(
expect.objectContaining({
entityResolvers: EXPECTED_ENTITY_RESOLVERS,
registerDependencies: true,
})
);
host.pushAffected([46]);
await tick();
expect(client.reexecuteOperation).toHaveBeenCalledOnce();
expect(host.reads).toHaveLength(2);
expect(host.writeQuery).toHaveBeenCalledTimes(3);
expect(cached).toEqual({ version: 'B' });
expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(2);
ops.next(teardownOf(newerB));
await tick();
host.pushAffected([46]);
await tick();
expect(host.writeQuery).toHaveBeenCalledTimes(3);
expect(cached).toEqual({ version: 'B' });
});
it('clears registration-only context before a later ordinary cache miss', async () => {
let readCount = 0;
host.readQuery = async (args) => {
host.reads.push({ opKey: args.opKey, query: args.query });
readCount += 1;
if (readCount === 1) {
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
}
return { kind: 'miss' };
};
const { ops, network, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(44));
await tick();
network.next({
operation: forwarded[0]!,
data: undefined,
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await tick();
host.pushAffected([44]);
await tick();
expect(client.reexecuteOperation).toHaveBeenCalledOnce();
expect(
vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0]?.context
.normalizedCacheReplacementRegistrationOnly
).toBe(true);
expect(host.reads).toHaveLength(2);
expect(forwarded).toHaveLength(1);
host.pushAffected([44]);
await tick();
expect(client.reexecuteOperation).toHaveBeenCalledTimes(2);
expect(
vi.mocked(client.reexecuteOperation).mock.calls[1]?.[0]?.context
.normalizedCacheReplacementRegistrationOnly
).toBe(false);
expect(host.reads).toHaveLength(3);
expect(forwarded).toHaveLength(2);
});
it('drops retained replacement payload on teardown', async () => {
host.readQuery = async (args) => {
host.reads.push({ opKey: args.opKey, query: args.query });
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
};
host.writeQuery = vi
.fn()
.mockRejectedValue(new Error('replacement init not ready'));
const { ops, network, forwarded, client } = controlledQueryHarness(host);
const op = makeOp(45);
ops.next(op);
await tick();
network.next({
operation: forwarded[0]!,
data: { from: 'network' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
});
await tick();
ops.next(teardownOf(op));
await tick();
host.pushAffected([45]);
await tick();
expect(host.writeQuery).toHaveBeenCalledOnce();
expect(host.reads).toHaveLength(1);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
expect(forwarded).toHaveLength(2);
expect(forwarded[1]?.kind).toBe('teardown');
});
it('reexecutes an old rejected cache-only read without forwarding the API', async () => {
let readCount = 0;
host.readQuery = async (args) => {
host.reads.push({ opKey: args.opKey, query: args.query });
readCount += 1;
if (readCount === 1) {
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
}
return { kind: 'miss' };
};
const { ops, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(44, 'cache-only'));
await tick();
host.pushAffected([44]);
await tick();
expect(client.reexecuteOperation).toHaveBeenCalledOnce();
const reissued = vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0];
expect(reissued?.context.requestPolicy).toBe('cache-only');
expect(forwarded).toHaveLength(0);
expect(host.reads).toHaveLength(2);
});
it('teardown unregisters the op with the host and stops re-execution', async () => {
const { ops, client } = harness(host);
const op = makeOp(7);
ops.next(op);
await tick();
ops.next(teardownOf(op));
await tick();
expect(host.teardowns).toEqual([7]);
host.pushAffected([7]);
expect(vi.mocked(client.reexecuteOperation)).not.toHaveBeenCalled();
});
describe('hidden-page affected rereads', () => {
let visibility: DocumentVisibilityState;
const setVisibility = (value: DocumentVisibilityState) => {
visibility = value;
document.dispatchEvent(new Event('visibilitychange'));
};
beforeEach(() => {
visibility = 'visible';
vi.spyOn(document, 'visibilityState', 'get').mockImplementation(
() => visibility
);
});
afterEach(() => {
setVisibility('visible');
vi.restoreAllMocks();
});
it('keeps previous results while hidden and catches up only mounted operations', async () => {
host.scriptRead({ kind: 'hit', data: { status: 'old' } });
const { ops, results, client } = controlledQueryHarness(host);
const first = makeOp(71);
const second = makeOp(72, 'cache-only');
ops.next(first);
ops.next(second);
await tick();
setVisibility('hidden');
host.scriptRead({ kind: 'hit', data: { status: 'latest' } });
host.pushAffected([71, 72, 999]);
host.pushAffected([71, 72]);
ops.next(teardownOf(second));
await tick();
expect(host.reads).toHaveLength(2);
expect(results.map((result) => result.data)).toEqual([
{ status: 'old' },
{ status: 'old' },
]);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
setVisibility('visible');
await tick();
expect(client.reexecuteOperation).toHaveBeenCalledOnce();
expect(host.reads).toHaveLength(3);
expect(host.reads.at(-1)).toMatchObject({
opKey: 71,
priority: 'user-visible',
});
expect(results.at(-1)?.data).toEqual({ status: 'latest' });
setVisibility('visible');
await tick();
expect(host.reads).toHaveLength(3);
});
it('allows initial queries, explicit refetches, saves, and subscription writes while hidden', async () => {
setVisibility('hidden');
host.scriptRead({ kind: 'hit', data: { status: 'old' } });
const { ops, results, forwarded, client } = harness(host);
ops.next(makeOp(71));
await tick();
host.pushAffected([71]);
ops.next(makeOp(71, 'network-only'));
ops.next(makeMutationOp(73, { setEntityProperty: { id: 'prop-1' } }));
ops.next(makeSubscriptionOp(74));
await tick();
expect(host.reads).toHaveLength(1);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
expect(forwarded.map((op) => op.kind)).toContain('query');
expect(host.begins).toHaveLength(1);
expect(host.commits).toHaveLength(1);
expect(host.writes).toHaveLength(1);
expect(
results.find((result) => result.operation.kind === 'mutation')
).toMatchObject({
extensions: {
normalizedCacheMutationDisposition: { kind: 'committed' },
},
});
// An actual subscription payload must also write through, not just pass
// its operation down the transport while hidden.
const subscription = harness(host, () => ({ data: { live: true } }));
subscription.ops.next(makeSubscriptionOp(75));
await tick();
expect(host.writes.at(-1)?.data).toEqual({ live: true });
});
it.each([false, true])(
'preserves an authoritative request across catch-up (already pending=%s)',
async (alreadyPending) => {
host.scriptRead({ kind: 'hit', data: { status: 'old' } });
const { ops, network, results, forwarded, client } =
controlledQueryHarness(host);
ops.next(
makeOp(71, alreadyPending ? 'cache-and-network' : 'cache-first')
);
await tick();
setVisibility('hidden');
host.scriptRead({ kind: 'hit', data: { status: 'optimistic' } });
host.pushAffected([71]);
host.pushAffected([71]);
if (!alreadyPending) ops.next(makeOp(71, 'network-only'));
await tick();
expect(host.reads).toHaveLength(1);
expect(results).toHaveLength(1);
expect(forwarded).toHaveLength(1);
setVisibility('visible');
await tick();
expect(host.reads).toHaveLength(2);
expect(results.at(-1)).toMatchObject({
data: { status: 'optimistic' },
stale: true,
});
expect(client.reexecuteOperation).not.toHaveBeenCalled();
expect(forwarded).toHaveLength(1);
network.next({
operation: forwarded[0]!,
data: { status: 'committed' },
stale: false,
hasNext: false,
});
await tick();
expect(results.at(-1)?.data).toEqual({ status: 'committed' });
expect(host.writes).toHaveLength(1);
expect(forwarded).toHaveLength(1);
}
);
it('keeps cache-only catch-up misses off the network', async () => {
const { ops, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(71, 'cache-only'));
await tick();
setVisibility('hidden');
host.pushAffected([71]);
expect(host.reads).toHaveLength(1);
setVisibility('visible');
await tick();
expect(host.reads).toHaveLength(2);
expect(forwarded).toHaveLength(0);
expect(client.reexecuteOperation).toHaveBeenCalledOnce();
expect(
vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0].context
.requestPolicy
).toBe('cache-only');
});
it('defers a network-completion reread without losing its registration-only policy', async () => {
const read = host.readQuery.bind(host);
host.readQuery = async (args) => {
const result = await read(args);
if (host.reads.length === 1) {
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
}
return result;
};
const { ops, network, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(71));
await tick();
setVisibility('hidden');
host.pushAffected([71]);
network.next({
operation: forwarded[0]!,
data: undefined,
stale: false,
hasNext: false,
});
await tick();
expect(host.reads).toHaveLength(1);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
setVisibility('visible');
await tick();
expect(host.reads).toHaveLength(2);
expect(forwarded).toHaveLength(1);
expect(
vi.mocked(client.reexecuteOperation).mock.calls[0]?.[0].context
).toMatchObject({ normalizedCacheReplacementRegistrationOnly: true });
host.pushAffected([71]);
await tick();
expect(forwarded).toHaveLength(2);
expect(
vi.mocked(client.reexecuteOperation).mock.calls[1]?.[0].context
).toMatchObject({ normalizedCacheReplacementRegistrationOnly: false });
});
it('continues restoring retained network data into a replacement worker while hidden', async () => {
const read = host.readQuery.bind(host);
host.readQuery = async (args) => {
await read(args);
throw Object.assign(new Error('old owner lost'), {
errorCode: 'owner-epoch-lost',
});
};
const write = host.writeQuery.bind(host);
host.writeQuery = vi
.fn()
.mockRejectedValueOnce(new Error('replacement not ready'))
.mockImplementation(write);
const { ops, network, forwarded, client } = controlledQueryHarness(host);
ops.next(makeOp(71));
await tick();
setVisibility('hidden');
network.next({
operation: forwarded[0]!,
data: { status: 'committed' },
stale: false,
hasNext: false,
});
await tick();
host.pushAffected([71]);
await tick();
expect(host.writeQuery).toHaveBeenCalledTimes(2);
expect(host.writes.at(-1)).toMatchObject({
data: { status: 'committed' },
registerDependencies: true,
});
expect(host.reads).toHaveLength(1);
expect(forwarded).toHaveLength(1);
expect(client.reexecuteOperation).not.toHaveBeenCalled();
});
});
describe('mutations', () => {
const optimistic = { setEntityProperty: { id: 'prop-1' } };
it('carries submitted client metadata through queue admission and settlement', async () => {
const enqueue = vi.spyOn(host, 'enqueueOptimisticMutation');
const metadata = {
kind: 'email-draft',
id: 'discard-attempt',
revision: 7,
};
const beforeMutationAttempt = vi.fn(
async (mutation: ClaimedMutation) =>
mutation.clientMetadata?.id === metadata.id
);
const onMutationAttemptResult = vi.fn(async () => {});
const { client, forwarded } = harness(host, undefined, {
beforeMutationAttempt,
onMutationAttemptResult,
});
await executeOptimisticMutation(
client,
MUTATION,
{ input: {} },
optimistic,
{
uuid: crypto.randomUUID(),
clientMetadata: metadata,
}
).toPromise();
await tick();
expect(enqueue).toHaveBeenCalledWith(
expect.objectContaining({ clientMetadata: metadata }),
expect.anything()
);
expect(beforeMutationAttempt).toHaveBeenCalledWith(
expect.objectContaining({ clientMetadata: metadata })
);
expect(forwarded).toHaveLength(1);
expect(forwarded[0].variables).toEqual({ input: {} });
expect(onMutationAttemptResult).toHaveBeenCalledWith(
expect.objectContaining({ clientMetadata: metadata }),
expect.anything(),
false
);
expect(host.commits).toHaveLength(1);
});
it('hands calendar events it cannot predict to the queue', async () => {
const enqueue = vi.spyOn(host, 'enqueueOptimisticMutation');
const { client } = harness(host);
await executeOptimisticMutation(
client,
MUTATION,
{ input: {} },
optimistic,
{
uuid: crypto.randomUUID(),
uncertainCalendarEventKeys: ['GraphqlCalendarEvent:event-1'],
}
).toPromise();
await tick();
expect(enqueue).toHaveBeenCalledWith(
expect.objectContaining({
uncertainCalendarEventKeys: ['GraphqlCalendarEvent:event-1'],
}),
expect.anything()
);
});
it.each([false, true])(
'discards an old query when a different tab commits the mutation (hydration=%s)',
async (hydration) => {
let settle!: (settlement: MutationSettlement) => void;
vi.spyOn(host, 'onMutationSettled').mockImplementation((callback) => {
settle = callback;
return () => undefined;
});
const { ops, network, forwarded, results } =
controlledQueryHarness(host);
ops.next(hydration ? makeHydrationOp(1) : makeOp(1, 'network-only'));
await tick();
settle({ status: 'committed', transactionId: 'other-tab-transaction' });
network.next(queryResult(forwarded[0], { from: 'obsolete' }));
await tick();
expect(results).toEqual([]);
expect(host.writes).toEqual([]);
expect(forwarded).toHaveLength(2);
}
);
it.each([false, true])(
'fences CRM responses dispatched before a confirmed REST write (hydration=%s)',
async (hydration) => {
const { ops, network, forwarded, results } =
controlledQueryHarness(host);
ops.next(hydration ? makeHydrationOp(1) : makeOp(1, 'network-only'));
await tick();
recordExternalWrite(host, ['GraphqlSoupCrmContact']);
network.next(
queryResult(forwarded[0], {
item: {
__typename: 'GraphqlSoupCrmContact',
id: 'contact-1',
hidden: false,
},
})
);
await tick();
expect(results).toEqual([]);
expect(host.writes).toEqual([]);
expect(forwarded).toHaveLength(2);
const fresh = {
item: {
__typename: 'GraphqlSoupCrmContact',
id: 'contact-1',
hidden: true,
},
};
network.next(queryResult(forwarded[1], fresh));
await tick();
expect(results.at(-1)?.data).toEqual(fresh);
}
);
it.each([false, true])(
'fences empty and CRM-free pages with declared membership dependencies (hydration=%s)',
async (hydration) => {
const { ops, network, forwarded, results } =
controlledQueryHarness(host);
const operation = hydration
? makeHydrationOp(1)
: makeOp(1, 'network-only');
ops.next(
makeOperation('query', operation, {
...operation.context,
externalCacheWriteTypes: ['GraphqlSoupCrmContact'],
})
);
await tick();
recordExternalWrite(host, ['GraphqlSoupCrmContact']);
network.next(queryResult(forwarded[0], { items: [] }));
await tick();
expect(results).toEqual([]);
expect(host.writes).toEqual([]);
expect(forwarded).toHaveLength(2);
recordExternalWrite(host, ['GraphqlSoupCrmContact']);
network.next(
queryResult(forwarded[1], {
items: [{ __typename: 'GraphqlSoupDocument', id: 'document-1' }],
})
);
await tick();
expect(results).toEqual([]);
expect(host.writes).toEqual([]);
expect(forwarded).toHaveLength(3);
const restored = {
items: [
{
__typename: 'GraphqlSoupCrmContact',
id: 'contact-1',
hidden: false,
},
],
};
network.next(queryResult(forwarded[2], restored));
await tick();
expect(results.at(-1)?.data).toEqual(restored);
}
);
it('keeps unrelated in-flight responses after a REST CRM write', async () => {
const { ops, network, forwarded, results } = controlledQueryHarness(host);
const operation = makeOp(1, 'network-only');
ops.next(
makeOperation('query', operation, {
...operation.context,
externalCacheWriteTypes: [],
})
);
await tick();
recordExternalWrite(host, [
'GraphqlSoupCrmCompany',
'GraphqlSoupCrmContact',
]);
const document = {
item: { __typename: 'GraphqlSoupDocument', id: 'document-1' },
};
network.next(queryResult(forwarded[0], document));
await tick();
expect(results.at(-1)?.data).toEqual(document);
expect(forwarded).toHaveLength(1);
});
it('honors cache-only if a subscriber changes policy before an obsolete response arrives', async () => {
const { ops, network, forwarded } = controlledQueryHarness(host);
ops.next(makeOp(1, 'network-only'));
ops.next(makeMutationOp(2));
await tick();
network.next(queryResult(forwarded[1], { saved: true }));
ops.next(makeOp(1, 'cache-only'));
await tick();
network.next(queryResult(forwarded[0], { from: 'obsolete' }));
await tick();
expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(1);
});
it.each([false, true])(
'restarts a pre-mutation read without publishing or persisting its stale response (hydration=%s)',
async (hydration) => {
const hydrate = vi.spyOn(host, 'hydrateQuery');
const { ops, network, forwarded, results } =
controlledQueryHarness(host);
ops.next(hydration ? makeHydrationOp(1) : makeOp(1, 'network-only'));
await tick();
const read = forwarded[0];
ops.next(makeMutationOp(2));
await tick();
network.next(queryResult(forwarded[1], { saved: true }));
await tick();
network.next({
...queryResult(read, { from: 'obsolete' }),
hasNext: true,
});
await tick();
expect(forwarded).toHaveLength(2);
network.next(queryResult(read, { from: 'obsolete' }));
await tick();
expect(forwarded).toHaveLength(3);
expect(
results.filter(({ operation }) => operation.kind === 'query')
).toEqual([]);
expect(host.writes).not.toContainEqual(
expect.objectContaining({ data: { from: 'obsolete' } })
);
network.next(queryResult(forwarded[2], { from: 'fresh' }));
await tick();
expect(results.at(-1)?.data).toEqual({ from: 'fresh' });
if (hydration) {
expect(hydrate).toHaveBeenCalledWith(
expect.objectContaining({
query: expect.stringContaining('@cacheOnly'),
})
);
}
}
);
it.each([false, true])(
'does not restart an obsolete query after teardown (hydration=%s)',
async (hydration) => {
const { ops, network, forwarded } = controlledQueryHarness(host);
ops.next(hydration ? makeHydrationOp(1) : makeOp(1, 'network-only'));
ops.next(makeMutationOp(2));
await tick();
network.next(queryResult(forwarded[1], { saved: true }));
ops.next(teardownOf(forwarded[0]));
network.next(queryResult(forwarded[0], { from: 'obsolete' }));
await tick();
expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(
1
);
expect(host.writes).not.toContainEqual(
expect.objectContaining({ data: { from: 'obsolete' } })
);
}
);
it('rechecks a response held behind an earlier persistence turn after mutation settlement', async () => {
const pending = deferred<void>();
const write = host.writeQuery.bind(host);
vi.spyOn(host, 'writeQuery').mockImplementationOnce(async (args) => {
const result = await write(args);
await pending.promise;
return result;
});
const { ops, network, forwarded } = controlledQueryHarness(host);
ops.next(makeOp(1, 'network-only'));
await tick();
network.next({
...queryResult(forwarded[0], { from: 'first' }),
hasNext: true,
});
await tick();
network.next(queryResult(forwarded[0], { from: 'obsolete' }));
ops.next(makeMutationOp(2));
await tick();
network.next(queryResult(forwarded[1], { saved: true }));
await tick();
pending.resolve();
await tick();
expect(host.writes).not.toContainEqual(
expect.objectContaining({ data: { from: 'obsolete' } })
);
expect(forwarded.filter(({ kind }) => kind === 'query')).toHaveLength(2);
});
it('does not discard an in-flight query after a rejected mutation', async () => {
const { ops, network, forwarded, results } = controlledQueryHarness(host);
ops.next(makeOp(1, 'network-only'));
ops.next(makeMutationOp(2));
await tick();
network.next({
...queryResult(forwarded[1], undefined),
error: new CombinedError({ graphQLErrors: [new Error('forbidden')] }),
});
network.next(queryResult(forwarded[0], { from: 'valid' }));
await tick();
expect(forwarded).toHaveLength(2);
expect(results.at(-1)?.data).toEqual({ from: 'valid' });
});
it.each([false, true])(
'rolls back rejected favorites rather than committing list patches (replay=%s)',
async (replay) => {
let submitted: Operation | undefined;
const capturingClient = {
mutation: (
query: Operation['query'],
variables: Operation['variables'],
context: Operation['context']
) => {
submitted = makeOperation(
'mutation',
createRequest(query, variables),
{
...context,
url: 'http://test',
requestPolicy: 'network-only',
}
);
return { toPromise: async () => ({}) };
},
} as unknown as Client;
await executeGraphqlSetFavoriteMutation(
capturingClient,
{
entityType: 'document',
entityId: 'document-1',
},
true,
0
);
if (!submitted) throw new Error('expected favorite submission');
const context = optimisticContextOf(submitted)!;
expect(context.linkPatches).toHaveLength(1);
if (replay) {
host.seedQueued({
uuid: context.uuid,
query: stringifyDocument(submitted.query),
operationName: 'SetFavorite',
variables: submitted.variables ?? undefined,
data: context.optimisticResponse,
linkPatches: context.linkPatches,
revalidations: context.revalidations,
});
}
// setFavorite emits GraphQL errors at the transport level, not an error
// union nested inside data. Replay needs no mounted mutation hook.
const error = new CombinedError({
graphQLErrors: [new Error('not authorized to update favorites')],
});
const { ops, client } = harness(host, () => ({
data: undefined,
error,
}));
if (replay) {
vi.mocked(client.mutation).mockReturnValue({
toPromise: async () => ({ error }),
} as never);
} else {
ops.next(submitted);
}
await tick();
expect(host.commits).toEqual([]);
expect(host.rollbacks).toEqual([replay ? '1' : '1']);
}
);
it.each([markGraphqlEmailThreadSeen, markGraphqlEmailThreadUnread])(
'revalidates Soup membership after a queued read-state write replays on startup',
async (markReadState) => {
let submitted: Operation | undefined;
const capturingClient = createClient({
url: 'http://test',
exchanges: [
optimisticResolversExchange(soupOptimisticResolvers),
() => (operations) =>
pipe(
operations,
map((operation) => {
submitted = operation;
return {
operation,
stale: false,
hasNext: false,
extensions: {
normalizedCacheMutationDisposition: {
kind: 'queued',
transactionId: '1',
},
},
};
})
),
],
});
const variables = [
{ input: { initial: { limit: 2 } } },
{ input: { continuation: { cursor: 'next' } } },
];
await expect(
markReadState(
capturingClient,
'thread',
variables.map((variables) => ({
document: QUERY,
variables,
}))
)
).resolves.toBe('queued');
if (!submitted) throw new Error('expected read-state submission');
const context = optimisticContextOf(submitted)!;
expect(context.revalidations).toHaveLength(2);
host.seedQueued({
uuid: context.uuid,
query: stringifyDocument(submitted.query),
variables: submitted.variables ?? undefined,
data: context.optimisticResponse,
revalidations: JSON.parse(JSON.stringify(context.revalidations)),
});
const { client } = harness(host, (op) =>
op.kind === 'mutation' ? { data: context.optimisticResponse } : {}
);
await tick();
expect(host.commits[0]?.transactionId).toBe('1');
expect(vi.mocked(client.query)).toHaveBeenCalledTimes(2);
expect(
vi.mocked(client.query).mock.calls.map((call) => call[1])
).toEqual(variables);
for (const call of vi.mocked(client.query).mock.calls) {
expect(call[2]).toEqual({ requestPolicy: 'network-only' });
}
}
);
it('replays a persisted mutation when the exchange starts', async () => {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000001',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
data: optimistic,
});
const { forwarded } = harness(host);
await tick();
expect(host.begins).toHaveLength(0);
expect(host.claims).toEqual(['1']);
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
expect(forwarded[0]?.context.fetch).toBeTypeOf('function');
expect(host.commits[0]?.transactionId).toBe('1');
});
it.each(['rejects', 'hangs'] as const)(
'advances after a terminal draft error even when recovery bookkeeping %s',
async (failure) => {
vi.useFakeTimers();
try {
const metadata = { kind: 'email-draft', revision: 7 };
host.seedQueued({
uuid: 'draft-handle',
query: stringifyDocument(SaveEmailDraftDocument),
operationName: 'SaveEmailDraft',
variables: { input: { draftId: 'draft-handle' } },
data: optimistic,
clientMetadata: metadata,
});
host.seedQueued({
uuid: 'unrelated',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
data: optimistic,
});
const onMutationAttemptResult = vi.fn(
async (mutation: ClaimedMutation) => {
if (mutation.operationName !== 'SaveEmailDraft') return;
if (failure === 'rejects')
throw new Error('Recovery disk unavailable');
await new Promise<void>(() => {});
}
);
const { forwarded } = harness(
host,
(op) =>
'draftId' in op.variables!.input
? {
data: undefined,
error: new CombinedError({
graphQLErrors: [
{
message: 'Draft rejected',
extensions: { retryable: true },
},
],
}),
}
: { data: { saved: true } },
{
shouldRetryMutation: shouldRetryGraphqlMutation,
onMutationAttemptResult,
onCacheError: () => {
throw new Error('Diagnostics unavailable');
},
}
);
await vi.advanceTimersByTimeAsync(2_010);
expect(onMutationAttemptResult).toHaveBeenCalledWith(
expect.objectContaining({ clientMetadata: metadata }),
expect.anything(),
false
);
expect(host.rollbacks).toEqual(['1']);
expect(host.defers).toHaveLength(0);
expect(host.commits).toMatchObject([{ transactionId: '2' }]);
expect(forwarded).toHaveLength(2);
} finally {
vi.useRealTimers();
}
}
);
it.each(['rejects', 'hangs'] as const)(
'replays unrelated mutations when recovery initialization %s',
async (failure) => {
vi.useFakeTimers();
const skipped = vi.fn();
try {
host.seedQueued({
uuid: 'unrelated',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
data: optimistic,
});
const { forwarded } = harness(host, undefined, {
prepareMutationQueue: async () => {
if (failure === 'rejects')
throw new Error('IndexedDB unavailable');
await new Promise<void>(() => {});
},
mutationQueueTelemetry: {
...NOOP_MUTATION_QUEUE_TELEMETRY,
skipped,
},
});
await vi.advanceTimersByTimeAsync(4_010);
expect(forwarded).toHaveLength(1);
expect(host.commits).toMatchObject([{ transactionId: '1' }]);
expect(skipped).toHaveBeenCalledWith(
failure === 'rejects' ? 'recovery-failed' : 'recovery-timeout'
);
} finally {
vi.useRealTimers();
}
}
);
it('reports each recovery failure while the queue keeps polling', async () => {
vi.useFakeTimers();
const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
const skipped = vi.fn();
try {
const prepareMutationQueue = vi.fn(async () => {
throw new Error('Queue inspection is unavailable');
});
harness(host, undefined, {
prepareMutationQueue,
mutationQueueTelemetry: { ...NOOP_MUTATION_QUEUE_TELEMETRY, skipped },
});
await vi.advanceTimersByTimeAsync(90_010);
expect(prepareMutationQueue).toHaveBeenCalledTimes(4);
expect(skipped.mock.calls).toEqual(
Array(4).fill(['recovery-inspection-unavailable'])
);
expect(warning).not.toHaveBeenCalled();
} finally {
warning.mockRestore();
vi.useRealTimers();
}
});
it('retries deferred recovery quietly until it can run', async () => {
vi.useFakeTimers();
const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
try {
let signedIn = false;
const prepareMutationQueue = vi.fn(async () =>
signedIn ? undefined : false
);
harness(host, undefined, { prepareMutationQueue });
await vi.advanceTimersByTimeAsync(10);
expect(prepareMutationQueue).toHaveBeenCalledOnce();
signedIn = true;
await vi.advanceTimersByTimeAsync(30_000);
expect(prepareMutationQueue).toHaveBeenCalledTimes(2);
await vi.advanceTimersByTimeAsync(60_000);
expect(prepareMutationQueue).toHaveBeenCalledTimes(2);
expect(warning).not.toHaveBeenCalled();
} finally {
warning.mockRestore();
vi.useRealTimers();
}
});
/** Like the draft lifecycle: drafts cannot be judged until user info loads. */
function signedInDraftLifecycle(): {
signIn(): void;
options: NormalizedCacheExchangeOptions;
} {
let signedIn = false;
return {
signIn: () => {
signedIn = true;
},
options: {
prepareMutationQueue: async () => (signedIn ? undefined : false),
beforeMutationAttempt: async (mutation) =>
signedIn || mutation.operationName !== 'SaveEmailDraft'
? true
: 'defer',
},
};
}
function draftOp(key: number): Operation {
return makeOperation(
'mutation',
createRequest(SaveEmailDraftDocument, {
input: { draftId: 'draft', subject: 'Draft' },
}),
makeMutationOp(key, optimistic).context
);
}
it('keeps a restored draft queued until sign-in instead of rolling it back', async () => {
vi.useFakeTimers();
try {
host.seedQueued({
uuid: 'draft',
query: stringifyDocument(SaveEmailDraftDocument),
operationName: 'SaveEmailDraft',
variables: { input: { draftId: 'draft' } },
data: optimistic,
clientMetadata: { kind: 'email-draft' },
});
const lifecycle = signedInDraftLifecycle();
const { forwarded } = harness(host, undefined, lifecycle.options);
await vi.advanceTimersByTimeAsync(5_000);
expect(host.defers.length).toBeGreaterThan(1);
expect(host.rollbacks).toHaveLength(0);
expect(forwarded).toHaveLength(0);
lifecycle.signIn();
await vi.advanceTimersByTimeAsync(1_010);
expect(host.rollbacks).toHaveLength(0);
expect(forwarded).toHaveLength(1);
expect(host.commits).toMatchObject([{ transactionId: '1' }]);
} finally {
vi.useRealTimers();
}
});
it('sends other mutations while draft recovery waits for sign-in', async () => {
vi.useFakeTimers();
try {
host.seedQueued({
uuid: 'unrelated',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
data: optimistic,
});
const { forwarded } = harness(
host,
undefined,
signedInDraftLifecycle().options
);
await vi.advanceTimersByTimeAsync(10);
expect(forwarded).toHaveLength(1);
expect(host.defers).toHaveLength(0);
expect(host.commits).toMatchObject([{ transactionId: '1' }]);
} finally {
vi.useRealTimers();
}
});
it('defers a draft enqueued before sign-in instead of rolling it back', async () => {
vi.useFakeTimers();
try {
const lifecycle = signedInDraftLifecycle();
const { ops, results, forwarded } = harness(
host,
undefined,
lifecycle.options
);
ops.next(draftOp(1));
await vi.advanceTimersByTimeAsync(10);
expect(host.claims).toEqual(['1']);
expect(host.defers).toMatchObject([{ transactionId: '1' }]);
expect(host.rollbacks).toHaveLength(0);
expect(forwarded).toHaveLength(0);
expect(results).toHaveLength(1);
expect(results[0]?.error).toBeUndefined();
lifecycle.signIn();
await vi.advanceTimersByTimeAsync(1_010);
expect(host.rollbacks).toHaveLength(0);
expect(forwarded).toHaveLength(1);
expect(host.commits).toMatchObject([{ transactionId: '1' }]);
} finally {
vi.useRealTimers();
}
});
it('stops polling once its host is retired', async () => {
vi.useFakeTimers();
try {
const retirable = createRetirableCacheHost(host);
const drained = vi.spyOn(retirable, 'currentRevision');
harness(retirable);
await vi.advanceTimersByTimeAsync(10);
expect(drained).toHaveBeenCalledOnce();
retirable.dispose();
await vi.advanceTimersByTimeAsync(120_000);
dispatchEvent(new Event('online'));
await vi.advanceTimersByTimeAsync(10);
expect(drained).toHaveBeenCalledOnce();
} finally {
vi.useRealTimers();
}
});
it.each([
{ failure: 'rejects', legacy: false },
{ failure: 'hangs', legacy: false },
{ failure: 'rejects', legacy: true },
{ failure: 'hangs', legacy: true },
])(
'releases a draft when admission $failure (legacy=$legacy)',
async ({ failure, legacy }) => {
vi.useFakeTimers();
try {
host.seedQueued({
uuid: 'draft',
query: stringifyDocument(SaveEmailDraftDocument),
operationName: 'SaveEmailDraft',
variables: { input: { draftId: 'draft' } },
data: optimistic,
clientMetadata: legacy ? undefined : { kind: 'email-draft' },
});
host.seedQueued({
uuid: 'other',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
data: optimistic,
});
const onMutationAttemptResult = vi.fn(async () => {});
const { forwarded } = harness(host, undefined, {
beforeMutationAttempt: async (mutation) => {
if (mutation.operationName !== 'SaveEmailDraft') return true;
if (failure === 'rejects')
throw new Error('Recovery storage unavailable');
return await new Promise<boolean>(() => {});
},
onMutationAttemptResult,
});
await vi.advanceTimersByTimeAsync(2_010);
expect(host.rollbacks).toEqual(['1']);
expect(host.defers).toHaveLength(0);
expect(host.commits).toMatchObject([{ transactionId: '2' }]);
expect(forwarded).toHaveLength(1);
expect(onMutationAttemptResult).toHaveBeenCalledWith(
expect.objectContaining({ transactionId: '1' }),
expect.objectContaining({
error: expect.objectContaining({
message: expect.stringContaining('Unable to prepare'),
}),
}),
false
);
} finally {
vi.useRealTimers();
}
}
);
it('returns a terminal recovery failure to a live caller without sending it', async () => {
const { ops, results, forwarded } = harness(host, undefined, {
beforeMutationAttempt: async () => {
throw new Error('Local storage unavailable');
},
});
ops.next(makeMutationOp(1, optimistic));
await vi.waitFor(() => expect(results).toHaveLength(1));
expect(forwarded).toHaveLength(0);
expect(host.defers).toHaveLength(0);
expect(host.rollbacks).toEqual(['1']);
expect(optimisticMutationDispositionOf(results[0])).toMatchObject({
kind: 'permanently-failed',
error: results[0]?.error,
});
expect(results[0]?.error?.graphQLErrors[0]?.extensions.code).toBe(
'LOCAL_RECOVERY_FAILED'
);
});
it.each([true, false])(
'advances past an unavailable archived thread regardless of legacy metadata (retryable=%s)',
async (retryable) => {
vi.useFakeTimers();
try {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000001',
query: stringifyDocument(SetEmailThreadArchivedDocument),
operationName: 'SetEmailThreadArchived',
variables: {
input: { threadId: 'trashed-thread', archived: true },
},
data: {
setEmailThreadArchived: {
__typename: 'GraphqlSoupEmailThread',
id: 'trashed-thread',
inboxVisible: false,
},
},
});
const readResult = {
updateNotifications: [
{
__typename: 'GraphqlNotification',
id: 'notification',
state: 'SEEN',
},
],
};
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000002',
query: stringifyDocument(UpdateNotificationsDocument),
operationName: 'UpdateNotifications',
variables: {
input: {
notificationIds: ['notification'],
operation: 'MARK_SEEN',
},
},
data: {
updateNotifications: [
{ __typename: 'GraphqlNotification', id: 'notification' },
],
},
});
const { forwarded } = harness(
host,
(op) =>
'threadId' in op.variables!.input
? {
data: undefined,
error: new CombinedError({
graphQLErrors: [
{
message: 'updated email thread is unavailable',
extensions: retryable
? { code: 'INTERNAL', retryable: true }
: { code: 'NOT_FOUND' },
},
],
}),
}
: { data: readResult },
{ shouldRetryMutation: shouldRetryGraphqlMutation }
);
await vi.advanceTimersByTimeAsync(10);
expect(forwarded).toHaveLength(2);
expect(host.defers).toHaveLength(0);
expect(host.rollbacks).toEqual(['1']);
expect(host.commits).toMatchObject([
{ transactionId: '2', data: readResult },
]);
} finally {
vi.useRealTimers();
}
}
);
it.each([
'terminal',
'superseded',
'retryable',
'unhandled replay',
] as const)(
'revalidates persisted recovery queries only after a terminal failure (%s)',
async (outcome) => {
vi.useFakeTimers();
try {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000001',
query: stringifyDocument(SaveEmailDraftDocument),
operationName: 'SaveEmailDraft',
variables: { input: { draftId: 'draft-handle', subject: 'Reply' } },
data: optimistic,
revalidations: [
{
query: stringifyDocument(QUERY),
operationName: 'Soup',
variablesJson: '{"input":{"limit":2}}',
},
],
});
if (outcome === 'superseded') {
const rollback = host.rollbackOptimisticWrite.bind(host);
host.rollbackOptimisticWrite = async (...args) => ({
...(await rollback(...args)),
kind: 'discarded-superseded',
replacementTransactionId: 'newer-intent',
});
}
const error = new CombinedError(
outcome === 'retryable'
? { networkError: new Error('Connection lost') }
: {
graphQLErrors: [
{
message: 'Draft rejected',
extensions: { code: 'DRAFT_ALREADY_SENT' },
},
],
}
);
const { client, forwarded } = harness(
host,
() => ({ error, data: undefined }),
{
shouldRetryMutation: shouldRetryGraphqlMutation,
}
);
if (outcome === 'unhandled replay') {
vi.mocked(client.mutation).mockReturnValue({
toPromise: async () => ({ error }),
} as never);
}
await vi.advanceTimersByTimeAsync(0);
expect(host.begins).toHaveLength(0);
expect(host.claims).toEqual(['1']);
expect(host.rollbacks).toHaveLength(outcome === 'retryable' ? 0 : 1);
expect(host.defers).toHaveLength(outcome === 'retryable' ? 1 : 0);
const repairs =
outcome === 'terminal' || outcome === 'unhandled replay';
expect(vi.mocked(client.query)).toHaveBeenCalledTimes(
repairs ? 1 : 0
);
if (repairs) {
expect(vi.mocked(client.query)).toHaveBeenCalledWith(
expect.anything(),
{ input: { limit: 2 } },
{ requestPolicy: 'network-only' }
);
}
if (outcome !== 'unhandled replay')
expect(optimisticContextOf(forwarded[0])).toBeUndefined();
} finally {
vi.useRealTimers();
}
}
);
it.each([true, undefined])(
'settles a restored superseded identity write before its replacement (confirmation=%s)',
async (requiresConfirmation) => {
for (const version of ['create', 'edit']) {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000001',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: { version } },
data: optimistic,
});
}
const claimNext = host.claimNextMutation.bind(host);
host.claimNextMutation = async (...args) => {
const claimed = await claimNext(...args);
if (claimed?.transactionId === '1') {
claimed.superseded = true;
if (requiresConfirmation === undefined) {
// Old deployed hosts have no flag. They must also recover.
delete (claimed as Partial<ClaimedMutation>).requiresConfirmation;
} else {
claimed.requiresConfirmation = requiresConfirmation;
}
}
return claimed;
};
const onCacheError = vi.fn();
const { forwarded } = harness(host, undefined, { onCacheError });
await vi.waitFor(() =>
expect(host.commits.map((commit) => commit.transactionId)).toEqual([
'1',
'2',
])
);
expect(forwarded.map((op) => op.variables?.input.version)).toEqual([
'create',
'edit',
]);
expect(host.defers).toEqual([]);
expect(onCacheError).not.toHaveBeenCalled();
}
);
it('evicts deleted threads when a persisted mutation replays without its caller', async () => {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000003',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
data: optimistic,
});
const deletedRecordKeys = vi.fn(() => {
expect(host.commits).toHaveLength(1);
return ['GraphqlSoupEmailThread:gone'];
});
harness(host, undefined, { deletedRecordKeys });
await tick();
expect(host.invalidations).toEqual([['GraphqlSoupEmailThread:gone']]);
});
describe('mutation drain after cache restoration', () => {
it.each(['failed', 'pending', 'late network'] as const)(
'does not reuse an old mutation response after storage resets (%s)',
async (oldResponse) => {
const commit = vi.spyOn(host, 'commitOptimisticWrite');
const pending = deferred<CommitOptimisticWriteResult>();
if (oldResponse === 'failed')
commit.mockRejectedValueOnce(new Error('local disk unavailable'));
if (oldResponse === 'pending')
commit.mockImplementationOnce(() => pending.promise);
const { ops, network, forwarded } = controlledQueryHarness(host);
const oldData = { setEntityProperty: { id: 'old-effect' } };
const newData = { setEntityProperty: { id: 'new-effect' } };
ops.next(makeMutationOp(1, oldData));
await vi.advanceTimersByTimeAsync(1);
const oldOperation = forwarded[0];
if (oldResponse !== 'late network') {
network.next(queryResult(oldOperation, oldData));
await vi.advanceTimersByTimeAsync(1);
}
host.resetStorage();
ops.next(makeMutationOp(2, newData));
await vi.advanceTimersByTimeAsync(1);
expect(forwarded).toHaveLength(2);
if (oldResponse === 'late network') {
network.next(queryResult(oldOperation, oldData));
} else if (oldResponse === 'pending') {
pending.reject(new CacheNavigationError());
}
await vi.advanceTimersByTimeAsync(1);
network.next(queryResult(forwarded[1], newData));
await vi.advanceTimersByTimeAsync(1);
expect(host.commits).toEqual([
{
transactionId: '1',
query: stringifyDocument(MUTATION),
data: newData,
},
]);
await vi.advanceTimersByTimeAsync(300_000);
expect(forwarded).toHaveLength(2);
}
);
beforeEach(() => vi.useFakeTimers());
afterEach(() => {
vi.clearAllTimers();
vi.useRealTimers();
vi.restoreAllMocks();
});
it('backs off empty cache wakeups while offline without spinning', async () => {
vi.spyOn(navigator, 'onLine', 'get').mockReturnValue(false);
const claim = vi.spyOn(host, 'claimNextMutation');
const { forwarded } = harness(host);
host.pushGeneration({ storage: 'reset' });
await vi.advanceTimersByTimeAsync(1_000);
expect(claim).toHaveBeenCalledOnce();
expect(host.claims).toEqual([]);
expect(forwarded).toHaveLength(0);
expect(vi.getTimerCount()).toBeLessThan(5);
});
it.each(['restore', 'poll', 'online'] as const)(
'waits for restore readiness before claiming a mutation after %s',
async (wake) => {
const events = new EventTarget();
vi.spyOn(globalThis, 'addEventListener').mockImplementation(
events.addEventListener.bind(events)
);
const { forwarded } = harness(host);
await vi.advanceTimersByTimeAsync(0);
host.seedQueued({
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
data: optimistic,
});
const ready = deferred<void>();
vi.spyOn(host, 'currentRevision').mockImplementationOnce(async () => {
await ready.promise;
return INITIAL_CACHE_REVISION;
});
const claimNext = host.claimNextMutation.bind(host);
const claim = vi
.spyOn(host, 'claimNextMutation')
.mockImplementation(async (...args) => {
// Like the real host, a claim waits for initialization before
// admission. Its caller must not tag it with the earlier epoch.
await ready.promise;
return await claimNext(...args);
});
if (wake === 'restore') host.pushGeneration({ storage: 'preserved' });
if (wake === 'online') events.dispatchEvent(new Event('online'));
await vi.advanceTimersByTimeAsync(wake === 'poll' ? 30_000 : 0);
const claimsBeforeReady = claim.mock.calls.length;
await vi.advanceTimersByTimeAsync(5_000);
// BFCache readiness conservatively invalidates the local epoch even
// when the durable database (including this queued head) survived.
host.pushGeneration({ storage: 'reset' });
const readyAt = Date.now();
ready.resolve();
await vi.advanceTimersByTimeAsync(1);
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
expect(host.claims).toEqual(['1']);
expect(host.commits).toHaveLength(1);
expect(host.rollbacks).toEqual([]);
expect(claimsBeforeReady).toBe(0);
expect(claim.mock.calls[0]).toEqual([
'exchange:test-client',
readyAt,
readyAt + 300_000,
]);
}
);
it('retries failed readiness without acquiring a mutation lease', async () => {
host.seedQueued({
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
data: optimistic,
});
const ready = vi
.spyOn(host, 'currentRevision')
.mockRejectedValueOnce(new CacheNavigationError());
const claim = vi.spyOn(host, 'claimNextMutation');
const { forwarded } = harness(host);
await vi.advanceTimersByTimeAsync(29_999);
expect(ready).toHaveBeenCalledOnce();
expect(claim).not.toHaveBeenCalled();
expect(forwarded).toEqual([]);
await vi.advanceTimersByTimeAsync(1);
expect(host.claims).toEqual(['1']);
expect(host.commits).toHaveLength(1);
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
});
it('fences a successful claim if storage resets after admission', async () => {
host.seedQueued({
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
variables: { input: { version: 'old' } },
data: optimistic,
});
const pendingClaim = deferred<void>();
const claimNext = host.claimNextMutation.bind(host);
vi.spyOn(host, 'claimNextMutation').mockImplementationOnce(
async (...args) => {
const claimed = await claimNext(...args);
await pendingClaim.promise;
return claimed;
}
);
const { forwarded } = harness(host);
await vi.advanceTimersByTimeAsync(0);
expect(host.claims).toEqual(['1']);
host.resetStorage();
// The replacement database can reuse the old transaction ID.
host.seedQueued({
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
variables: { input: { version: 'new' } },
data: optimistic,
});
pendingClaim.resolve();
await vi.advanceTimersByTimeAsync(1);
expect(forwarded.map((op) => op.variables?.input.version)).toEqual([
'new',
]);
expect(host.commits).toHaveLength(1);
expect(host.rollbacks).toEqual([]);
});
it.each([
{ wake: 'online', whileDeferring: false },
{ wake: 'online', whileDeferring: true },
{ wake: 'restore', whileDeferring: false },
{ wake: 'restore', whileDeferring: true },
])(
'preserves short retry deadlines after $wake (while deferring: $whileDeferring)',
async ({ wake, whileDeferring }) => {
// Isolate the online listener from other exchanges in this suite.
const events = new EventTarget();
vi.spyOn(globalThis, 'addEventListener').mockImplementation(
events.addEventListener.bind(events)
);
const deferring = deferred<void>();
const defer = host.deferOptimisticWrite.bind(host);
const deferSpy = vi.spyOn(host, 'deferOptimisticWrite');
if (whileDeferring) {
deferSpy.mockImplementationOnce(async (...args) => {
const result = await defer(...args);
await deferring.promise;
return result;
});
}
const error = new CombinedError({
networkError: new Error('offline'),
});
let attempts = 0;
const { ops, forwarded } = harness(
host,
() =>
++attempts <= 5
? { error, data: undefined }
: { data: optimistic },
{ shouldRetryMutation: () => true }
);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(0);
for (const delay of [1_000, 2_000, 4_000, 8_000, 16_000]) {
const retryAt = deferSpy.mock.calls.at(-1)![2];
expect(retryAt - Date.now()).toBe(delay);
const sendsBeforeWake = forwarded.length;
await vi.advanceTimersByTimeAsync(100);
if (wake === 'online') events.dispatchEvent(new Event('online'));
else host.pushGeneration({ storage: 'preserved' });
await vi.advanceTimersByTimeAsync(1);
deferring.resolve();
await vi.advanceTimersByTimeAsync(1);
expect(forwarded).toHaveLength(sendsBeforeWake);
await vi.advanceTimersByTimeAsync(retryAt - Date.now() - 1);
expect(forwarded).toHaveLength(sendsBeforeWake);
await vi.advanceTimersByTimeAsync(1);
expect(forwarded).toHaveLength(sendsBeforeWake + 1);
}
expect(host.begins).toHaveLength(1);
expect(host.defers).toHaveLength(5);
expect(host.commits).toHaveLength(1);
expect(host.rollbacks).toHaveLength(0);
}
);
it('retires an expired retry hint if another runner owns the head', async () => {
const error = new CombinedError({ networkError: new Error('offline') });
const { ops, forwarded } = harness(
host,
() => ({ error, data: undefined }),
{ shouldRetryMutation: () => true }
);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(0);
const claim = vi
.spyOn(host, 'claimNextMutation')
.mockResolvedValue(undefined);
await vi.advanceTimersByTimeAsync(100);
host.pushGeneration({ storage: 'preserved' });
await vi.advanceTimersByTimeAsync(0);
expect(claim).toHaveBeenCalledOnce();
await vi.advanceTimersByTimeAsync(1_000);
expect(claim).toHaveBeenCalledTimes(2);
expect(forwarded).toHaveLength(1);
});
it.each([false, true])(
'resumes an interrupted claim without waiting for the poll (restore while pending: %s)',
async (restoreWhilePending) => {
const pendingClaim = deferred<ClaimedMutation | undefined>();
const claim = vi.spyOn(host, 'claimNextMutation');
claim.mockImplementationOnce(() => pendingClaim.promise);
host.seedQueued({
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
data: optimistic,
});
const { forwarded } = harness(host);
await vi.advanceTimersByTimeAsync(0);
expect(claim).toHaveBeenCalledOnce();
if (restoreWhilePending) {
host.pushGeneration({ storage: 'preserved' });
await vi.advanceTimersByTimeAsync(1);
expect(claim).toHaveBeenCalledOnce();
}
pendingClaim.reject(new CacheNavigationError());
await vi.advanceTimersByTimeAsync(1);
if (!restoreWhilePending) {
expect(forwarded).toHaveLength(0);
host.pushGeneration({ storage: 'preserved' });
await vi.advanceTimersByTimeAsync(1);
}
expect(host.claims).toEqual(['1']);
expect(host.commits).toHaveLength(1);
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
}
);
it.each([
{ restoreWhilePending: false, committed: false },
{ restoreWhilePending: false, committed: true },
{ restoreWhilePending: true, committed: false },
{ restoreWhilePending: true, committed: true },
])(
'rechecks an uncertain commit without bypassing leases ($restoreWhilePending, $committed)',
async ({ restoreWhilePending, committed }) => {
const pendingCommit = deferred<CommitOptimisticWriteResult>();
const commit = host.commitOptimisticWrite.bind(host);
vi.spyOn(host, 'commitOptimisticWrite').mockImplementationOnce(
async (...args) => {
// The worker may have committed even though its reply was lost.
if (committed) await commit(...args);
return await pendingCommit.promise;
}
);
const claim = vi.spyOn(host, 'claimNextMutation');
const { ops, forwarded, results } = harness(host);
await vi.advanceTimersByTimeAsync(0);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(1);
host.seedQueued({
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
data: optimistic,
});
const claimsBeforeRestore = claim.mock.calls.length;
if (restoreWhilePending) {
host.pushGeneration({ storage: 'preserved' });
await vi.advanceTimersByTimeAsync(1);
expect(claim).toHaveBeenCalledTimes(claimsBeforeRestore);
}
pendingCommit.reject(new CacheNavigationError());
await vi.advanceTimersByTimeAsync(1);
if (!restoreWhilePending) {
host.pushGeneration({ storage: 'preserved' });
await vi.advanceTimersByTimeAsync(1);
}
expect(claim.mock.calls.length).toBeGreaterThan(claimsBeforeRestore);
expect(
optimisticMutationDispositionOf(
results.find((result) => result.operation.key === 1)!
)
).toEqual({ kind: 'queued', transactionId: '1' });
// A runnable successor is sent immediately, but an unsettled head's
// existing lease must never be stolen or its network call duplicated.
expect(forwarded).toHaveLength(committed ? 2 : 1);
expect(host.commits).toHaveLength(committed ? 2 : 0);
const claimsAfterRestore = claim.mock.calls.length;
await vi.advanceTimersByTimeAsync(30_000);
// Forget the stale five-minute local backoff even if no head could
// be claimed on restore; the durable queue still controls eligibility.
expect(claim.mock.calls.length).toBeGreaterThan(claimsAfterRestore);
expect(forwarded).toHaveLength(committed ? 2 : 1);
// Once the old lease expires, retry persistence of the known server
// response. A local cache failure must not repeat the server effect.
await vi.advanceTimersByTimeAsync(300_000);
expect(host.commits).toHaveLength(2);
expect(forwarded).toHaveLength(2);
expect(
host.commits.map(({ transactionId }) => transactionId)
).toEqual(['1', '2']);
}
);
it('re-applies a confirmed head before admission hooks can discard it', async () => {
const events: string[] = [];
const commit = host.commitOptimisticWrite.bind(host);
let commitFailed = false;
vi.spyOn(host, 'commitOptimisticWrite').mockImplementation(
async (...args) => {
if (!commitFailed) {
commitFailed = true;
events.push(`commit failed ${args[0]}`);
throw new Error('local disk unavailable');
}
events.push(`commit ${args[0]}`);
return await commit(...args);
}
);
const rollback = host.rollbackOptimisticWrite.bind(host);
vi.spyOn(host, 'rollbackOptimisticWrite').mockImplementation(
async (...args) => {
events.push(`rollback ${args[0]} ${args[3]}`);
return await rollback(...args);
}
);
const onMutationAttemptResult = vi.fn(
async (
mutation: ClaimedMutation,
_result: OperationResult,
_retry: boolean
) => {
events.push(`result ${mutation.transactionId}`);
}
);
let admissions = 0;
const { ops, forwarded } = harness(host, undefined, {
// Only the first admission is current; later local intent is obsolete.
beforeMutationAttempt: async (mutation) => {
events.push(`admit ${mutation.transactionId}`);
admissions += 1;
return admissions === 1;
},
onMutationAttemptResult,
});
await vi.advanceTimersByTimeAsync(0);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(1);
ops.next(makeMutationOp(2, optimistic));
// The confirmed head is reclaimed once its lease expires.
await vi.advanceTimersByTimeAsync(300_000);
expect(events).toEqual([
'admit 1',
'result 1',
'commit failed 1',
// Re-applied without sending again or asking admission to veto it.
'result 1',
'commit 1',
'admit 2',
'rollback 2 LOCAL_SUPERSEDED',
]);
expect(forwarded).toHaveLength(1);
expect(host.commits).toMatchObject([
{ transactionId: '1', data: { from: 'network' } },
]);
const confirmedResult = [
expect.objectContaining({ transactionId: '1' }),
expect.objectContaining({ data: { from: 'network' } }),
false,
];
expect(onMutationAttemptResult.mock.calls).toEqual([
confirmedResult,
confirmedResult,
]);
});
// The replacement queue reuses transaction id 1 and lease
// generation 1, so an unfenced stale attempt would discard the new head.
it('fences a recovery-failure rollback after storage resets', async () => {
const recording = deferred<void>();
let admissions = 0;
const { ops, forwarded } = controlledQueryHarness(host, {
beforeMutationAttempt: async () => {
admissions += 1;
if (admissions === 1) throw new Error('Recovery storage lost');
return true;
},
onMutationAttemptResult: () => recording.promise,
});
await vi.advanceTimersByTimeAsync(0);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(1);
host.resetStorage();
ops.next(makeMutationOp(2, optimistic));
await vi.advanceTimersByTimeAsync(1);
expect(forwarded).toHaveLength(1);
recording.resolve();
await vi.advanceTimersByTimeAsync(1);
expect(host.rollbacks).toEqual([]);
});
});
it('rolls back when a persisted replay resolves with an urql error', async () => {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000002',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: {} },
data: optimistic,
});
const error = new CombinedError({
networkError: new Error('offline'),
});
const { client } = harness(host);
vi.mocked(client.mutation).mockImplementation(
() =>
({
toPromise: () => Promise.resolve({ error }),
}) as never
);
await tick();
expect(host.rollbacks).toEqual(['1']);
});
it.each(['foreground', 'restored', 'unhandled replay'] as const)(
'preserves an already-sent rejection across the %s boundary',
async (path) => {
const variables = {
input: { draftId: 'draft-handle', subject: 'Reply' },
};
const rejection = new CombinedError({
graphQLErrors: [
{
message: 'Draft was sent elsewhere',
extensions: { code: 'DRAFT_ALREADY_SENT' },
},
],
});
const rollback = vi.spyOn(host, 'rollbackOptimisticWrite');
if (path !== 'foreground') {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000002',
query: stringifyDocument(SaveEmailDraftDocument),
operationName: 'SaveEmailDraft',
variables,
data: optimistic,
});
}
const { ops, client, forwarded } = harness(host, () => ({
error: rejection,
data: undefined,
}));
if (path === 'foreground') {
ops.next(
makeOperation(
'mutation',
createRequest(SaveEmailDraftDocument, variables),
makeMutationOp(1, optimistic).context
)
);
} else if (path === 'unhandled replay') {
// A reconstructed client may return an error without traversing
// writeThrough; the queue drain's fallback also preserves its code.
vi.mocked(client.mutation).mockReturnValue({
toPromise: async () => ({ error: rejection }),
} as never);
}
await tick();
expect(rollback).toHaveBeenCalledExactlyOnceWith(
path === 'foreground' ? '1' : '1',
expect.any(Object),
rejection.message,
'DRAFT_ALREADY_SENT'
);
expect(host.begins).toHaveLength(path === 'foreground' ? 1 : 0);
if (path === 'restored') {
expect(host.claims).toEqual(['1']);
expect(forwarded[0]?.variables).toEqual(variables);
expect(optimisticContextOf(forwarded[0])).toBeUndefined();
}
}
);
it('forwards optimistic mutations without cache work when the host is disabled', async () => {
const disabledHost: CacheHost = { ...host, disabled: true };
const { ops, forwarded } = harness(disabledHost);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.begins).toHaveLength(0);
expect(host.claims).toHaveLength(0);
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
});
it('acknowledges cache installation independently of the network result', async () => {
const acknowledge = vi.fn();
const enqueue = host.enqueueOptimisticMutation.bind(host);
let release!: () => void;
const installation = new Promise<void>((resolve) => {
release = resolve;
});
host.enqueueOptimisticMutation = vi.fn(async (args, claim) => {
await installation;
return enqueue(args, claim);
});
const { ops, forwarded, results, network } = controlledQueryHarness(host);
const operation = makeMutationOp(1, optimistic);
ops.next(
makeOperation('mutation', operation, {
...operation.context,
normalizedCacheOptimisticEnqueued: acknowledge,
})
);
await tick();
expect(acknowledge).not.toHaveBeenCalled();
expect(forwarded).toEqual([]);
release();
await tick();
expect(acknowledge).toHaveBeenCalledOnce();
expect(results).toEqual([]);
expect(forwarded).toHaveLength(1);
expect(
vi.mocked(host.enqueueOptimisticMutation).mock.calls[0][0]
).not.toHaveProperty('onEnqueued');
network.next({
operation: forwarded[0],
data: optimistic,
stale: false,
hasNext: false,
});
await tick();
expect(results).toHaveLength(1);
expect(acknowledge).toHaveBeenCalledOnce();
});
it('installs the optimistic layer before forwarding to the network', async () => {
const { ops, results, forwarded } = harness(host);
const enqueue = host.enqueueOptimisticMutation.bind(host);
host.enqueueOptimisticMutation = async (args, claim) => {
// The mutation must not have hit the network yet.
expect(forwarded).toHaveLength(0);
return enqueue(args, claim);
};
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.begins).toHaveLength(1);
expect(host.begins[0]?.data).toEqual(optimistic);
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
expect(results).toHaveLength(1);
expect(results[0]?.data).toEqual({ from: 'network' });
});
it('does not forward an admitted enqueue rejected by pagehide uncertainty', async () => {
host.enqueueOptimisticMutation = vi.fn().mockRejectedValue(
Object.assign(new Error('pagehide abruptly disposed the host'), {
errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
})
);
const { ops, results, forwarded } = harness(host);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(forwarded).toHaveLength(0);
expect(results).toHaveLength(1);
expect(results[0]?.error?.networkError).toMatchObject({
errorCode: 'admitted-enqueue-uncertain',
});
});
it('keeps a standby enqueue off the API while graceful disposal waits for its response', async () => {
const enqueue = host.enqueueOptimisticMutation.bind(host);
let releaseResponse!: () => void;
const responseGate = new Promise<void>((resolve) => {
releaseResponse = resolve;
});
host.enqueueOptimisticMutation = async (args, claim) => {
await responseGate;
return {
...(await enqueue(args, claim)),
initialClaim: { kind: 'not-runnable' },
};
};
const { ops, results, forwarded } = harness(host);
ops.next(makeMutationOp(1, optimistic));
await tick();
host.dispose();
expect(forwarded).toHaveLength(0);
expect(results).toHaveLength(0);
releaseResponse();
await tick();
expect(forwarded).toHaveLength(0);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: '1',
});
});
it('does not forward when graceful disposal sees transport failure while waiting', async () => {
let rejectResponse!: (error: Error) => void;
host.enqueueOptimisticMutation = vi.fn(
async () =>
await new Promise<EnqueueOptimisticMutationResult>(
(_resolve, reject) => {
rejectResponse = reject;
}
)
);
const { ops, results, forwarded } = harness(host);
ops.next(makeMutationOp(1, optimistic));
await tick();
host.dispose();
expect(forwarded).toHaveLength(0);
rejectResponse(
Object.assign(new Error('transport failed during graceful wait'), {
errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
})
);
await tick();
expect(forwarded).toHaveLength(0);
expect(results[0]?.error?.networkError).toMatchObject({
errorCode: 'admitted-enqueue-uncertain',
});
});
it('does not forward or retry an admitted enqueue after multi-tab transport uncertainty', async () => {
const oldScopeQueue: unknown[] = [];
const enqueueAttempts = vi.fn(
async (args: Parameters<CacheHost['enqueueOptimisticMutation']>[0]) => {
// A second tab could observe this durable side effect even though this
// tab lost the SharedWorker response immediately afterward.
oldScopeQueue.push(args.data);
throw Object.assign(new Error('old-scope transport failed'), {
errorCode: ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,
});
}
);
host.enqueueOptimisticMutation = enqueueAttempts;
const secondTabObservedQueue = (): unknown[] => [...oldScopeQueue];
const onCacheError = vi.fn();
const { ops, results, forwarded } = harness(host, undefined, {
onCacheError,
});
const base = makeMutationOp(1, optimistic);
const operation = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [
{
query: 'query CachedList { cachedList { id } }',
variablesJson: '{}',
path: [{ field: 'cachedList' }],
operation: { kind: 'remove', entityKey: 'Item:1' },
},
],
revalidations: [],
},
});
ops.next(operation);
await tick();
expect(secondTabObservedQueue()).toEqual([optimistic]);
expect(enqueueAttempts).toHaveBeenCalledOnce();
expect(forwarded).toHaveLength(0);
expect(results).toHaveLength(1);
expect(results[0]?.data).toBeUndefined();
expect(results[0]?.error?.networkError).toMatchObject({
message: 'old-scope transport failed',
errorCode: 'admitted-enqueue-uncertain',
});
expect(onCacheError).toHaveBeenCalledOnce();
});
it('replays an older returned claim and reports the new caller as queued', async () => {
host.seedQueued({
uuid: '00000000-0000-4000-8000-000000000003',
query: stringifyDocument(MUTATION),
operationName: 'SetEntityProperty',
variables: { input: { restored: true } },
data: optimistic,
});
const { ops, results, forwarded } = harness(host);
ops.next(makeMutationOp(2, optimistic));
await tick();
expect(host.claims[0]).toBe('1');
expect(forwarded[0]?.kind).toBe('mutation');
const liveResult = results.find((result) => result.operation.key === 2);
expect(liveResult).toBeDefined();
expect(optimisticMutationDispositionOf(liveResult!)).toEqual({
kind: 'queued',
transactionId: '2',
});
});
it('keeps the new mutation queued when the initial head is not runnable', async () => {
const enqueue = host.enqueueOptimisticMutation.bind(host);
host.enqueueOptimisticMutation = async (args, claim) => ({
...(await enqueue(args, claim)),
initialClaim: { kind: 'not-runnable' },
});
const { ops, results, forwarded } = harness(host);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.begins).toHaveLength(1);
expect(forwarded).toHaveLength(0);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: '1',
});
});
it('reports a nested initial claim failure without bypassing or duplicating enqueue', async () => {
const enqueue = host.enqueueOptimisticMutation.bind(host);
host.enqueueOptimisticMutation = async (args, claim) => ({
...(await enqueue(args, claim)),
initialClaim: { kind: 'failed', error: 'claim storage failed' },
});
const onCacheError = vi.fn();
const { ops, results, forwarded } = harness(host, undefined, {
onCacheError,
});
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.begins).toHaveLength(1);
expect(forwarded).toHaveLength(0);
expect(onCacheError).toHaveBeenCalledWith(
expect.objectContaining({ message: 'claim storage failed' }),
expect.objectContaining({ key: 1 })
);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: '1',
});
});
it('passes declarative link patches into the durable begin call', async () => {
const base = makeMutationOp(1, optimistic);
const patch = {
query: 'query Group { user { groupSoup { bins { items { id } } } } }',
operationName: 'Group',
variablesJson: '{}',
path: [
{ field: 'user' },
{ field: 'groupSoup' },
{ field: 'bins' },
{ field: 'items' },
],
operation: {
kind: 'remove' as const,
entityKey: 'GraphqlSoupItem:task-1',
},
};
const op = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [patch],
revalidations: [],
},
});
const { ops } = harness(host);
ops.next(op);
await tick();
expect(host.begins[0]?.linkPatches).toEqual([patch]);
});
it('falls back to property-only optimism when patched setup becomes stale', async () => {
const base = makeMutationOp(1, optimistic);
const op = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [
{
query:
'query Group { user { groupSoup { bins { items { id } } } } }',
operationName: 'Group',
variablesJson: '{}',
path: [
{ field: 'user' },
{ field: 'groupSoup' },
{ field: 'bins' },
],
operation: {
kind: 'remove',
entityKey: 'GraphqlSoupItem:task-1',
},
},
],
revalidations: [],
},
});
const enqueue = host.enqueueOptimisticMutation.bind(host);
host.enqueueOptimisticMutation = async (args, claim) => {
if (args.linkPatches?.length) throw new Error('stale bin');
return enqueue(args, claim);
};
const onCacheError = vi.fn();
const { ops } = harness(host, undefined, { onCacheError });
ops.next(op);
await tick();
expect(onCacheError).toHaveBeenCalledOnce();
expect(host.begins[0]?.linkPatches).toEqual([]);
expect(host.commits).toHaveLength(1);
});
it('sends a patched mutation directly while another context owns the database', async () => {
const base = makeMutationOp(1, optimistic);
const op = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [
{
query:
'query Group { user { groupSoup { bins { items { id } } } } }',
operationName: 'Group',
variablesJson: '{}',
path: [
{ field: 'user' },
{ field: 'groupSoup' },
{ field: 'bins' },
],
operation: {
kind: 'remove',
entityKey: 'GraphqlSoupItem:task-1',
},
},
],
revalidations: [],
},
});
host.enqueueOptimisticMutation = vi.fn().mockRejectedValue(
Object.assign(new Error('owner lock is held by another build'), {
errorCode: OWNER_LOCK_UNAVAILABLE_ERROR_CODE,
})
);
const warn = vi
.spyOn(console, 'warn')
.mockImplementation(() => undefined);
const onCacheError = vi.fn();
const { ops, results, forwarded } = harness(host, undefined, {
onCacheError,
});
try {
ops.next(op);
await tick();
// No link-patch degradation retry: the refusal says nothing about
// the patches, and nothing was admitted to a durable queue.
expect(host.enqueueOptimisticMutation).toHaveBeenCalledOnce();
expect(forwarded.map((forwardedOp) => forwardedOp.kind)).toEqual([
'mutation',
]);
expect(results[0]?.data).toEqual({ from: 'network' });
expect(onCacheError).not.toHaveBeenCalled();
expect(warn).not.toHaveBeenCalled();
} finally {
warn.mockRestore();
}
});
it('uses only explicit recovery queries when a record-rooted parent is missing', async () => {
const base = makeMutationOp(1, optimistic);
const recovery = {
query: 'query Target { user { id } }',
operationName: 'Target',
variablesJson: '{}',
};
const op = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse: optimistic,
linkPatches: [
{
query:
'fragment Parent on GraphqlSoupDocument { properties { id } }',
recordRoot: {
fragmentName: 'Parent',
entityKey: 'GraphqlSoupDocument:missing',
},
variablesJson: '{}',
path: [{ field: 'properties' }],
operation: {
kind: 'prependUnique',
entityKey: 'GraphqlProperty:temporary',
},
},
],
revalidations: [recovery],
},
});
const enqueue = host.enqueueOptimisticMutation.bind(host);
host.enqueueOptimisticMutation = vi.fn(async (args, claim) => {
if (args.linkPatches?.length) throw new Error('missing parent');
return enqueue(args, claim);
});
const { ops } = harness(host);
ops.next(op);
await tick();
expect(host.begins[0]?.linkPatches).toEqual([]);
expect(host.enqueueOptimisticMutation).toHaveBeenLastCalledWith(
expect.objectContaining({ linkPatches: [], revalidations: [recovery] }),
expect.anything()
);
expect(host.commits).toHaveLength(1);
});
it('bounds queued network attempts to one minute', async () => {
const timeoutSignal = new AbortController().signal;
const existing = new AbortController();
const timeout = vi
.spyOn(AbortSignal, 'timeout')
.mockReturnValue(timeoutSignal);
const operationFetch = vi.fn().mockResolvedValue(new Response());
try {
const mutation = makeMutationOp(1, optimistic);
const mutationWithFetch = makeOperation(mutation.kind, mutation, {
...mutation.context,
fetch: operationFetch,
} as never);
let fetched: Promise<Response> | undefined;
const { ops } = harness(host, (op) => {
if (op.kind === 'mutation') {
fetched = op.context.fetch?.('http://test', {
signal: existing.signal,
});
}
return {};
});
ops.next(mutationWithFetch);
await tick();
expect(timeout).toHaveBeenCalledWith(60_000);
const signal: AbortSignal = operationFetch.mock.calls[0]?.[1].signal;
expect(signal.aborted).toBe(false);
existing.abort('cancelled');
expect(signal.aborted).toBe(true);
expect(signal.reason).toBe('cancelled');
await fetched;
} finally {
timeout.mockRestore();
}
});
it('commits with the network result on success and never emits a synthetic result', async () => {
const { ops, results } = harness(host);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.commits).toHaveLength(1);
expect(host.commits[0]?.transactionId).toBe('1');
expect(host.commits[0]?.data).toEqual({ from: 'network' });
expect(host.rollbacks).toHaveLength(0);
// Only the real network result reaches the caller.
expect(results).toHaveLength(1);
expect(results[0]?.data).toEqual({ from: 'network' });
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'committed',
data: { from: 'network' },
});
// The optimistic path never uses the plain write-through.
expect(host.writes).toHaveLength(0);
});
it('does not expose a stale response when commit lands beneath a replacement', async () => {
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (transactionId, claim, args) => ({
...(await commit(transactionId, claim, args)),
kind: 'committed-superseded',
replacementTransactionId: '2',
});
const { ops, results } = harness(host);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.commits[0]?.data).toEqual({ from: 'network' });
expect(results[0]?.data).toBeUndefined();
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: '2',
});
});
it.each(['none', 'reported deletion', 'explicit effect'] as const)(
'fences postcommit effects across a reset during %s',
async (resetDuring) => {
const pending = deferred<void>();
if (resetDuring !== 'none') {
const remove = host.deleteRecords.bind(host);
vi.spyOn(host, 'deleteRecords').mockImplementationOnce(
async (...args) => {
const result = await remove(...args);
await pending.promise;
return result;
}
);
}
const deletion = {
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'document-1',
};
const update = {
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id: 'document-1',
displayName: 'Renamed',
},
};
const data = {
renameEntities: {
results: [
{
__typename: 'GraphqlMutationSuccess',
effects: [deletion, update],
},
],
},
};
const base = makeRenameMutationOp(10);
const operation = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse: {
renameEntities: { results: [] },
},
},
});
const { ops, results } = harness(
host,
(op) => (op.kind === 'mutation' ? { data } : {}),
resetDuring === 'reported deletion'
? { deletedRecordKeys: () => ['GraphqlSoupDocument:document-1'] }
: {}
);
ops.next(operation);
await tick();
expect(host.commits).toHaveLength(1);
if (resetDuring !== 'none') {
host.resetStorage();
pending.resolve();
await tick();
expect(host.cacheActions).toEqual([
{ kind: 'delete', value: ['GraphqlSoupDocument:document-1'] },
]);
expect(optimisticMutationDispositionOf(results[0])?.kind).toBe(
'committed'
);
return;
}
expect(host.cacheActions).toEqual([
{
kind: 'delete',
value: ['GraphqlSoupDocument:document-1'],
},
{
kind: 'write',
value: {
renameEntities: {
results: [
{
__typename: 'GraphqlMutationSuccess',
effects: [update],
},
],
},
},
},
]);
expect(results[0]?.data).toBe(data);
}
);
it('skips stale explicit effects and revalidations for a superseded commit', async () => {
const deletion = {
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'document-1',
};
const update = {
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id: 'document-1',
displayName: 'Stale rename',
},
};
const data = {
renameEntities: {
results: [
{
__typename: 'GraphqlMutationSuccess',
effects: [deletion, update],
},
],
},
};
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (transactionId, claim, args) => ({
...(await commit(transactionId, claim, args)),
kind: 'committed-superseded',
replacementTransactionId: '2',
revalidations: [
{
query: stringifyDocument(QUERY),
operationName: 'Soup',
variablesJson: '{"input":{"limit":2}}',
},
],
});
const base = makeRenameMutationOp(11);
const operation = makeOperation(base.kind, base, {
...base.context,
normalizedCacheOptimistic: {
uuid: crypto.randomUUID(),
optimisticResponse: { renameEntities: { results: [] } },
},
});
const { ops, results, client } = harness(host, (op) =>
op.kind === 'mutation' ? { data } : {}
);
ops.next(operation);
await tick();
expect(host.commits).toHaveLength(1);
expect(host.cacheActions).toEqual([]);
expect(vi.mocked(client.query)).not.toHaveBeenCalled();
expect(results[0]?.data).toBeUndefined();
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: '2',
});
});
it.each([false, true])(
'preserves a committed response when identity diagnostics are reported (callback throws=%s)',
async (callbackThrows) => {
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (transactionId, claim, args) => ({
...(await commit(transactionId, claim, args)),
identityErrors: ['missing identity response object'],
});
const onCacheError = vi.fn(() => {
if (callbackThrows) throw new Error('diagnostic failed');
});
const { ops, results, forwarded } = harness(host, undefined, {
onCacheError,
});
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(onCacheError).toHaveBeenCalledWith(
expect.objectContaining({
message: 'missing identity response object',
}),
expect.anything()
);
expect(host.commits).toHaveLength(1);
expect(host.rollbacks).toHaveLength(0);
expect(host.defers).toHaveLength(0);
expect(forwarded).toHaveLength(1);
expect(results[0]?.error).toBeUndefined();
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'committed',
data: results[0]?.data,
});
expect(results[0]?.data).toBeDefined();
}
);
it.each([
{ replacementTransactionId: undefined, callbackThrows: false },
{ replacementTransactionId: undefined, callbackThrows: true },
{ replacementTransactionId: '2', callbackThrows: false },
{ replacementTransactionId: '2', callbackThrows: true },
])(
'settles an identity failure without replaying the failed attempt (replacement $replacementTransactionId, callback throws=$callbackThrows)',
async ({ replacementTransactionId, callbackThrows }) => {
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (transactionId, claim, args) => ({
...(await commit(transactionId, claim, args)),
kind: 'failed',
error: 'missing identity response id',
replacementTransactionId,
revalidations: [
{
query: stringifyDocument(QUERY),
operationName: 'Soup',
variablesJson: '{"input":{"limit":2}}',
},
],
});
const onCacheError = vi.fn(() => {
if (callbackThrows) throw new Error('diagnostic failed');
});
const { ops, results, client, forwarded } = harness(host, undefined, {
onCacheError,
});
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(onCacheError).toHaveBeenCalledWith(
expect.objectContaining({ message: 'missing identity response id' }),
expect.anything()
);
expect(onCacheError).toHaveBeenCalledTimes(1);
expect(host.commits).toHaveLength(1);
expect(host.defers).toHaveLength(0);
expect(forwarded).toHaveLength(1);
expect(vi.mocked(client.query)).toHaveBeenCalledTimes(
replacementTransactionId ? 0 : 1
);
expect(results[0]?.data).toBeUndefined();
if (replacementTransactionId) {
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: replacementTransactionId,
});
} else {
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'permanently-failed',
error: expect.objectContaining({
message: expect.stringContaining('missing identity response id'),
}),
});
}
}
);
it('fires commit revalidations with network-only policy', async () => {
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (transactionId, claim, args) => ({
...(await commit(transactionId, claim, args)),
revalidations: [
{
query: stringifyDocument(QUERY),
operationName: 'Soup',
variablesJson: '{"input":{"limit":2}}',
},
],
});
const { ops, client } = harness(host);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(vi.mocked(client.query)).toHaveBeenCalledOnce();
expect(vi.mocked(client.query).mock.calls[0]?.[2]).toEqual({
requestPolicy: 'network-only',
});
});
it.each(['initial', 'continuation'] as const)(
'fences a contextless %s fallback shared by a later CRM observer',
async (mode) => {
const variables = {
input:
mode === 'initial'
? {
initial: {
filters: {
crmContactFilter: { literal: { hidden: false } },
},
},
}
: { continuation: { cursor: 'durable-opaque-page' } },
};
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (...args) => ({
...(await commit(...args)),
revalidations: [
{
query: stringifyDocument(SoupDocument),
operationName: 'Soup',
variablesJson: JSON.stringify(variables),
},
],
});
const requests: Array<ReturnType<typeof deferred<Response>>> = [];
const client = createClient({
url: 'http://test/graphql',
preferGetMethod: false,
exchanges: [
normalizedCacheExchange(host, {
externalWriteTypes: resolveCrmExternalWriteTypes,
}),
fetchExchange,
],
fetch: vi.fn(async (_input, init) => {
const body =
typeof init?.body === 'string' ? JSON.parse(init.body) : {};
if (body.query?.includes('mutation'))
return new Response(JSON.stringify({ data: optimistic }), {
headers: { 'content-type': 'application/json' },
});
const response = deferred<Response>();
requests.push(response);
return response.promise;
}),
});
await executeOptimisticMutation(
client,
MUTATION,
{ input: {} },
optimistic,
{
uuid: crypto.randomUUID(),
}
).toPromise();
await vi.waitFor(() => expect(requests).toHaveLength(1));
const results: OperationResult[] = [];
const subscription = client
.query(SoupDocument, variables, {
requestPolicy: 'network-only',
externalCacheWriteTypes: ['GraphqlSoupCrmContact'],
})
.subscribe((result) => results.push(result));
try {
await tick();
expect(requests).toHaveLength(1);
recordExternalWrite(host, ['GraphqlSoupCrmContact']);
const old = {
user: { id: 'viewer', soup: { items: [], nextCursor: null } },
};
requests[0].resolve(
new Response(JSON.stringify({ data: old }), {
headers: { 'content-type': 'application/json' },
})
);
await vi.waitFor(() => expect(requests).toHaveLength(2));
expect(results).toEqual([]);
expect(
host.writes.some(
(write) => JSON.stringify(write.data) === JSON.stringify(old)
)
).toBe(false);
const restored = {
user: {
id: 'viewer',
soup: {
items: [
{
__typename: 'GraphqlSoupCrmContact',
id: 'contact-1',
hidden: false,
},
],
nextCursor: null,
},
},
};
requests[1].resolve(
new Response(JSON.stringify({ data: restored }), {
headers: { 'content-type': 'application/json' },
})
);
await vi.waitFor(() =>
expect(results.at(-1)?.data).toEqual(restored)
);
} finally {
subscription.unsubscribe();
}
}
);
it.each(['query', 'persistence'] as const)(
'bounds conditional link recovery while %s is stalled without retrying a committed mutation',
async (stage) => {
vi.useFakeTimers();
const read = deferred<OperationResult>();
const persistence = deferred<undefined>();
try {
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (...args) => ({
...(await commit(...args)),
revalidations: [
{
query: stringifyDocument(QUERY),
operationName: 'Soup',
variablesJson: '{}',
onlyOnLinkFailure: true,
},
],
});
const onCacheError = vi.fn();
const { ops, client, results, forwarded } = harness(host, undefined, {
onCacheError,
});
vi.mocked(client.executeRequestOperation).mockReturnValue({
toPromise: () => read.promise,
} as never);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(0);
expect(host.commits).toHaveLength(1);
expect(client.query).not.toHaveBeenCalled();
expect(client.executeRequestOperation).toHaveBeenCalledOnce();
// urql drops a query whose key has a dispatch outstanding.
const [repair] = vi.mocked(client.executeRequestOperation).mock
.calls[0];
expect(repair.key).toBeLessThan(0);
expect(repair.key).not.toBe(createRequest(QUERY, {}).key);
if (stage === 'persistence') {
read.resolve({
...queryResult(makeOp(2, 'network-only')),
extensions: {
__macroNormalizedCache: {
source: 'live-network',
persistence: persistence.promise,
},
},
});
}
await vi.advanceTimersByTimeAsync(59_999);
expect(results).toHaveLength(0);
await vi.advanceTimersByTimeAsync(1);
expect(results).toHaveLength(1);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'committed',
data: results[0].data,
});
expect(onCacheError).toHaveBeenCalledWith(
expect.objectContaining({
message: 'Timed out delivering mutation updates',
}),
expect.anything()
);
expect(forwarded).toHaveLength(1);
expect(host.rollbacks).toHaveLength(0);
expect(host.defers).toHaveLength(0);
} finally {
read.resolve(queryResult(makeOp(2, 'network-only')));
persistence.resolve(undefined);
vi.useRealTimers();
}
}
);
it.each([true, false])(
'delegates persisted commit revalidations only when an owner accepts: %s',
async (handled) => {
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (transactionId, claim, args) => ({
...(await commit(transactionId, claim, args)),
revalidations: [
{
query: stringifyDocument(QUERY),
operationName: 'Soup',
variablesJson: '{"input":{"limit":2}}',
},
],
});
const delegateRevalidation = vi.fn(() => handled);
const { ops, client, results } = harness(host, undefined, {
delegateRevalidation,
});
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(delegateRevalidation).toHaveBeenCalledWith(client, {
document: expect.any(Object),
variables: { input: { limit: 2 } },
});
expect(vi.mocked(client.query)).toHaveBeenCalledTimes(handled ? 0 : 1);
expect(results[0]?.error).toBeUndefined();
expect(host.commits).toHaveLength(1);
}
);
it('preserves a committed mutation when delegated reconciliation fails', async () => {
const commit = host.commitOptimisticWrite.bind(host);
host.commitOptimisticWrite = async (transactionId, claim, args) => ({
...(await commit(transactionId, claim, args)),
revalidations: [
{
query: stringifyDocument(QUERY),
operationName: 'Soup',
variablesJson: '{}',
},
],
});
const error = new Error('refresh owner unavailable');
const onCacheError = vi.fn();
const { ops, results } = harness(host, undefined, {
delegateRevalidation: () => {
throw error;
},
onCacheError,
});
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(onCacheError).toHaveBeenCalledWith(error, expect.any(Object));
expect(results[0]?.error).toBeUndefined();
expect(host.commits).toHaveLength(1);
expect(host.rollbacks).toHaveLength(0);
});
it('rolls back on a GraphQL error result', async () => {
const error = new CombinedError({ graphQLErrors: ['nope'] });
const { ops, results } = harness(host, (op) =>
op.kind === 'mutation' ? { error } : {}
);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.rollbacks).toEqual(['1']);
expect(host.commits).toHaveLength(0);
expect(results[0]?.error).toBe(error);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'permanently-failed',
error,
});
});
it.each([
{
code: 'DRAFT_ALREADY_SENT',
network: false,
expected: 'DRAFT_ALREADY_SENT',
},
{ code: 'INTERNAL', network: false, expected: 'INTERNAL' },
{ code: 42, network: false, expected: undefined },
{ code: 'DRAFT_ALREADY_SENT', network: true, expected: undefined },
])(
'retains authoritative string error codes on background replay: %j',
async ({ code, network, expected }) => {
vi.useFakeTimers();
try {
const rejection = new CombinedError({
graphQLErrors: [
{ message: 'server rejection', extensions: { code } },
],
...(network ? { networkError: new Error('transport failed') } : {}),
});
const rollback = vi.spyOn(host, 'rollbackOptimisticWrite');
let attempts = 0;
const { ops } = harness(
host,
() => {
attempts += 1;
return {
error:
attempts === 1
? new CombinedError({ networkError: new Error('offline') })
: rejection,
data: undefined,
};
},
{ shouldRetryMutation: () => attempts === 1 }
);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(0);
expect(rollback).not.toHaveBeenCalled();
await vi.advanceTimersByTimeAsync(1_000);
expect(attempts).toBe(2);
expect(rollback).toHaveBeenCalledExactlyOnceWith(
'1',
expect.any(Object),
rejection.message,
expected
);
} finally {
vi.useRealTimers();
}
}
);
it('keeps the disposition queued when permanent settlement is uncertain', async () => {
const error = new CombinedError({ graphQLErrors: ['nope'] });
host.rollbackOptimisticWrite = async () => {
throw new Error('lost rollback response');
};
const { ops, results } = harness(host, (op) =>
op.kind === 'mutation' ? { error, data: undefined } : {}
);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: '1',
});
});
it('rolls back on a network error result', async () => {
const error = new CombinedError({
networkError: new Error('offline'),
});
const { ops } = harness(host, (op) =>
op.kind === 'mutation' ? { error, data: undefined } : {}
);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(host.rollbacks).toEqual(['1']);
expect(host.commits).toHaveLength(0);
});
it('retains a retryable network failure as a successful local write', async () => {
const error = new CombinedError({
networkError: new Error('offline'),
});
const shouldRetryMutation = vi.fn(() => true);
const { ops, results } = harness(
host,
(op) => (op.kind === 'mutation' ? { error, data: undefined } : {}),
{ shouldRetryMutation }
);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(shouldRetryMutation).toHaveBeenCalledWith(error);
expect(host.defers).toEqual([
{ transactionId: '1', error: error.message },
]);
expect(host.rollbacks).toHaveLength(0);
expect(results[0]?.error).toBeUndefined();
expect(results[0]?.data).toEqual(optimistic);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'queued',
transactionId: '1',
});
});
it.each([
{ status: 500, data: null, failures: 0 },
{ status: 503, data: { from: 'server' }, failures: 0 },
{ status: 500, data: null, failures: 9 },
{ status: 503, data: { from: 'server' }, failures: 9 },
])(
'handles HTTP $status without GraphQL errors after $failures server failures',
async ({ status, data, failures }) => {
vi.useFakeTimers();
try {
if (failures > 0) {
host.seedQueued(
{
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
data: optimistic,
},
failures
);
}
const response = new Response(JSON.stringify({ data }), {
status,
headers: { 'content-type': 'application/json' },
});
const shouldRetryMutation = vi.fn(shouldRetryGraphqlMutation);
const rollback = vi.spyOn(host, 'rollbackOptimisticWrite');
const defer = vi.spyOn(host, 'deferOptimisticWrite');
const client = createClient({
url: 'http://test/graphql',
fetch: vi.fn(async () => response),
exchanges: [
normalizedCacheExchange(host, { shouldRetryMutation }),
fetchExchange,
],
});
const pending =
failures === 0
? executeOptimisticMutation(
client,
MUTATION,
{ input: {} },
optimistic,
{ uuid: crypto.randomUUID() }
).toPromise()
: undefined;
await vi.advanceTimersByTimeAsync(10);
expect(shouldRetryMutation).toHaveBeenCalledExactlyOnceWith(
expect.objectContaining({ response, graphQLErrors: [] })
);
expect(host.commits).toHaveLength(0);
if (failures === 0) {
expect(defer).toHaveBeenCalledExactlyOnceWith(
'1',
expect.any(Object),
expect.any(Number),
expect.stringContaining(String(status)),
true
);
expect(host.rollbacks).toHaveLength(0);
expect(optimisticMutationDispositionOf((await pending)!)).toEqual({
kind: 'queued',
transactionId: '1',
});
} else {
expect(host.defers).toHaveLength(0);
expect(rollback).toHaveBeenCalledExactlyOnceWith(
'1',
expect.any(Object),
expect.stringContaining('10 server failures'),
'MUTATION_RETRY_EXHAUSTED'
);
}
} finally {
vi.clearAllTimers();
vi.useRealTimers();
}
}
);
it.each([false, true])(
'preserves success and explicit GraphQL rejection with fetchExchange (rejected=%s)',
async (rejected) => {
vi.useFakeTimers();
try {
const response = new Response(
JSON.stringify(
rejected
? {
errors: [
{ message: 'rejected', extensions: { code: 'INVALID' } },
],
}
: { data: optimistic }
),
{
status: rejected ? 503 : 200,
headers: { 'content-type': 'application/json' },
}
);
const client = createClient({
url: 'http://test/graphql',
fetch: vi.fn(async () => response),
exchanges: [
normalizedCacheExchange(host, {
shouldRetryMutation: shouldRetryGraphqlMutation,
}),
fetchExchange,
],
});
const pending = executeOptimisticMutation(
client,
MUTATION,
{ input: {} },
optimistic,
{ uuid: crypto.randomUUID() }
).toPromise();
await vi.advanceTimersByTimeAsync(10);
const result = await pending;
expect(host.defers).toHaveLength(0);
expect(optimisticMutationDispositionOf(result)?.kind).toBe(
rejected ? 'permanently-failed' : 'committed'
);
if (rejected) {
expect(result.error?.graphQLErrors[0]?.extensions.code).toBe(
'INVALID'
);
expect(result.error?.response).toBe(response);
}
} finally {
vi.clearAllTimers();
vi.useRealTimers();
}
}
);
it.each(['graphql', 'http-500', 'http-503'])(
'permanently fails the tenth %s failure and advances the queue',
async (kind) => {
vi.useFakeTimers();
try {
const error =
kind === 'graphql'
? new CombinedError({
graphQLErrors: [
{
message: 'persistent failure',
extensions: { retryable: true },
},
],
})
: new CombinedError({
networkError: new Error('server unavailable'),
response: new Response(null, {
status: kind === 'http-500' ? 500 : 503,
}),
});
const rollback = vi.spyOn(host, 'rollbackOptimisticWrite');
let attempts = 0;
const { ops, results, forwarded } = harness(
host,
() =>
++attempts <= 10
? { error, data: undefined }
: { data: optimistic },
{ shouldRetryMutation: () => true }
);
ops.next(makeMutationOp(1, optimistic));
ops.next(makeMutationOp(2, optimistic));
await vi.advanceTimersByTimeAsync(0);
for (let attempt = 1; attempt < 10; attempt += 1) {
expect(forwarded).toHaveLength(attempt);
expect(host.rollbacks).toHaveLength(0);
await vi.advanceTimersByTimeAsync(
Math.min(1_000 * 2 ** (attempt - 1), 60_000)
);
}
await vi.advanceTimersByTimeAsync(1);
expect(host.defers).toHaveLength(9);
expect(rollback).toHaveBeenCalledExactlyOnceWith(
'1',
expect.any(Object),
expect.stringContaining('10 server failures'),
'MUTATION_RETRY_EXHAUSTED'
);
expect(host.commits.map((entry) => entry.transactionId)).toEqual([
'2',
]);
expect(forwarded).toHaveLength(11);
expect(
results.some(
(result) =>
optimisticMutationDispositionOf(result)?.kind ===
'permanently-failed'
)
).toBe(true);
} finally {
vi.clearAllTimers();
vi.useRealTimers();
}
}
);
it('network failures neither consume nor reset the server failure budget', async () => {
vi.useFakeTimers();
try {
const server = new CombinedError({
graphQLErrors: [
{ message: 'server failed', extensions: { retryable: true } },
],
});
const network = new CombinedError({
networkError: new DOMException('request timed out', 'TimeoutError'),
});
let attempts = 0;
const { ops } = harness(
host,
() => {
attempts += 1;
// Transport failures before the first server error cannot consume
// the budget; transport failures after nine cannot reset it either.
return {
error:
(attempts >= 13 && attempts <= 21) || attempts === 34
? server
: network,
data: undefined,
};
},
{ shouldRetryMutation: () => true }
);
ops.next(makeMutationOp(1, optimistic));
await vi.advanceTimersByTimeAsync(0);
for (let attempt = 1; attempt < 34; attempt += 1) {
expect(host.rollbacks).toHaveLength(0);
await vi.advanceTimersByTimeAsync(
Math.min(1_000 * 2 ** (attempt - 1), 60_000)
);
}
expect(attempts).toBe(34);
expect(host.defers).toHaveLength(33);
expect(host.rollbacks).toEqual(['1']);
} finally {
vi.clearAllTimers();
vi.useRealTimers();
}
});
it('uses the persisted budget on replay, records exhaustion and revalidates', async () => {
host.seedQueued(
{
uuid: crypto.randomUUID(),
query: stringifyDocument(MUTATION),
data: optimistic,
revalidations: [
{ query: stringifyDocument(QUERY), variablesJson: '{}' },
],
},
9
);
const rollback = vi.spyOn(host, 'rollbackOptimisticWrite');
const onMutationAttemptResult = vi.fn(async () => {});
const error = new CombinedError({
graphQLErrors: [
{ message: 'still failing', extensions: { retryable: true } },
],
});
const { client } = harness(host, () => ({ error, data: undefined }), {
shouldRetryMutation: () => true,
onMutationAttemptResult,
});
await tick();
expect(host.defers).toHaveLength(0);
expect(rollback).toHaveBeenCalledExactlyOnceWith(
'1',
expect.any(Object),
expect.stringContaining('10 server failures'),
'MUTATION_RETRY_EXHAUSTED'
);
expect(onMutationAttemptResult).toHaveBeenCalledExactlyOnceWith(
expect.objectContaining({
transactionId: '1',
serverFailureCount: 9,
}),
expect.objectContaining({
error: expect.objectContaining({
graphQLErrors: [
expect.objectContaining({
extensions: { code: 'MUTATION_RETRY_EXHAUSTED' },
}),
],
}),
}),
false
);
expect(client.query).toHaveBeenCalledOnce();
});
it('requires explicit retry after a draft application failure and preserves its handles', async () => {
vi.useFakeTimers();
try {
const variables = {
input: {
draftId: 'draft-handle',
threadDbId: 'thread-handle',
subject: 'Saved',
},
};
const saved = {
saveEmailDraft: {
draftId: 'server-draft',
draft: {
__typename: 'GraphqlSoupEmailMessage',
id: 'server-draft',
},
thread: {
__typename: 'GraphqlSoupEmailThread',
id: 'server-thread',
},
},
};
const error = new CombinedError({
graphQLErrors: [
{
message: 'attachment loading failed after commit',
extensions: { code: 'INTERNAL', retryable: true },
},
],
});
let attempts = 0;
const { ops, results, forwarded } = harness(
host,
() => {
attempts += 1;
return attempts === 1
? { error, data: undefined }
: { data: saved };
},
{ shouldRetryMutation: shouldRetryGraphqlMutation }
);
ops.next(
makeOperation(
'mutation',
createRequest(SaveEmailDraftDocument, variables),
makeMutationOp(1, saved).context
)
);
await vi.advanceTimersByTimeAsync(0);
expect(attempts).toBe(1);
expect(host.rollbacks).toEqual(['1']);
expect(host.defers).toHaveLength(0);
expect(results[0]?.error).toBe(error);
expect(optimisticMutationDispositionOf(results[0])).toEqual({
kind: 'permanently-failed',
error,
});
await vi.advanceTimersByTimeAsync(1_000);
expect(attempts).toBe(1);
ops.next(
makeOperation(
'mutation',
createRequest(SaveEmailDraftDocument, variables),
makeMutationOp(2, saved).context
)
);
await vi.advanceTimersByTimeAsync(0);
expect(attempts).toBe(2);
expect(forwarded.map((op) => op.variables)).toEqual([
variables,
variables,
]);
expect(host.begins).toHaveLength(2);
expect(host.commits).toEqual([
expect.objectContaining({
transactionId: '2',
data: saved,
}),
]);
expect(host.rollbacks).toEqual(['1']);
} finally {
vi.useRealTimers();
}
});
it('accepts later local writes while a deferred offline head blocks the network', async () => {
const error = new CombinedError({
networkError: new Error('offline'),
});
const firstOptimistic = {
setEntityProperty: { id: 'prop-1', displayName: 'Doing' },
};
const secondOptimistic = {
setEntityProperty: { id: 'prop-1', displayName: 'Completed' },
};
const { ops, results, forwarded } = harness(
host,
(op) => (op.kind === 'mutation' ? { error, data: undefined } : {}),
{ shouldRetryMutation: () => true }
);
ops.next(makeMutationOp(1, firstOptimistic));
await tick();
ops.next(makeMutationOp(2, secondOptimistic));
await tick();
expect(host.claims).toEqual(['1']);
expect(forwarded.map((op) => op.key)).toEqual([1]);
expect(host.begins.map((begin) => begin.data)).toEqual([
firstOptimistic,
secondOptimistic,
]);
expect(results).toHaveLength(2);
expect(results[0]?.error).toBeUndefined();
expect(results[1]?.error).toBeUndefined();
expect(results[0]?.data).toEqual(firstOptimistic);
expect(results[1]?.data).toEqual(secondOptimistic);
expect(optimisticMutationDispositionOf(results[1])).toEqual({
kind: 'queued',
transactionId: '2',
});
});
it('forwards queued optimistic mutations strictly in enqueue order', async () => {
const { ops, forwarded } = harness(host);
ops.next(makeMutationOp(1, optimistic));
ops.next(makeMutationOp(2, optimistic));
await tick();
expect(host.claims).toEqual(['1', '2']);
// The second caller was released as queued while the first attempt was
// in flight, so its eventual send is reconstructed from durable data.
expect(forwarded).toHaveLength(2);
expect(forwarded[0]?.key).toBe(1);
expect(forwarded[1]?.kind).toBe('mutation');
expect(host.commits.map((entry) => entry.transactionId)).toEqual([
'1',
'2',
]);
});
it('writes non-optimistic mutation responses through the standard path', async () => {
const { ops, results, forwarded } = harness(host);
ops.next(makeMutationOp(1));
await tick();
expect(host.begins).toHaveLength(0);
expect(host.commits).toHaveLength(0);
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
expect(host.writes).toHaveLength(1);
expect(host.writes[0]?.data).toEqual({ from: 'network' });
expect(results).toHaveLength(1);
});
it('normalizes update-only mutation effects without inferring deletions from inputs', async () => {
const data = {
renameEntities: {
results: [
{
__typename: 'GraphqlMutationSuccess',
effects: [
{
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id: 'document-1',
displayName: 'Renamed',
},
},
],
},
],
},
};
const { ops } = harness(host, () => ({ data }));
ops.next(makeRenameMutationOp(9));
await tick();
expect(host.writes.map((write) => write.data)).toEqual([data]);
expect(host.invalidations).toHaveLength(0);
});
it('applies aliased nested mutation effects in order with ancestor typenames', async () => {
const deleteDocument = (id: string) => ({
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: id,
});
const updateDocument = (id: string) => ({
__typename: 'SoupUpdated',
current: {
__typename: 'GraphqlSoupDocument',
id,
displayName: `Document ${id}`,
},
});
const patches = [
deleteDocument('delete-then-update'),
updateDocument('delete-then-update'),
updateDocument('update-then-delete'),
deleteDocument('update-then-delete'),
];
const data = {
renamed: {
__typename: 'EntityMutationPayload',
outcomes: [
{
__typename: 'GraphqlMutationSuccess',
patches,
},
],
},
};
const { ops, results } = harness(host, () => ({ data }));
ops.next(makeRenameMutationOp(9, true));
await tick();
const wrappedWrite = (patch: unknown) => ({
renamed: {
__typename: 'EntityMutationPayload',
outcomes: [
{
__typename: 'GraphqlMutationSuccess',
patches: [patch],
},
],
},
});
expect(host.cacheActions).toEqual([
{
kind: 'delete',
value: ['GraphqlSoupDocument:delete-then-update'],
},
{ kind: 'write', value: wrappedWrite(patches[1]) },
{ kind: 'write', value: wrappedWrite(patches[2]) },
{
kind: 'delete',
value: ['GraphqlSoupDocument:update-then-delete'],
},
]);
expect(results[0]?.data).toBe(data);
});
it('reports every mutation cache failure, continues effects, and returns the original result', async () => {
const writeFailure = new Error('cache write failed');
const deleteFailure = new Error('cache deletion failed');
vi.spyOn(host, 'writeQuery').mockRejectedValueOnce(writeFailure);
vi.spyOn(host, 'deleteRecords').mockRejectedValueOnce(deleteFailure);
const onCacheError = vi.fn();
const patches = [
{
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id: 'document-1',
displayName: 'One',
},
},
{
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'document-2',
},
{
__typename: 'SoupUpdated',
item: {
__typename: 'GraphqlSoupDocument',
id: 'document-3',
displayName: 'Three',
},
},
{
__typename: 'GraphqlCacheDeletion',
graphqlTypeName: 'GraphqlSoupDocument',
entityId: 'document-4',
},
];
const data = {
renameEntities: {
results: [
{
__typename: 'GraphqlMutationSuccess',
effects: patches,
},
],
},
};
const { ops, results } = harness(host, () => ({ data }), {
onCacheError,
});
const op = makeRenameMutationOp(9);
ops.next(op);
await tick();
expect(onCacheError.mock.calls).toEqual([
[writeFailure, op],
[deleteFailure, op],
]);
expect(host.writes).toHaveLength(1);
expect(host.invalidations).toEqual([['GraphqlSoupDocument:document-4']]);
expect(results[0]?.data).toBe(data);
});
it('degrades to a plain network mutation when the optimistic setup fails', async () => {
host.enqueueOptimisticMutation = async () => {
throw new Error('idb exploded');
};
const onCacheError = vi.fn();
const client = { reexecuteOperation: vi.fn() } as unknown as Client;
const ops = makeSubject<Operation>();
const results: OperationResult[] = [];
const forwarded: Operation[] = [];
const forward = (ops$: Source<Operation>): Source<OperationResult> =>
pipe(
ops$,
map((op) => {
forwarded.push(op);
return {
operation: op,
data: { from: 'network' },
error: undefined,
extensions: undefined,
stale: false,
hasNext: false,
};
})
);
pipe(
normalizedCacheExchange(host, { onCacheError })({
forward,
client,
dispatchDebug: () => undefined,
})(ops.source),
subscribe((r) => results.push(r))
);
ops.next(makeMutationOp(1, optimistic));
await tick();
expect(onCacheError).toHaveBeenCalledOnce();
expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);
expect(results[0]?.data).toEqual({ from: 'network' });
// No transaction was installed → nothing to commit or roll back, and
// the response still write-throughs as a plain mutation.
expect(host.commits).toHaveLength(0);
expect(host.rollbacks).toHaveLength(0);
expect(host.writes).toHaveLength(1);
});
});
});