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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import type {
CacheRequest,
CacheResponseErrorCode,
WorkerMessage,
WriteResult,
} from '../protocol';
import { INITIAL_CACHE_REVISION } from '../protocol';
import type {
CacheCoordinatorPageAdapter,
CacheCoordinatorPageAdapterOptions,
PageAdapterDisposeOptions,
} from '../worker/coordinator-page-adapter';
const adapterFactory = vi.hoisted(() => vi.fn());
vi.mock('../worker/coordinator-page-adapter', () => ({
createCacheCoordinatorPageAdapter: adapterFactory,
}));
import {
CACHE_COORDINATOR_PROTOCOL_VERSION,
type EngineOpenOutcome,
} from '../worker/coordinator-protocol';
import {
CacheBootstrapExhaustedError,
COORDINATOR_CONNECT_TIMEOUT_MS,
} from '../worker/startup';
import { CacheNavigationError } from './navigation-error';
import { createWorkerCacheHost } from './worker-host';
const CLIENT_ID = '00000000-0000-4000-8000-000000000007';
const STORAGE_GENERATION = '00000000-0000-7000-8000-000000000001';
const EMPTY_WRITE: WriteResult = {
revision: INITIAL_CACHE_REVISION,
revisionAdvanced: false,
changed: [],
affectedOps: [],
reset: false,
};
function responseFor(request: CacheRequest): unknown {
switch (request.kind) {
case 'current-revision':
return INITIAL_CACHE_REVISION;
case 'current-storage-generation':
return STORAGE_GENERATION;
case 'read':
return { kind: 'miss' };
case 'read-records-by-keys':
return { revision: INITIAL_CACHE_REVISION, records: [] };
case 'search':
return { documents: [], nextCursor: null };
case 'hydrate':
return {
kind: 'data',
data: { cursor: 'next' },
revision: INITIAL_CACHE_REVISION,
};
case 'write':
case 'commit-optimistic-write':
case 'rollback-optimistic-write':
return EMPTY_WRITE;
case 'enqueue-optimistic-mutation':
return {
...EMPTY_WRITE,
transactionId: '1',
initialClaim: { kind: 'not-runnable' },
};
case 'inspect-mutations':
case 'inspect-query':
case 'inspect-query-variants':
return [];
case 'claim-next-mutation':
return undefined;
case 'invalidate':
case 'delete-records':
return { revision: INITIAL_CACHE_REVISION, affectedOps: request.keys };
case 'init':
case 'defer-optimistic-write':
case 'teardown':
return null;
case 'clear':
return INITIAL_CACHE_REVISION;
}
}
class FakePageAdapter {
onmessage: ((event: MessageEvent<WorkerMessage>) => void) | null = null;
readonly requests: CacheRequest[] = [];
readonly start = vi.fn(async (): Promise<void> => {});
readonly ignoredKinds = new Set<CacheRequest['kind']>();
readonly errors = new Map<CacheRequest['kind'], string>();
readonly dispose = vi.fn(
async (_options: PageAdapterDisposeOptions = {}): Promise<void> => {}
);
constructor(readonly options: CacheCoordinatorPageAdapterOptions) {}
postMessage(request: CacheRequest): void {
this.requests.push(request);
if (this.ignoredKinds.has(request.kind)) return;
const error = this.errors.get(request.kind);
queueMicrotask(() => {
if (error === undefined) this.respond(request.id, responseFor(request));
else this.reject(request.id, error);
});
}
respond(id: number, result: unknown): void {
this.emit({ id, ok: true, result });
}
reject(id: number, error: string, errorCode?: CacheResponseErrorCode): void {
this.emit({
id,
ok: false,
error,
...(errorCode === undefined ? {} : { errorCode }),
});
}
push(message: WorkerMessage | unknown): void {
this.emit(message as WorkerMessage);
}
replace(
ownerEpoch: number,
openOutcome: EngineOpenOutcome = 'opened-existing'
): void {
this.options.onEngineReplaced?.(ownerEpoch, openOutcome);
}
protocolError(error: Error): void {
this.options.onProtocolError?.(error);
}
terminalError(error: Error): void {
this.options.onTerminalError?.(error);
}
unavailable(reason: string): void {
this.options.onCacheUnavailable?.(reason);
}
superseded(reason: string): void {
this.options.onCacheSuperseded?.(reason);
}
private emit(message: WorkerMessage): void {
this.onmessage?.({ data: message } as MessageEvent<WorkerMessage>);
}
}
let lastAdapter: FakePageAdapter | undefined;
let configureAdapter: (adapter: FakePageAdapter) => void;
let sharedWorkerConstructor: ReturnType<typeof vi.fn>;
let dedicatedWorkerConstructor: ReturnType<typeof vi.fn>;
let indexedDbDelete: ReturnType<typeof vi.fn>;
function stubSupportedBrowser(): void {
sharedWorkerConstructor = vi.fn();
dedicatedWorkerConstructor = vi.fn();
vi.stubGlobal('SharedWorker', sharedWorkerConstructor);
vi.stubGlobal('Worker', dedicatedWorkerConstructor);
vi.stubGlobal('MessageChannel', vi.fn());
indexedDbDelete = vi.fn(() => ({
onblocked: null,
onerror: null,
onsuccess: null,
}));
vi.stubGlobal('indexedDB', { deleteDatabase: indexedDbDelete });
vi.stubGlobal('navigator', {
locks: {
request: vi.fn(
async (
name: string,
_options: LockOptions,
callback: (lock: Lock | null) => unknown
) => await callback({ name, mode: 'exclusive' } as Lock)
),
},
storage: { getDirectory: vi.fn() },
});
}
function requireAdapter(): FakePageAdapter {
if (!lastAdapter) throw new Error('page adapter was not constructed');
return lastAdapter;
}
describe('createWorkerCacheHost', () => {
beforeEach(() => {
localStorage.clear();
stubSupportedBrowser();
vi.spyOn(crypto, 'randomUUID').mockReturnValue(CLIENT_ID);
lastAdapter = undefined;
configureAdapter = () => undefined;
adapterFactory.mockReset();
adapterFactory.mockImplementation(
(options: CacheCoordinatorPageAdapterOptions) => {
const fake = new FakePageAdapter(options);
configureAdapter(fake);
lastAdapter = fake;
return fake as unknown as CacheCoordinatorPageAdapter;
}
);
});
afterEach(() => {
vi.useRealTimers();
vi.unstubAllGlobals();
vi.restoreAllMocks();
});
it('uses a storage-free no-op host when a required capability is unavailable', async () => {
vi.stubGlobal('SharedWorker', undefined);
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
const host = createWorkerCacheHost({ scope: 'scope-1' });
expect(warn).toHaveBeenCalledWith(
'[graphql-cache] disabled: SharedWorker is not supported by this browser'
);
expect(adapterFactory).not.toHaveBeenCalled();
expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();
expect(indexedDbDelete).not.toHaveBeenCalled();
expect(host.disabled).toBe(true);
await expect(host.readQuery({ query: '{ x }' })).resolves.toEqual({
kind: 'miss',
});
await expect(
host.writeQuery({ query: '{ x }', data: { x: 1 } })
).resolves.toEqual(EMPTY_WRITE);
});
it("refuses a scope whose database would read as another scope's WAL file", () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
const host = createWorkerCacheHost({ scope: 'scope-1-wal' });
expect(warn).toHaveBeenCalledWith(
'[graphql-cache] disabled: cache scope must not end with -wal'
);
expect(adapterFactory).not.toHaveBeenCalled();
expect(host.disabled).toBe(true);
});
it('routes hydration through the payload-projecting RPC', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await expect(
host.hydrateQuery({
query: 'query Backfill { items @cacheOnly { id } cursor }',
data: { items: [{ id: '1' }], cursor: 'next' },
identity: 'user-1',
})
).resolves.toEqual({
kind: 'data',
data: { cursor: 'next' },
revision: INITIAL_CACHE_REVISION,
});
expect(requireAdapter().requests).toContainEqual(
expect.objectContaining({
kind: 'hydrate',
query: 'query Backfill { items @cacheOnly { id } cursor }',
data: { items: [{ id: '1' }], cursor: 'next' },
identity: 'user-1',
})
);
});
it('reads the durable generation through initialization without requiring a reset notification', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await expect(host.currentStorageGeneration()).resolves.toBe(
STORAGE_GENERATION
);
expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
'init',
'current-storage-generation',
]);
host.dispose();
});
it('notifies generation subscribers only when a live cache change resets storage', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.currentStorageGeneration();
const changed = vi.fn();
const unsubscribe = host.onCacheGenerationChanged(changed);
requireAdapter().push({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
});
expect(changed).not.toHaveBeenCalled();
requireAdapter().push({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
reset: true,
});
expect(changed).toHaveBeenCalledExactlyOnceWith({ storage: 'reset' });
unsubscribe();
requireAdapter().push({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
reset: true,
});
expect(changed).toHaveBeenCalledOnce();
host.dispose();
});
it('uses the no-op host when OPFS is unavailable', () => {
vi.stubGlobal('navigator', {
locks: { request: vi.fn() },
storage: {},
});
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
const host = createWorkerCacheHost({ scope: 'scope-1' });
expect(host.disabled).toBe(true);
expect(warn).toHaveBeenCalledWith(
'[graphql-cache] disabled: OPFS is not supported by this browser'
);
expect(adapterFactory).not.toHaveBeenCalled();
});
it('does not false-gate worker-only sync access handle capability', async () => {
vi.stubGlobal('FileSystemFileHandle', undefined);
vi.stubGlobal('FileSystemSyncAccessHandle', undefined);
configureAdapter = (fake) => {
fake.errors.set('init', 'sync access handles unavailable in engine');
};
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
expect(host.disabled).not.toBe(true);
await expect(host.clear()).rejects.toThrow(
'sync access handles unavailable in engine'
);
expect(adapterFactory).toHaveBeenCalledOnce();
expect(onInitializationError).toHaveBeenCalledOnce();
});
it('treats teardown as local cleanup after initialization failure and disposal', async () => {
configureAdapter = (fake) => {
fake.errors.set('init', 'injected initialization failure');
};
const host = createWorkerCacheHost({ scope: 'scope-1' });
await expect(host.clear()).rejects.toThrow(
'injected initialization failure'
);
host.dispose();
await expect(host.teardown(7)).resolves.toBeUndefined();
expect(
requireAdapter().requests.filter((request) => request.kind === 'teardown')
).toEqual([]);
});
it('samples origin storage pressure periodically and clears the timer on dispose', async () => {
vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
const estimate = vi.fn(async () => ({ usage: 25, quota: 100 }));
vi.stubGlobal('navigator', {
...(navigator as unknown as Record<string, unknown>),
storage: {
getDirectory: vi.fn(),
estimate,
persisted: vi.fn(async () => true),
},
});
const observations: Array<Record<string, unknown>> = [];
const host = createWorkerCacheHost({
scope: 'scope-1',
storageHealthIntervalMs: 1_000,
telemetry: {
record: (observation) => observations.push(observation),
flush: vi.fn(),
},
});
await host.readQuery({ query: 'query Ready { value }' });
await Promise.resolve();
expect(estimate).toHaveBeenCalledOnce();
await vi.advanceTimersByTimeAsync(2_000);
expect(estimate).toHaveBeenCalledTimes(3);
host.dispose();
await vi.advanceTimersByTimeAsync(2_000);
expect(estimate).toHaveBeenCalledTimes(3);
expect(
observations.filter(
(observation) =>
observation.name === 'graphql_cache.origin_storage_pressure'
)
).toHaveLength(3);
});
it('constructs the coordinator adapter and starts cutover cleanup lazily on first RPC', async () => {
const host = createWorkerCacheHost({ scope: 'lazy-scope' });
host.onOpsAffected(() => undefined);
expect(adapterFactory).not.toHaveBeenCalled();
expect(sharedWorkerConstructor).not.toHaveBeenCalled();
expect(dedicatedWorkerConstructor).not.toHaveBeenCalled();
expect(indexedDbDelete).not.toHaveBeenCalled();
const read = host.readQuery({ query: '{ x }' });
expect(adapterFactory).toHaveBeenCalledOnce();
await vi.waitFor(() => expect(indexedDbDelete).toHaveBeenCalledOnce());
expect(indexedDbDelete).toHaveBeenCalledWith('graphql-cache:lazy-scope');
expect(adapterFactory).toHaveBeenCalledWith(
expect.objectContaining({ scope: 'lazy-scope' })
);
await expect(read).resolves.toEqual({ kind: 'miss' });
await host.clear();
expect(requireAdapter().requests.map((request) => request.kind)).toEqual([
'init',
'read',
'clear',
]);
expect(indexedDbDelete).toHaveBeenCalledOnce();
host.dispose();
});
it('preserves the complete CacheHost RPC surface, request ids, and call order', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1', hotCapacity: 42 });
const claim = { owner: 'runner', generation: 'generation-1' };
const results = await Promise.all([
host.readQuery({
opKey: 7,
query: 'query Read { user { id } }',
priority: 'user-visible',
entityResolvers: [
{
parentType: 'GraphqlUser',
fieldName: 'emailThread',
targetType: 'GraphqlSoupEmailThread',
argumentPath: ['input', 'threadId'],
},
],
}),
host.readRecordsByKeys({
document: 'fragment Item on GraphqlSoupDocument { id }',
fragmentName: 'Item',
keys: ['GraphqlSoupDocument:item-1'],
}),
host.search({
profile: 'quick-access-v1',
buckets: ['document'],
query: 'plan',
limit: 20,
nowMs: 123,
}),
host.writeQuery({
opKey: 8,
registerDependencies: true,
query: 'query Read { user { id } }',
data: { user: { id: 'user-1' } },
identity: 'user-1',
entityResolvers: [
{
parentType: 'GraphqlUser',
fieldName: 'emailThread',
targetType: 'GraphqlSoupEmailThread',
argumentPath: ['input', 'threadId'],
},
],
}),
host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000005',
opKey: 9,
query: 'mutation Rename { rename { id } }',
data: { rename: { id: 'doc-1' } },
},
{ owner: 'runner', nowMs: 100, leaseExpiresAtMs: 1_100 }
),
host.inspectQueryVariants({
query: 'query Views { views }',
path: [{ field: 'views' }],
}),
host.inspectQuery({
query: 'query Views { views }',
path: [{ field: 'views' }],
variableFilters: [{ input: { limit: 20 } }],
}),
host.claimNextMutation('runner', 200, 1_200),
host.deferOptimisticWrite('1', claim, 2_000, 'offline'),
host.commitOptimisticWrite('1', claim, {
query: 'mutation Rename { rename { id } }',
data: { rename: { id: 'doc-1' } },
}),
host.rollbackOptimisticWrite('2', claim, 'denied', 'DRAFT_ALREADY_SENT'),
host.invalidate(['User:1']),
host.deleteRecords(['Document:1']),
host.teardown(7),
host.clear(),
]);
const requests = requireAdapter().requests;
expect(
requests.find((request) => request.kind === 'rollback-optimistic-write')
).toMatchObject({ errorCode: 'DRAFT_ALREADY_SENT', error: 'denied' });
expect(requests.map(({ id, kind }) => [id, kind])).toEqual([
[1, 'init'],
[2, 'read'],
[3, 'read-records-by-keys'],
[4, 'search'],
[5, 'write'],
[6, 'enqueue-optimistic-mutation'],
[7, 'inspect-query-variants'],
[8, 'inspect-query'],
[9, 'claim-next-mutation'],
[10, 'defer-optimistic-write'],
[11, 'commit-optimistic-write'],
[12, 'rollback-optimistic-write'],
[13, 'invalidate'],
[14, 'delete-records'],
[15, 'teardown'],
[16, 'clear'],
]);
expect(requests[0]).toEqual({
id: 1,
kind: 'init',
scope: 'scope-1',
hotCapacity: 42,
});
expect(requests[1]).toEqual(
expect.objectContaining({
opId: `${CLIENT_ID}:7`,
priority: 'user-visible',
entityResolvers: [
expect.objectContaining({
parentType: 'GraphqlUser',
fieldName: 'emailThread',
}),
],
})
);
expect(requests[3]).toEqual({
id: 4,
kind: 'search',
request: {
profile: 'quick-access-v1',
buckets: ['document'],
query: 'plan',
limit: 20,
nowMs: 123,
},
});
expect(requests[5]).toEqual(
expect.objectContaining({
uuid: '00000000-0000-4000-8000-000000000005',
})
);
expect(requests[4]).toEqual(
expect.objectContaining({
originOpId: `${CLIENT_ID}:8`,
registration: {
opId: `${CLIENT_ID}:8`,
entityResolvers: [
expect.objectContaining({
parentType: 'GraphqlUser',
fieldName: 'emailThread',
}),
],
},
})
);
expect(requests[5]).toEqual(
expect.objectContaining({
originOpId: `${CLIENT_ID}:9`,
owner: 'runner',
createdAtMs: 100,
nowMs: 100,
leaseExpiresAtMs: 1_100,
})
);
expect(requests[14]).toEqual({
id: 15,
kind: 'teardown',
opId: `${CLIENT_ID}:7`,
});
expect(results[0]).toEqual({ kind: 'miss' });
expect(results[2]).toEqual({ documents: [], nextCursor: null });
expect(results[4]).toEqual(expect.objectContaining({ transactionId: '1' }));
host.dispose();
});
it('follows coordinator phase deadlines instead of applying the read timeout to startup', async () => {
vi.useFakeTimers();
configureAdapter = (fake) => {
fake.ignoredKinds.add('init');
fake.ignoredKinds.add('read');
};
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 10,
onInitializationError,
});
const read = host.readQuery({ query: '{ user }' });
const rejected = expect(read).rejects.toThrow('cache worker timeout: read');
await vi.advanceTimersByTimeAsync(0);
const adapter = requireAdapter();
const progress = (
ownerEpoch: number,
phase: 'loading-assets' | 'opening-database',
timeoutMs: number
) =>
adapter.options.onStartupProgress?.({
coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
kind: 'engine-startup',
ownerEpoch,
databaseAction: 'open-existing',
phase,
timeoutMs,
});
progress(1, 'loading-assets', 60_000);
await vi.advanceTimersByTimeAsync(30_000);
expect(onInitializationError).not.toHaveBeenCalled();
progress(1, 'opening-database', 20_000);
await vi.advanceTimersByTimeAsync(20_001);
// The coordinator retries before the page's grace expires.
progress(2, 'loading-assets', 60_000);
await vi.advanceTimersByTimeAsync(30_000);
expect(onInitializationError).not.toHaveBeenCalled();
adapter.respond(1, null);
await vi.advanceTimersByTimeAsync(11);
await rejected;
expect(onInitializationError).not.toHaveBeenCalled();
host.dispose();
});
it('retries a transient coordinator registration failure without disabling or quarantining the cache', async () => {
let attempt = 0;
let first: FakePageAdapter | undefined;
configureAdapter = (fake) => {
if (attempt++ !== 0) return;
first = fake;
fake.start.mockImplementation(async () => {
const error = new Error('SharedWorker load failed');
fake.terminalError(error);
throw error;
});
};
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
await expect(host.readQuery({ query: '{ user }' })).resolves.toEqual({
kind: 'miss',
});
expect(adapterFactory).toHaveBeenCalledTimes(2);
expect(first?.dispose).toHaveBeenCalledWith({ graceful: false });
expect(first?.requests).toEqual([]);
expect(onInitializationError).not.toHaveBeenCalled();
host.dispose();
});
it('bounds hung coordinator registration retries and reports terminal failure only once', async () => {
vi.useFakeTimers();
configureAdapter = (fake) =>
fake.start.mockImplementation(() => new Promise(() => {}));
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const rejected = expect(host.currentRevision()).rejects.toThrow(
'cache worker timeout: registration'
);
await vi.advanceTimersByTimeAsync(
COORDINATOR_CONNECT_TIMEOUT_MS * 3 + 100 + 200 + 1
);
await rejected;
expect(adapterFactory).toHaveBeenCalledTimes(3);
expect(onInitializationError).toHaveBeenCalledOnce();
expect(requireAdapter().requests).toEqual([]);
expect(vi.getTimerCount()).toBe(0);
});
it('cancels coordinator registration on disposal without retrying or reporting failure', async () => {
vi.useFakeTimers();
configureAdapter = (fake) =>
fake.start.mockImplementation(() => new Promise(() => {}));
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const rejected = expect(host.currentRevision()).rejects.toThrow(
'disposed during startup'
);
host.dispose();
await rejected;
expect(adapterFactory).toHaveBeenCalledOnce();
expect(onInitializationError).not.toHaveBeenCalled();
expect(vi.getTimerCount()).toBe(0);
});
it.each([
['open-existing', true],
['open-existing', false],
['wipe-before-open', false],
] as const)(
'requires coordinator proof to preserve a failed startup scope (%s, proof: %s)',
async (databaseAction, provenUntouched) => {
configureAdapter = (fake) => fake.ignoredKinds.add('init');
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const rejected = expect(host.currentRevision()).rejects.toThrow(
'bootstrap attempts exhausted'
);
const adapter = requireAdapter();
await vi.waitFor(() => expect(adapter.requests).toHaveLength(1));
adapter.options.onStartupProgress?.({
coordinatorVersion: CACHE_COORDINATOR_PROTOCOL_VERSION,
kind: 'engine-startup',
ownerEpoch: 1,
phase: 'loading-assets',
databaseAction,
timeoutMs: 60_000,
});
adapter.terminalError(
provenUntouched
? new CacheBootstrapExhaustedError('bootstrap attempts exhausted')
: new Error('bootstrap attempts exhausted')
);
await rejected;
await vi.waitFor(() =>
expect(onInitializationError).toHaveBeenCalledOnce()
);
expect(localStorage.getItem('graphql-cache:scope')).toBe(
provenUntouched ? 'scope-1' : 'quarantine:scope-1'
);
}
);
it.each([false, true])(
'pauses initialization during a blocked handoff without failing writes (replacement: %s)',
async (replacement) => {
vi.useFakeTimers();
configureAdapter = (fake) => fake.ignoredKinds.add('init');
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
initializationTimeoutMs: 10,
onInitializationError,
});
const read = host.readQuery({ opKey: 7, query: 'query Read { user }' });
const rejected = expect(read).rejects.toThrow('owner handoff timeout');
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
await vi.advanceTimersByTimeAsync(0);
const adapter = requireAdapter();
adapter.options.onCacheReadAvailabilityChanged?.('blocked');
await rejected;
await vi.advanceTimersByTimeAsync(60_001);
expect(adapter.requests.map(({ kind }) => kind)).toEqual(['init']);
expect(onInitializationError).not.toHaveBeenCalled();
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
if (replacement) adapter.replace(2);
else adapter.options.onCacheReadAvailabilityChanged?.('ready');
adapter.respond(1, null);
await mutation;
expect(adapter.requests.map(({ kind }) => kind)).toEqual([
'init',
'enqueue-optimistic-mutation',
]);
await expect(
host.readQuery({ query: 'query Recovered { user }' })
).resolves.toEqual({ kind: 'miss' });
host.dispose();
}
);
it('queues parked reads, writes, and teardown in call order without background timeouts', async () => {
vi.useFakeTimers();
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 10,
});
await host.currentRevision();
const adapter = requireAdapter();
adapter.ignoredKinds.add('read');
adapter.ignoredKinds.add('write');
adapter.ignoredKinds.add('teardown');
adapter.options.onCacheReadAvailabilityChanged?.('waiting');
const read = host.readQuery({ opKey: 7, query: 'query Parked { user }' });
const write = host.writeQuery({
query: 'query Parked { user }',
data: { user: true },
});
const teardown = host.teardown(7);
await vi.advanceTimersByTimeAsync(300_001);
const queued = adapter.requests.filter((request) =>
['read', 'write', 'teardown'].includes(request.kind)
);
expect(queued.map((request) => request.kind)).toEqual([
'read',
'write',
'teardown',
]);
adapter.options.onCacheReadAvailabilityChanged?.('ready');
for (const request of queued)
adapter.respond(request.id, responseFor(request));
await Promise.all([read, write, teardown]);
host.dispose();
});
it('keeps an initially parked host initializing without failing reads or writes', async () => {
vi.useFakeTimers();
configureAdapter = (fake) => fake.ignoredKinds.add('init');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
initializationTimeoutMs: 10,
onInitializationError,
});
const read = host.readQuery({ query: 'query Initial { user }' });
const write = host.writeQuery({
query: 'query Initial { user }',
data: { user: true },
});
await vi.advanceTimersByTimeAsync(0);
const adapter = requireAdapter();
adapter.options.onCacheReadAvailabilityChanged?.('waiting');
await vi.advanceTimersByTimeAsync(300_001);
expect(adapter.requests.map((request) => request.kind)).toEqual(['init']);
expect(onInitializationError).not.toHaveBeenCalled();
adapter.options.onCacheReadAvailabilityChanged?.('ready');
adapter.respond(1, null);
await Promise.all([read, write]);
expect(adapter.requests.map((request) => request.kind)).toEqual([
'init',
'read',
'write',
]);
host.dispose();
});
it('bounds hung registration/init before admitting reads or mutations', async () => {
vi.useFakeTimers();
configureAdapter = (fake) => fake.ignoredKinds.add('init');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 100,
initializationTimeoutMs: 10,
onInitializationError,
});
const read = host.readQuery({ opKey: 4, query: 'query Read { user }' });
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const readRejected = expect(read).rejects.toThrow(
'cache worker timeout: init'
);
const mutationRejected = expect(mutation).rejects.toThrow(
'cache worker timeout: init'
);
await vi.advanceTimersByTimeAsync(11);
await Promise.all([readRejected, mutationRejected]);
const adapter = requireAdapter();
expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
[1, 'init'],
]);
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
expect(onInitializationError).toHaveBeenCalledOnce();
expect(vi.getTimerCount()).toBe(0);
});
it.each(['current-revision', 'inspect-mutations'] as const)(
'times out a hung %s request',
async (kind) => {
vi.useFakeTimers();
configureAdapter = (fake) => fake.ignoredKinds.add(kind);
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 10,
});
const revision =
kind === 'inspect-mutations'
? host.inspectMutations!()
: host.currentRevision();
const revisionRejected = expect(revision).rejects.toThrow(
`cache worker timeout: ${kind}`
);
await vi.advanceTimersByTimeAsync(11);
await revisionRejected;
expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
'init',
kind,
]);
host.dispose();
expect(vi.getTimerCount()).toBe(0);
}
);
it('recovers typed initial epoch loss with fresh init handshakes only', async () => {
configureAdapter = (fake) => fake.ignoredKinds.add('init');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const affected: number[][] = [];
host.onOpsAffected((keys) => affected.push(keys));
const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const readRejected = expect(read).rejects.toMatchObject({
message: 'owner epoch 1 was lost',
errorCode: 'owner-epoch-lost',
});
const mutationRejected = expect(mutation).rejects.toMatchObject({
message: 'owner epoch 1 was lost',
errorCode: 'owner-epoch-lost',
});
const adapter = requireAdapter();
await vi.waitFor(() => expect(adapter.requests).toHaveLength(1));
adapter.reject(1, 'owner epoch 1 was lost', 'owner-epoch-lost');
await Promise.all([readRejected, mutationRejected]);
adapter.replace(2);
expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
[1, 'init'],
[2, 'init'],
]);
expect(affected).toEqual([]);
adapter.reject(2, 'owner epoch 2 was lost', 'owner-epoch-lost');
await Promise.resolve();
adapter.replace(3);
expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
[1, 'init'],
[2, 'init'],
[3, 'init'],
]);
expect(affected).toEqual([]);
adapter.respond(3, null);
await vi.waitFor(() =>
expect(
adapter.requests.filter(({ kind }) => kind === 'init')
).toHaveLength(3)
);
expect(affected).toEqual([]);
expect(
adapter.requests.filter(
(request) =>
request.kind === 'read' ||
request.kind === 'enqueue-optimistic-mutation'
)
).toEqual([]);
expect(onInitializationError).not.toHaveBeenCalled();
host.dispose();
});
it('suppresses replacement notification while an original init is queued', async () => {
configureAdapter = (fake) => fake.ignoredKinds.add('init');
const host = createWorkerCacheHost({ scope: 'scope-1' });
const affected: number[][] = [];
host.onOpsAffected((keys) => affected.push(keys));
const read = host.readQuery({ opKey: 5, query: 'query Read { user }' });
const adapter = requireAdapter();
await vi.waitFor(() => expect(adapter.requests).toHaveLength(1));
adapter.replace(2);
adapter.respond(1, null);
await expect(read).resolves.toEqual({ kind: 'miss' });
expect(affected).toEqual([]);
expect(adapter.requests.map(({ id, kind }) => [id, kind])).toEqual([
[1, 'init'],
[2, 'read'],
]);
host.dispose();
});
it('times out read-only RPC without timing out or replaying mutations', async () => {
vi.useFakeTimers();
configureAdapter = (fake) => {
fake.ignoredKinds.add('read');
fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 10,
});
const read = host.readQuery({ query: 'query Read { user { id } }' });
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000006',
query: 'mutation Rename { rename { id } }',
data: { rename: { id: 'doc-1' } },
},
{ owner: 'runner', nowMs: 123, leaseExpiresAtMs: 1_123 }
);
const readResult = expect(read).rejects.toThrow(
'cache worker timeout: read'
);
let mutationSettled = false;
void mutation.then(
() => {
mutationSettled = true;
},
() => {
mutationSettled = true;
}
);
await vi.advanceTimersByTimeAsync(11);
await readResult;
expect(mutationSettled).toBe(false);
const adapter = requireAdapter();
expect(
adapter.requests.filter(
(request) => request.kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1);
const mutationRequest = adapter.requests.find(
(request) => request.kind === 'enqueue-optimistic-mutation'
);
adapter.respond(mutationRequest?.id as number, {
...EMPTY_WRITE,
transactionId: '1',
initialClaim: { kind: 'not-runnable' },
});
await expect(mutation).resolves.toEqual(
expect.objectContaining({ transactionId: '1' })
);
expect(
adapter.requests.filter(
(request) => request.kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1);
host.dispose();
});
it('rejects old-epoch requests and never replays reads or durable mutations', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('read');
fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
const host = createWorkerCacheHost({ scope: 'scope-1' });
const affected: number[][] = [];
host.onOpsAffected((keys) => affected.push(keys));
await host.clear();
const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const readRejected = expect(read).rejects.toThrow('owner epoch 1 was lost');
const mutationRejected = expect(mutation).rejects.toThrow(
'owner epoch 1 was lost'
);
const adapter = requireAdapter();
await vi.waitFor(() =>
expect(
adapter.requests.filter(
(request) =>
request.kind === 'read' ||
request.kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(2)
);
const oldEpochRequests = adapter.requests.filter(
(request) =>
request.kind === 'read' ||
request.kind === 'enqueue-optimistic-mutation'
);
for (const request of oldEpochRequests) {
adapter.reject(request.id, 'owner epoch 1 was lost', 'owner-epoch-lost');
}
await Promise.all([readRejected, mutationRejected]);
adapter.replace(2);
await vi.waitFor(() =>
expect(
adapter.requests.filter(({ kind }) => kind === 'init')
).toHaveLength(2)
);
expect(affected).toEqual([]);
expect(
adapter.requests.filter((request) => request.kind === 'init')
).toHaveLength(2);
expect(
adapter.requests.filter(
(request) =>
request.kind === 'read' ||
request.kind === 'enqueue-optimistic-mutation'
)
).toEqual(oldEpochRequests);
host.dispose();
});
it('notifies a successfully registered key whose old-epoch reread was rejected', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const affected: number[][] = [];
host.onOpsAffected((keys) => affected.push(keys));
await host.clear();
await Promise.all([
host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),
host.readQuery({ opKey: 9, query: 'query Nine { nine }' }),
]);
const adapter = requireAdapter();
adapter.ignoredKinds.add('read');
const reread = host.readQuery({
opKey: 7,
query: 'query SlowSeven { seven }',
});
await vi.waitFor(() =>
expect(
adapter.requests.filter(
(request) =>
request.kind === 'read' && request.query.includes('SlowSeven')
)
).toHaveLength(1)
);
const request = adapter.requests.find(
(candidate) =>
candidate.kind === 'read' && candidate.query.includes('SlowSeven')
);
adapter.reject(
request?.id as number,
'owner epoch 1 was lost',
'owner-epoch-lost'
);
await expect(reread).rejects.toMatchObject({
errorCode: 'owner-epoch-lost',
});
adapter.replace(2);
await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));
expect(
adapter.requests.filter(
(candidate) =>
candidate.kind === 'read' && candidate.query.includes('SlowSeven')
)
).toHaveLength(1);
host.dispose();
});
it('notifies only registered active operations and deduplicates replacement epochs', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const affected: number[][] = [];
const unsubscribe = host.onOpsAffected((keys) => affected.push(keys));
await host.clear();
await Promise.all([
host.readQuery({ opKey: 7, query: 'query Seven { seven }' }),
host.writeQuery({
opKey: 9,
registerDependencies: true,
query: 'query Nine { nine }',
data: { nine: 9 },
}),
host.readQuery({ query: 'query Untracked { untracked }' }),
]);
const adapter = requireAdapter();
adapter.replace(2);
await vi.waitFor(() => expect(affected).toEqual([[7, 9]]));
await host.teardown(7);
await host.readQuery({ opKey: 9, query: 'query NineAgain { nine }' });
adapter.replace(2);
adapter.replace(1);
adapter.replace(3);
adapter.replace(3);
await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9]]));
await Promise.all([
host.readQuery({ opKey: 9, query: 'query NineThird { nine }' }),
host.readQuery({ opKey: 7, query: 'query SevenAgain { seven }' }),
]);
adapter.replace(4);
await vi.waitFor(() => expect(affected).toEqual([[7, 9], [9], [9, 7]]));
unsubscribe();
expect(affected).toEqual([[7, 9], [9], [9, 7]]);
host.dispose();
});
it.each([
['opened-existing', 'preserved'],
['opened-new', 'reset'],
['reset-incompatible', 'reset'],
['reset-corrupt', 'reset'],
['reset-storage-uncertain', 'reset'],
] as const)(
'invalidates engine dependencies but reports %s storage as %s',
async (openOutcome, storage) => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const generations = vi.fn();
const affected = vi.fn();
const unsubscribe = host.onCacheGenerationChanged(generations);
host.onOpsAffected(affected);
await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
const adapter = requireAdapter();
adapter.replace(2, openOutcome);
await vi.waitFor(() => expect(affected).toHaveBeenCalledWith([7]));
expect(generations).toHaveBeenCalledExactlyOnceWith({ storage });
expect(adapter.requests.filter((r) => r.kind === 'init')).toHaveLength(2);
adapter.replace(2, 'reset-corrupt');
adapter.replace(1, 'reset-corrupt');
expect(generations).toHaveBeenCalledOnce();
unsubscribe();
adapter.replace(3, openOutcome);
expect(generations).toHaveBeenCalledOnce();
host.dispose();
}
);
it.each(
[[], ['note'], ['channel', 'dm']].map((searchChangedBuckets) => ({
searchChangedBuckets,
}))
)(
'forwards hydration search metadata $searchChangedBuckets',
async ({ searchChangedBuckets }) => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const listener = vi.fn();
host.onCacheChanged(listener, { includeHydration: true });
await host.currentRevision();
requireAdapter().push({
kind: 'cache-hydrated',
revision: INITIAL_CACHE_REVISION,
searchChangedBuckets,
});
expect(listener).toHaveBeenCalledWith(INITIAL_CACHE_REVISION, {
searchChangedBuckets,
});
host.dispose();
}
);
it.each(
[[], ['note']].map((searchChangedBuckets) => ({ searchChangedBuckets }))
)(
'forwards query-write metadata and ignores it on reset: $searchChangedBuckets',
async ({ searchChangedBuckets }) => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const listener = vi.fn();
host.onCacheChanged(listener);
await host.currentRevision();
requireAdapter().push({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
searchChangedBuckets,
});
expect(listener).toHaveBeenLastCalledWith(INITIAL_CACHE_REVISION, {
searchChangedBuckets,
});
requireAdapter().push({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
searchChangedBuckets,
reset: true,
});
expect(listener).toHaveBeenLastCalledWith(INITIAL_CACHE_REVISION);
host.dispose();
}
);
it('delivers hydration only to opted-in subscribers and cleans them up', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const foreground = vi.fn();
const quickAccess = vi.fn();
const operations = vi.fn();
host.onCacheChanged(foreground);
host.onOpsAffected(operations);
const unsubscribe = host.onCacheChanged(quickAccess, {
includeHydration: true,
});
await host.currentRevision();
const adapter = requireAdapter();
adapter.push({ kind: 'cache-hydrated', revision: INITIAL_CACHE_REVISION });
expect(quickAccess).toHaveBeenCalledOnce();
expect(foreground).not.toHaveBeenCalled();
expect(operations).not.toHaveBeenCalled();
adapter.push({ kind: 'cache-changed', revision: INITIAL_CACHE_REVISION });
expect(quickAccess).toHaveBeenCalledTimes(2);
expect(foreground).toHaveBeenCalledOnce();
unsubscribe();
adapter.push({ kind: 'cache-hydrated', revision: INITIAL_CACHE_REVISION });
expect(quickAccess).toHaveBeenCalledTimes(2);
host.onCacheChanged(quickAccess, { includeHydration: true });
host.dispose();
adapter.push({ kind: 'cache-hydrated', revision: INITIAL_CACHE_REVISION });
expect(quickAccess).toHaveBeenCalledTimes(2);
});
it('strictly filters pushes to the exact client operation prefix', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const affected: number[][] = [];
const cacheChanges = vi.fn();
const settlements: unknown[] = [];
host.onOpsAffected((keys) => affected.push(keys));
host.onCacheChanged(cacheChanges);
host.onMutationSettled((settlement) => settlements.push(settlement));
await host.clear();
const adapter = requireAdapter();
adapter.push({
kind: 'ops-affected',
opIds: [
`${CLIENT_ID}:7`,
`${CLIENT_ID}:7`,
`foreign:${CLIENT_ID}:8`,
`${CLIENT_ID}0:9`,
`${CLIENT_ID}:1e3`,
`${CLIENT_ID}:0x10`,
`${CLIENT_ID}:NaN`,
`${CLIENT_ID}:9007199254740992`,
`${CLIENT_ID}:007`,
`${CLIENT_ID}:-0`,
`${CLIENT_ID}:not-a-number`,
`${CLIENT_ID}:`,
`${CLIENT_ID}:12`,
],
keys: ['User:1'],
});
adapter.push({ kind: 'ops-affected', opIds: [7], keys: [] });
adapter.push({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
});
adapter.push({
kind: 'mutation-settled',
settlement: { transactionId: '3', status: 'committed' },
});
expect(affected).toEqual([[7, 12]]);
expect(cacheChanges).toHaveBeenCalledOnce();
expect(settlements).toEqual([{ transactionId: '3', status: 'committed' }]);
host.dispose();
});
it('reports initialization failure once, settles callers, and closes transport', async () => {
vi.useFakeTimers();
configureAdapter = (fake) => {
fake.errors.set('init', 'OPFS initialization failed');
};
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 10,
onInitializationError,
});
const read = host.readQuery({ query: 'query Read { user }' });
const write = host.writeQuery({
query: 'query Read { user }',
data: { user: null },
});
const readRejected = expect(read).rejects.toThrow(
'OPFS initialization failed'
);
const writeRejected = expect(write).rejects.toThrow(
'OPFS initialization failed'
);
await vi.runAllTimersAsync();
await Promise.all([readRejected, writeRejected]);
const adapter = requireAdapter();
adapter.protocolError(new Error('late coordinator error'));
adapter.reject(1, 'late initialization response');
expect(onInitializationError).toHaveBeenCalledOnce();
expect(onInitializationError).toHaveBeenCalledWith(
expect.objectContaining({ message: 'OPFS initialization failed' })
);
expect(adapter.dispose).toHaveBeenCalledOnce();
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
expect(vi.getTimerCount()).toBe(0);
host.dispose();
expect(adapter.dispose).toHaveBeenCalledOnce();
});
it('terminal transport failure quarantines scope and rejects admitted mutations once', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const affected = vi.fn();
host.onOpsAffected(affected);
await host.clear();
const adapter = requireAdapter();
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const transportError = new Error('coordinator MessagePort messageerror');
const mutationRejected = expect(mutation).rejects.toMatchObject({
message: expect.stringContaining('coordinator MessagePort messageerror'),
errorCode: 'admitted-enqueue-uncertain',
cause: transportError,
});
await vi.waitFor(() =>
expect(
adapter.requests.filter(
(request) => request.kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1)
);
adapter.terminalError(transportError);
await mutationRejected;
adapter.terminalError(new Error('duplicate terminal callback'));
adapter.replace(2);
expect(onInitializationError).toHaveBeenCalledOnce();
expect(adapter.dispose).toHaveBeenCalledOnce();
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
expect(localStorage.getItem('graphql-cache:scope')).toBe(
'quarantine:scope-1'
);
expect(affected).not.toHaveBeenCalled();
expect(
adapter.requests.filter(
(request) => request.kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1);
await expect(host.clear()).rejects.toThrow(
'coordinator MessagePort messageerror'
);
});
it('stops using the cache without quarantine when another context holds the database', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('init');
};
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const read = host.readQuery({ query: 'query Q { q }' });
const unavailable = expect(read).rejects.toMatchObject({
errorCode: 'owner-lock-unavailable',
});
await vi.waitFor(() =>
expect(requireAdapter().requests.map(({ kind }) => kind)).toContain(
'init'
)
);
const adapter = requireAdapter();
adapter.unavailable('cache database owner lock is held by another context');
await unavailable;
expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(
expect.objectContaining({ errorCode: 'owner-lock-unavailable' })
);
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
// Storage was never touched, so the scope stays reusable next load.
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
await expect(
host.readQuery({ query: 'query Q { q }' })
).rejects.toMatchObject({ errorCode: 'owner-lock-unavailable' });
adapter.unavailable('duplicate notice');
expect(onInitializationError).toHaveBeenCalledOnce();
});
it('retires a ready host once a request is refused because the database is unavailable', async () => {
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
await host.clear();
const adapter = requireAdapter();
adapter.ignoredKinds.add('read');
const read = host.readQuery({ query: 'query Q { q }' });
await vi.waitFor(() => expect(adapter.requests.at(-1)?.kind).toBe('read'));
adapter.reject(
adapter.requests.at(-1)?.id ?? -1,
'cache database owner lock is held by another context',
'owner-lock-unavailable'
);
await expect(read).rejects.toMatchObject({
errorCode: 'owner-lock-unavailable',
});
expect(onInitializationError).toHaveBeenCalledOnce();
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: false });
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
});
it('retires quietly and asks the app to reload when a newer build takes over', async () => {
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const onSuperseded = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
onSuperseded,
});
await host.clear();
const adapter = requireAdapter();
adapter.superseded('a newer version of the app took over the local cache');
adapter.superseded('duplicate notice');
expect(onSuperseded).toHaveBeenCalledOnce();
expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(
expect.objectContaining({ errorCode: 'owner-lock-unavailable' })
);
// Leaving like a navigating page stops the engine without counting as a
// lost owner, so the newer build opens the same database.
expect(adapter.dispose).toHaveBeenCalledWith({
graceful: false,
preserveDatabase: true,
});
// The newer build opens the same database, so the scope is kept.
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
await expect(
host.readQuery({ query: 'query Q { q }' })
).rejects.toMatchObject({ errorCode: 'owner-lock-unavailable' });
});
it('reports an enqueue in flight at the handover as uncertain, never unsent', async () => {
localStorage.setItem('graphql-cache:scope', 'scope-1');
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.clear();
const adapter = requireAdapter();
adapter.ignoredKinds.add('enqueue-optimistic-mutation');
adapter.ignoredKinds.add('read');
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000101',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const read = host.readQuery({ query: 'query Q { q }' });
// The newer build replays the queued row, so the page must not send the
// mutation itself; the read never touched durable state.
const mutationRejected = expect(mutation).rejects.toMatchObject({
errorCode: 'admitted-enqueue-uncertain',
});
const readRejected = expect(read).rejects.toMatchObject({
errorCode: 'owner-lock-unavailable',
});
await vi.waitFor(() =>
expect(adapter.requests.map(({ kind }) => kind)).toEqual(
expect.arrayContaining(['enqueue-optimistic-mutation', 'read'])
)
);
adapter.superseded('a newer version of the app took over the local cache');
await mutationRejected;
await readRejected;
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
});
it('quarantines transport scope before invoking the product failure callback', async () => {
let runLock!: () => Promise<void>;
vi.stubGlobal('navigator', {
locks: {
request: vi.fn(
<T>(
_name: string,
_options: LockOptions,
callback: (lock: Lock | null) => T | PromiseLike<T>
) =>
new Promise<T>((resolve, reject) => {
runLock = async () => {
try {
resolve(
await callback({
name: 'graphql-cache:scope-storage',
mode: 'exclusive',
} as Lock)
);
} catch (error) {
reject(error);
}
};
})
),
},
storage: { getDirectory: vi.fn() },
});
localStorage.setItem('graphql-cache:scope', 'scope-1');
const callbackScopes: Array<string | null> = [];
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError: () => {
callbackScopes.push(localStorage.getItem('graphql-cache:scope'));
},
});
await host.clear();
requireAdapter().terminalError(new Error('transport failed'));
expect(callbackScopes).toEqual([]);
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
await runLock();
await vi.waitFor(() =>
expect(callbackScopes).toEqual(['quarantine:scope-1'])
);
});
it('converges same-scope failures and ignores stale or disposed host quarantine', async () => {
const adapters: FakePageAdapter[] = [];
adapterFactory.mockImplementation(
(adapterOptions: CacheCoordinatorPageAdapterOptions) => {
const fake = new FakePageAdapter(adapterOptions);
adapters.push(fake);
return fake as unknown as CacheCoordinatorPageAdapter;
}
);
localStorage.setItem('graphql-cache:scope', 'shared-old');
const firstError = vi.fn();
const secondError = vi.fn();
const first = createWorkerCacheHost({
scope: 'shared-old',
onInitializationError: firstError,
});
const second = createWorkerCacheHost({
scope: 'shared-old',
onInitializationError: secondError,
});
await Promise.all([first.clear(), second.clear()]);
adapters[0]?.terminalError(new Error('first tab transport failed'));
expect(localStorage.getItem('graphql-cache:scope')).toBe(
'quarantine:shared-old'
);
adapters[1]?.terminalError(new Error('second tab transport failed'));
expect(localStorage.getItem('graphql-cache:scope')).toBe(
'quarantine:shared-old'
);
await vi.waitFor(() => {
expect(firstError).toHaveBeenCalledOnce();
expect(secondError).toHaveBeenCalledOnce();
});
const staleError = vi.fn();
const stale = createWorkerCacheHost({
scope: 'shared-old',
onInitializationError: staleError,
});
await stale.clear();
localStorage.setItem('graphql-cache:scope', 'new-healthy-scope');
adapters[2]?.terminalError(new Error('late stale transport failed'));
expect(localStorage.getItem('graphql-cache:scope')).toBe(
'new-healthy-scope'
);
const disposedError = vi.fn();
const disposed = createWorkerCacheHost({
scope: 'shared-old',
onInitializationError: disposedError,
});
await disposed.clear();
disposed.dispose();
adapters[3]?.terminalError(new Error('late disposed callback'));
expect(localStorage.getItem('graphql-cache:scope')).toBe(
'new-healthy-scope'
);
expect(disposedError).not.toHaveBeenCalled();
});
it('reports a lazy adapter-construction failure without leaking a transport', async () => {
adapterFactory.mockImplementationOnce(() => {
throw new Error('SharedWorker construction failed');
});
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
expect(adapterFactory).not.toHaveBeenCalled();
await expect(host.clear()).rejects.toThrow(
'SharedWorker construction failed'
);
expect(adapterFactory).toHaveBeenCalledOnce();
expect(onInitializationError).toHaveBeenCalledOnce();
expect(lastAdapter).toBeUndefined();
host.dispose();
});
it('disposes explicitly with graceful idempotence and drains pending mutation responses', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.clear();
const adapter = requireAdapter();
let finishDrain: (() => void) | undefined;
const draining = new Promise<void>((resolve) => {
finishDrain = resolve;
});
adapter.dispose.mockImplementationOnce(async () => await draining);
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
await vi.waitFor(() =>
expect(
adapter.requests.filter(
(request) => request.kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1)
);
const mutationRequest = adapter.requests.find(
(request) => request.kind === 'enqueue-optimistic-mutation'
);
host.dispose();
host.dispose();
expect(adapter.dispose).not.toHaveBeenCalled();
adapter.respond(mutationRequest?.id as number, {
...EMPTY_WRITE,
transactionId: '4',
initialClaim: { kind: 'not-runnable' },
});
await expect(mutation).resolves.toEqual(
expect.objectContaining({ transactionId: '4' })
);
finishDrain?.();
await draining;
expect(adapter.dispose).toHaveBeenCalledOnce();
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
await expect(host.clear()).rejects.toThrow(
'cache worker host was disposed'
);
});
it('keeps pagehide armed until graceful adapter retirement resolves', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.clear();
const adapter = requireAdapter();
let finishRetirement!: () => void;
const retirement = new Promise<void>((resolve) => {
finishRetirement = resolve;
});
adapter.dispose.mockImplementationOnce(async () => await retirement);
host.dispose();
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
dispatchEvent(new Event('pagehide'));
expect(adapter.dispose).toHaveBeenNthCalledWith(2, {
graceful: false,
preserveDatabase: true,
});
finishRetirement();
await retirement;
await expect(host.clear()).rejects.toThrow(
'cache worker host was disposed'
);
});
it('quarantines and reports transport failure during adapter retirement', async () => {
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
await host.clear();
const adapter = requireAdapter();
let finishRetirement!: () => void;
const retirement = new Promise<void>((resolve) => {
finishRetirement = resolve;
});
adapter.dispose.mockImplementationOnce(async () => await retirement);
host.dispose();
adapter.terminalError(new Error('SharedWorker failed during retirement'));
expect(adapter.dispose).toHaveBeenNthCalledWith(2, { graceful: false });
await vi.waitFor(() => {
expect(localStorage.getItem('graphql-cache:scope')).toBe(
'quarantine:scope-1'
);
expect(onInitializationError).toHaveBeenCalledOnce();
});
finishRetirement();
await retirement;
});
it('waits for existing read timeout before gracefully disconnecting a requester', async () => {
vi.useFakeTimers();
configureAdapter = (fake) => fake.ignoredKinds.add('read');
const host = createWorkerCacheHost({
scope: 'scope-1',
requestTimeoutMs: 10,
});
await host.clear();
const adapter = requireAdapter();
const read = host.readQuery({ query: 'query Slow { slow }' });
const readOutcome = read.then(
() => undefined,
(error: unknown) => error
);
await Promise.resolve();
expect(adapter.requests.filter(({ kind }) => kind === 'read')).toHaveLength(
1
);
host.dispose();
expect(adapter.dispose).not.toHaveBeenCalled();
await vi.advanceTimersByTimeAsync(11);
await expect(readOutcome).resolves.toMatchObject({
message: 'cache worker timeout: read',
});
expect(adapter.dispose).toHaveBeenCalledOnce();
expect(adapter.dispose).toHaveBeenCalledWith({ graceful: true });
});
it('preserves transport uncertainty when graceful disposal is already draining admitted work', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
await host.clear();
const adapter = requireAdapter();
let finishDrain!: () => void;
const draining = new Promise<void>((resolve) => {
finishDrain = resolve;
});
adapter.dispose.mockImplementationOnce(async () => await draining);
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
await vi.waitFor(() =>
expect(
adapter.requests.filter(
({ kind }) => kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1)
);
host.dispose();
adapter.terminalError(new Error('transport failed during drain'));
await expect(mutation).rejects.toMatchObject({
errorCode: 'admitted-enqueue-uncertain',
});
expect(localStorage.getItem('graphql-cache:scope')).toBe(
'quarantine:scope-1'
);
expect(onInitializationError).toHaveBeenCalledOnce();
finishDrain();
await draining;
});
it('classifies admitted and late navigation writes consistently', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.currentRevision();
const adapter = requireAdapter();
adapter.ignoredKinds.add('write');
const args = {
query: 'subscription Updates { update }',
data: { update: 1 },
};
const admitted = host.writeQuery(args);
const rejected =
expect(admitted).rejects.toBeInstanceOf(CacheNavigationError);
await vi.waitFor(() => expect(adapter.requests.at(-1)?.kind).toBe('write'));
dispatchEvent(new PageTransitionEvent('pagehide'));
await rejected;
await expect(host.writeQuery(args)).rejects.toBeInstanceOf(
CacheNavigationError
);
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await expect(host.currentRevision()).rejects.toBeInstanceOf(
CacheNavigationError
);
expect(adapterFactory).toHaveBeenCalledOnce();
});
it('reconnects the same host repeatedly and retains subscriptions and active query dependencies', async () => {
localStorage.setItem('graphql-cache:scope', 'scope-1');
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const affected = vi.fn();
const generations = vi.fn();
const changed = vi.fn();
const hydrated = vi.fn();
const settled = vi.fn();
host.onOpsAffected(affected);
host.onCacheGenerationChanged(generations);
host.onCacheChanged(changed);
host.onCacheChanged(hydrated, { includeHydration: true });
host.onMutationSettled(settled);
for (let cycle = 0; cycle < 2; cycle += 1) {
await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
await host.readQuery({ opKey: 9, query: 'query Nine { nine }' });
const old = requireAdapter();
dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
expect(old.dispose).toHaveBeenCalledWith({
graceful: false,
preserveDatabase: true,
});
await host.teardown(9);
await expect(host.currentRevision()).rejects.toBeInstanceOf(
CacheNavigationError
);
old.terminalError(new Error('late retired transport error'));
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await host.currentRevision();
const replacement = requireAdapter();
expect(replacement).not.toBe(old);
expect(affected).toHaveBeenLastCalledWith([7]);
expect(generations).toHaveBeenLastCalledWith({ storage: 'reset' });
expect(host.clientId).toBe(CLIENT_ID);
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
expect(replacement.options.scope).toBe('scope-1');
old.replace(100);
old.terminalError(new Error('late callback after restore'));
old.push({ kind: 'cache-changed', revision: INITIAL_CACHE_REVISION });
expect(changed).toHaveBeenCalledTimes(cycle);
replacement.push({
kind: 'cache-changed',
revision: INITIAL_CACHE_REVISION,
});
replacement.push({
kind: 'cache-hydrated',
revision: INITIAL_CACHE_REVISION,
});
replacement.push({
kind: 'mutation-settled',
settlement: { transactionId: '3', status: 'committed' },
});
expect(changed).toHaveBeenCalledTimes(cycle + 1);
expect(hydrated).toHaveBeenCalledTimes((cycle + 1) * 2);
expect(settled).toHaveBeenCalledTimes(cycle + 1);
}
expect(adapterFactory).toHaveBeenCalledTimes(3);
expect(onInitializationError).not.toHaveBeenCalled();
host.dispose();
});
it.each(['registration', 'init'] as const)(
'restores when pagehide interrupts %s without resurrecting the old attempt',
async (phase) => {
configureAdapter = (fake) => {
if (phase === 'registration')
fake.start.mockImplementationOnce(() => new Promise(() => {}));
else fake.ignoredKinds.add('init');
};
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
const affected = vi.fn();
host.onOpsAffected(affected);
const read = host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
const rejected =
expect(read).rejects.toBeInstanceOf(CacheNavigationError);
const old = requireAdapter();
if (phase === 'init')
await vi.waitFor(() => expect(old.requests).toHaveLength(1));
dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
configureAdapter = () => undefined;
// No intervening microtask: exercise the old startup's catch/finally racing restore.
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await rejected;
await expect(host.currentRevision()).resolves.toBe(
INITIAL_CACHE_REVISION
);
expect(requireAdapter()).not.toBe(old);
expect(affected).toHaveBeenCalledWith([7]);
expect(onInitializationError).not.toHaveBeenCalled();
expect(adapterFactory).toHaveBeenCalledTimes(2);
host.dispose();
}
);
it.each([false, true])(
'does not resurrect an explicitly disposed host (restore started: %s)',
async (restoreStarted) => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.currentRevision();
dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
if (restoreStarted)
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
host.dispose();
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await expect(host.currentRevision()).rejects.toThrow(
'cache worker host was disposed'
);
await new Promise((resolve) => setTimeout(resolve, 0));
expect(adapterFactory).toHaveBeenCalledOnce();
}
);
it('reports a failed restore through normal initialization fallback', async () => {
const onInitializationError = vi.fn();
const host = createWorkerCacheHost({
scope: 'scope-1',
onInitializationError,
});
await host.currentRevision();
dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
configureAdapter = (fake) => fake.errors.set('init', 'restore failed');
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await expect(host.currentRevision()).rejects.toThrow('restore failed');
expect(onInitializationError).toHaveBeenCalledExactlyOnceWith(
expect.objectContaining({ message: 'restore failed' })
);
host.dispose();
});
it('revalidates reads attempted while suspended instead of counting them as replacement registrations', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
const affected = vi.fn();
host.onOpsAffected(affected);
await host.readQuery({ opKey: 7, query: 'query Seven { seven }' });
dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
for (const opKey of [7, 9]) {
await expect(
host.readQuery({ opKey, query: 'query Value { value }' })
).rejects.toBeInstanceOf(CacheNavigationError);
}
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await host.currentRevision();
expect(affected).toHaveBeenCalledWith([7, 9]);
host.dispose();
});
it('fences a pre-navigation write waiting to be admitted across immediate restoration', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.currentRevision();
const stale = host.writeQuery({
query: 'query Value { value }',
data: { value: 'stale' },
});
const rejected = expect(stale).rejects.toBeInstanceOf(CacheNavigationError);
dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await rejected;
await host.currentRevision();
expect(requireAdapter().requests.some(({ kind }) => kind === 'write')).toBe(
false
);
host.dispose();
});
it('never replays an uncertain enqueue after restoration', async () => {
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.currentRevision();
const old = requireAdapter();
old.ignoredKinds.add('enqueue-optimistic-mutation');
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const rejected = expect(mutation).rejects.toMatchObject({
errorCode: 'admitted-enqueue-uncertain',
cause: expect.any(CacheNavigationError),
});
await vi.waitFor(() =>
expect(old.requests.at(-1)?.kind).toBe('enqueue-optimistic-mutation')
);
dispatchEvent(new PageTransitionEvent('pagehide', { persisted: true }));
dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
await rejected;
await host.currentRevision();
expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([
'init',
'current-revision',
]);
host.dispose();
});
it('treats pagehide enqueue as uncertain without quarantining persistent storage', async () => {
configureAdapter = (fake) => {
fake.ignoredKinds.add('enqueue-optimistic-mutation');
};
localStorage.setItem('graphql-cache:scope', 'scope-1');
const host = createWorkerCacheHost({ scope: 'scope-1' });
await host.clear();
const adapter = requireAdapter();
const mutation = host.enqueueOptimisticMutation(
{
uuid: '00000000-0000-4000-8000-000000000100',
query: 'mutation Update { update }',
data: { update: true },
},
{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 }
);
const rejected = expect(mutation).rejects.toMatchObject({
message: expect.stringContaining('disposed for page navigation'),
errorCode: 'admitted-enqueue-uncertain',
cause: expect.any(CacheNavigationError),
});
await vi.waitFor(() =>
expect(
adapter.requests.filter(
({ kind }) => kind === 'enqueue-optimistic-mutation'
)
).toHaveLength(1)
);
host.dispose();
expect(adapter.dispose).not.toHaveBeenCalled();
dispatchEvent(new Event('pagehide'));
await rejected;
expect(adapter.dispose).toHaveBeenCalledOnce();
expect(adapter.dispose).toHaveBeenCalledWith({
graceful: false,
preserveDatabase: true,
});
expect(localStorage.getItem('graphql-cache:scope')).toBe('scope-1');
});
});