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 { externalWriteVersion, predatesExternalWrite } from './external-writes';
/**
* urql exchange backed by the normalized wasm cache (via a `CacheHost`).
*
* Differences from `@urql/exchange-graphcache`:
* - cache reads are **async** (the cache is disk-backed, possibly in another
* worker/process). Cache-first misses enter the network queue after reading;
* cache-and-network queries start the network without waiting for storage;
* - invalidation is push-based: the host emits "these operation keys must
* re-execute" (local sibling writes, other tabs/webviews, external
* invalidations) and the exchange re-executes them as `cache-first`.
*
* Request policies:
* - `cache-first` (default): hit → emit; miss → network.
* - `cache-and-network`: read and fetch concurrently; a cache hit may emit with
* `stale: true` only before newer results supersede that read. (`toPromise()`
* ignores stale results, so imperative callers keep network-fresh semantics.)
* - `network-only`: skip read; response still written to cache.
* - Foreground network query results publish before persistence. Their private
* metadata carries a revision acknowledgement for local reconciliation; writes
* remain ordered, and acknowledgements never replay the response payload.
* - `cache-only`: hit → emit; miss → emit `data: undefined`, no network.
*
* Mutations:
* - With an optimistic response (see `executeOptimisticMutation`): the
* mutation and layer are durably queued before the ordered runner
* (`mutation-queue-runner.ts`) forwards it. Retryable failures retain optimism for background replay, but the tenth
* server failure permanently rolls back; transport failures are not counted.
* Other permanent failures roll back immediately. A caller blocked behind the queue
* head receives a synthetic `queued` disposition instead of waiting.
* - Without one: forwarded normally; successful responses are normalized
* through the standard write path so dependent cached queries update.
*
* Cache failures normally degrade to the network. An admitted optimistic
* enqueue with an unknown durable outcome emits an error instead, because
* forwarding could duplicate a side effect already in the persistent queue.
*/
import { fireAndForget } from '@core/util/fireAndForget';
import { type Span, Telemetry } from '@macro-inc/observability';
import {
type Client,
CombinedError,
createRequest,
type Exchange,
makeOperation,
type Operation,
type OperationResult,
stringifyDocument,
} from '@urql/core';
import {
type DocumentNode,
Kind,
type OperationDefinitionNode,
visit,
} from 'graphql';
import { batch } from 'solid-js';
import {
empty,
filter,
fromPromise,
fromValue,
makeSubject,
map,
merge,
mergeMap,
pipe,
type Source,
share,
tap,
} from 'wonka';
import { supportsStoreReconciliation } from '../../urql-solid/reactive-selection';
import type { CacheHost } from '../host/types';
import {
type CacheRevision,
type ClaimedMutation,
type EnqueueOptimisticMutationResult,
isAdmittedEnqueueUncertainError,
isCacheRevision,
isOwnerEpochLostError,
isOwnerLockUnavailableError,
type QueryRevalidationWire,
type ReadResult,
} from '../protocol';
import { classifyCacheError } from '../telemetry';
import { createDeferredQueryRereads } from './deferred-query-rereads';
import {
createDocumentQueryReader,
QueryReadInvalidatedError,
} from './document-query-reader';
import {
compileEntityResolvers,
type EntityResolverConfig,
} from './entity-resolvers';
import { isQueryObject, LiveQuery, withLiveQueryData } from './live-query';
import {
createMutationQueueRunner,
QUEUE_LEASE_MS,
QUEUE_REQUEST_TIMEOUT_MS,
queueAttemptOf,
replayDocument,
withQueueRequestTimeout,
} from './mutation-queue-runner';
import {
type MutationQueueTelemetry,
NOOP_MUTATION_QUEUE_TELEMETRY,
} from './mutation-queue-telemetry';
import type { QueryRevalidation } from './optimistic';
import {
normalizedEntityKey,
notifyOptimisticMutationEnqueued,
optimisticContextOf,
withOptimisticMutationDisposition,
} from './optimistic';
import { queryShape } from './query-shape';
import { runSubscriptionCacheEffects } from './subscription-cache-trace';
/** Server writes acknowledged since this query left for the network. */
const QUERY_MUTATION_VERSION_CONTEXT_KEY =
'normalizedCacheQueryMutationVersion';
/** Marks dependency-pushed reads as latency-sensitive worker work. */
const AFFECTED_READ_CONTEXT_KEY = 'normalizedCacheAffectedRead';
// Below every hashed operation key, so a link repair shares none of them.
let lastLinkRepairKey = -(2 ** 40);
/**
* A link repair gets its own operation key, because the mutation queue waits for
* it. urql drops a query whose key has a dispatch outstanding, and an affected
* reread this exchange fences never reports back, so on a shared key the repair
* was never sent and held the whole queue until its timeout. Other revalidations
* aren't waited on, and share the mounted reader's key and scope.
*/
function revalidationQuery(
client: Client,
document: DocumentNode,
variables: Record<string, unknown>,
isLinkRepair: boolean
) {
if (!isLinkRepair) {
return client.query(document, variables, { requestPolicy: 'network-only' });
}
lastLinkRepairKey -= 1;
return client.executeRequestOperation(
client.createRequestOperation(
'query',
{ ...createRequest(document, variables), key: lastLinkRepairKey },
{ requestPolicy: 'network-only' }
)
);
}
/** Prevents a replacement-registration cache read from forwarding the API again. */
const REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY =
'normalizedCacheReplacementRegistrationOnly';
/** Marks a query as network-to-cache hydration with a projected result. */
declare module '@urql/core' {
interface OperationContext {
/** Publish the network result without storing it in the cache. */
persistResult?: false;
/** Types that can change this query's membership, even in an empty response. */
externalCacheWriteTypes?: readonly string[];
}
}
export const HYDRATE_ONLY_CONTEXT_KEY = 'normalizedCacheHydrateOnly';
/** Retains the client-annotated document while the transport uses a stripped copy. */
const HYDRATION_DOCUMENT_CONTEXT_KEY = 'normalizedCacheHydrationDocument';
const NORMALIZED_CACHE_RESULT_METADATA_KEY = '__macroNormalizedCache';
/** Private authority metadata attached by the normalized-cache exchange. */
export type NormalizedCacheResultMetadata =
| {
source: 'live-network';
/** Subscription effects finished successfully in this cache generation. */
cacheEffectsApplied?: boolean;
revision?: CacheRevision;
/** Local-only acknowledgement; never rejects or republishes response data. */
persistence?: Promise<CacheRevision | undefined>;
}
| { source: 'normalized-cache-hit' }
| { source: 'normalized-cache-patch' }
| { source: 'affected-cache-reread' };
/** Reads normalized-cache authority metadata from an urql operation result. */
export function normalizedCacheResultMetadata(
result: Pick<OperationResult, 'extensions'>
): NormalizedCacheResultMetadata | undefined {
const metadata = result.extensions?.[NORMALIZED_CACHE_RESULT_METADATA_KEY];
if (metadata === null || typeof metadata !== 'object') return;
const source = (metadata as { source?: unknown }).source;
if (
source === 'normalized-cache-hit' ||
source === 'affected-cache-reread' ||
source === 'normalized-cache-patch'
) {
return { source };
}
if (source !== 'live-network') return;
const { revision, persistence, cacheEffectsApplied } = metadata as {
cacheEffectsApplied?: unknown;
revision?: unknown;
persistence?: unknown;
};
return {
source,
...(typeof cacheEffectsApplied === 'boolean'
? { cacheEffectsApplied }
: {}),
...(isCacheRevision(revision) ? { revision } : {}),
...(isThenable(persistence)
? { persistence: persistence as Promise<CacheRevision | undefined> }
: {}),
};
}
// zone.js replaces the global Promise, so a native async function's promise
// fails `instanceof Promise` in the app.
function isThenable(value: unknown): value is PromiseLike<unknown> {
return (
typeof value === 'object' &&
value !== null &&
typeof (value as { then?: unknown }).then === 'function'
);
}
function withResultMetadata(
result: OperationResult,
metadata: NormalizedCacheResultMetadata
): OperationResult {
return {
...result,
extensions: {
...result.extensions,
[NORMALIZED_CACHE_RESULT_METADATA_KEY]: metadata,
},
};
}
const queryTextCache = new WeakMap<object, string>();
function queryText(op: Operation): string {
const doc = op.query;
let text = queryTextCache.get(doc);
if (text === undefined) {
text = stringifyDocument(doc);
queryTextCache.set(doc, text);
}
return text;
}
function hydrationDocument(op: Operation): DocumentNode | undefined {
const document: unknown = op.context[HYDRATION_DOCUMENT_CONTEXT_KEY];
return document && typeof document === 'object'
? (document as DocumentNode)
: undefined;
}
function cacheQueryText(op: Operation): string {
const document = hydrationDocument(op);
if (!document) return queryText(op);
let text = queryTextCache.get(document);
if (text === undefined) {
text = stringifyDocument(document);
queryTextCache.set(document, text);
}
return text;
}
function isHydrateOnly(op: Operation): boolean {
return op.context[HYDRATE_ONLY_CONTEXT_KEY] === true;
}
const transportDocumentCache = new WeakMap<object, DocumentNode>();
function hydrationTransportOperation(op: Operation): Operation {
let document = transportDocumentCache.get(op.query);
if (!document) {
document = visit(op.query, {
Directive(node) {
return node.name.value === 'cacheOnly' ? null : undefined;
},
});
transportDocumentCache.set(op.query, document);
}
return makeOperation(
op.kind,
{ ...op, query: document },
{
...op.context,
requestPolicy: 'network-only',
[HYDRATION_DOCUMENT_CONTEXT_KEY]: hydrationDocument(op) ?? op.query,
}
);
}
function operationName(op: Operation): string | undefined {
for (const def of op.query.definitions) {
if (def.kind === Kind.OPERATION_DEFINITION) {
return (def as OperationDefinitionNode).name?.value;
}
}
return undefined;
}
function cacheResult(
op: Operation,
data: unknown,
stale: boolean,
source: Extract<
NormalizedCacheResultMetadata,
{ source: 'normalized-cache-hit' | 'affected-cache-reread' }
>['source'] = 'normalized-cache-hit'
): OperationResult {
return withResultMetadata(
{
operation: op,
data,
error: undefined,
extensions: undefined,
stale,
hasNext: false,
},
{ source }
);
}
type CacheEffect =
| { kind: 'write'; data: unknown }
| { kind: 'delete'; key: string };
/** Returns the normalized key carried by the cache-deletion GraphQL type. */
function graphqlCacheDeletionKey(value: unknown): string | undefined {
if (value === null || typeof value !== 'object') return;
const record = value as Record<string, unknown>;
if (
record.__typename !== 'GraphqlCacheDeletion' ||
typeof record.graphqlTypeName !== 'string' ||
typeof record.entityId !== 'string'
) {
return;
}
return normalizedEntityKey({
__typename: record.graphqlTypeName,
id: record.entityId,
});
}
/** Returns whether a response subtree contains an explicit cache deletion. */
function containsCacheDeletion(data: unknown): boolean {
if (graphqlCacheDeletionKey(data) !== undefined) return true;
if (data === null || typeof data !== 'object') return false;
return Array.isArray(data)
? data.some(containsCacheDeletion)
: Object.values(data).some(containsCacheDeletion);
}
/**
* Converts any GraphQL operation payload into ordered cache effects. Ordinary
* data remains one normalized write. When an explicit cache deletion is nested
* in an object or list, writes are narrowed to the corresponding response path
* so surrounding writes and deletions retain their wire order. Response keys
* and ancestor scalar context (including `__typename`) are copied verbatim,
* which preserves aliases and inline-fragment resolution without schema or
* operation knowledge.
*/
function operationCacheEffects(data: unknown): CacheEffect[] {
const deletionKey = graphqlCacheDeletionKey(data);
if (deletionKey !== undefined) {
return [{ kind: 'delete', key: deletionKey }];
}
if (!containsCacheDeletion(data)) return [{ kind: 'write', data }];
if (Array.isArray(data)) {
return data.flatMap((value) =>
operationCacheEffects(value).map((effect) =>
effect.kind === 'write'
? {
kind: 'write' as const,
// Safe only for transient operation-root effect lists such as
// `soupUpdates`/`effects`, never normalized entity link lists.
data: [effect.data],
}
: effect
)
);
}
if (data === null || typeof data !== 'object') {
return [{ kind: 'write', data }];
}
const entries = Object.entries(data);
const context = entries.filter(([, value]) => !containsCacheDeletion(value));
const effectFields = entries.filter(([, value]) =>
containsCacheDeletion(value)
);
return effectFields.flatMap(([effectField, value]) =>
operationCacheEffects(value).map((effect) => {
if (effect.kind === 'delete') return effect;
const wrapped: Record<string, unknown> = {};
for (const [field, fieldValue] of entries) {
if (field === effectField) wrapped[field] = effect.data;
else if (context.some(([contextField]) => contextField === field)) {
wrapped[field] = fieldValue;
}
}
return { kind: 'write' as const, data: wrapped };
})
);
}
function uncertainEnqueueResult(op: Operation, error: Error): OperationResult {
return {
operation: op,
data: undefined,
error: new CombinedError({ networkError: error }),
extensions: undefined,
stale: false,
hasNext: false,
};
}
export interface NormalizedCacheExchangeOptions {
/**
* Best-effort startup recovery before per-mutation admission. Resolve
* `false` when it cannot run yet; the next drain asks again.
*/
prepareMutationQueue?: () => Promise<boolean | void>;
/**
* False discards obsolete client intent without sending it to the server.
* `'defer'` keeps the mutation queued and asks again shortly, for intent
* that cannot be judged yet (a draft before its account is known).
*/
beforeMutationAttempt?: (
mutation: ClaimedMutation
) => Promise<boolean | 'defer'>;
/** Persist domain recovery state for a replayed result, including when its UI is closed. */
onMutationAttemptResult?: (
mutation: ClaimedMutation,
result: OperationResult,
retry: boolean
) => Promise<void>;
/** Domain-specific deletions inferred from a successful server response. */
deletedRecordKeys?: (result: OperationResult) => string[];
/** Return true to transfer a committed query refresh to an active reader's queue.
* Persisted descriptors without an owner retain the normal network fallback. */
delegateRevalidation?: (client: Client, query: QueryRevalidation) => boolean;
/** Recover membership dependencies for imperative or durably replayed queries. */
externalWriteTypes?: (operation: Operation) => readonly string[] | undefined;
/** Schema-typed singular entity relations derived from field arguments. */
entityResolvers?: EntityResolverConfig;
/** Called when cache work fails; the operation may degrade or emit uncertainty. */
onCacheError?: (error: unknown, op: Operation) => void;
/**
* Extracts the session identity (e.g. viewer id, `data.user.id`) from a
* response. The extracted value is passed to the cache as an opaque tag;
* a write tagged with a different identity than the one bound to the
* cache wipes and rebinds it atomically (silent restart), and every
* active operation re-executes. Schema knowledge lives here — the cache
* layer itself is identity-agnostic.
*/
extractIdentity?: (data: unknown) => string | undefined;
/**
* Decides whether a failed optimistic mutation remains queued. The caller
* receives a `queued` disposition; `true` retains the optimistic layer for
* a later background attempt. Defaults to `false`.
*/
shouldRetryMutation?: (error: CombinedError) => boolean | Promise<boolean>;
/** Spans, bounded logs, and counters for the durable mutation queue. */
mutationQueueTelemetry?: MutationQueueTelemetry;
}
export function normalizedCacheExchange(
host: CacheHost,
options: NormalizedCacheExchangeOptions = {}
): Exchange {
const entityResolvers = compileEntityResolvers(options.entityResolvers);
return ({ forward, client }) => {
/** Operations registered with the host, for push-driven re-execution. */
const activeOps = new Map<number, Operation>();
const documentReader = createDocumentQueryReader(host);
// Teardown and generation changes cancel document reads in flight. The
// read is already stale then, so the cancellation is not a cache failure.
const reportReadError = (error: unknown, op: Operation): void => {
if (!(error instanceof QueryReadInvalidatedError))
options.onCacheError?.(error, op);
};
let cacheGeneration = 0;
let mutationVersion = 0;
host.onMutationSettled((settlement) => {
// Another tab's durable queue runner can commit into this same cache.
if (settlement.status !== 'permanently-failed') mutationVersion += 1;
});
const liveQueries = new Map<
number,
{ view: LiveQuery; result: OperationResult }
>();
const { source: affectedResults$, next: emitAffectedResult } =
makeSubject<OperationResult>();
type RetainedReplacementFallback = {
version: number;
writeArgs: Parameters<CacheHost['writeQuery']>[0];
readyPending: boolean;
recovering: boolean;
invalidated: boolean;
recoveryPromise?: Promise<void>;
};
type QueryState = {
/** Includes background persistence for dependency/replacement ordering. */
networkBoundQueries: number;
networkRequestsInFlight: number;
replacementFallback: boolean;
deferredAffected: boolean;
completedReplacementFallback: boolean;
networkRegistrationSatisfied: boolean;
retainedReplacementFallback?: RetainedReplacementFallback;
networkResultVersion: number;
cacheReadVersion: number;
networkError?: CombinedError;
};
// Keep write ordering across teardown/remount, including imperative queries
// that unsubscribe as soon as the early network result reaches toPromise().
const queryResultTurns = new Map<number, Promise<void>>();
const queryStates = new Map<number, QueryState>();
const queryState = (key: number): QueryState => {
let state = queryStates.get(key);
if (!state) {
state = {
networkBoundQueries: 0,
networkRequestsInFlight: 0,
replacementFallback: false,
deferredAffected: false,
completedReplacementFallback: false,
networkRegistrationSatisfied: false,
networkResultVersion: 0,
cacheReadVersion: 0,
};
queryStates.set(key, state);
}
return state;
};
// Async reads must not resurrect a torn-down operation, overwrite a newer
// network result, or undo a subsequent optimistic/affected cache reread.
const beginCacheRead = (key: number) => {
const state = queryState(key);
const version = ++state.cacheReadVersion;
const generation = cacheGeneration;
const isLatest = () =>
activeOps.has(key) &&
queryStates.get(key) === state &&
state.cacheReadVersion === version;
return {
isCurrent: () => generation === cacheGeneration && isLatest(),
isLatest,
};
};
const acquireQueryResultTurn = async (key: number): Promise<() => void> => {
const previous = queryResultTurns.get(key) ?? Promise.resolve();
let release!: () => void;
const current = new Promise<void>((resolve) => {
release = resolve;
});
queryResultTurns.set(key, current);
await previous;
return () => {
release();
if (queryResultTurns.get(key) === current) queryResultTurns.delete(key);
};
};
const invalidateOlderRetainedFallback = async (
state: QueryState,
version: number
): Promise<void> => {
while (true) {
const retained = state.retainedReplacementFallback;
if (!retained || retained.version >= version) return;
retained.invalidated = true;
retained.readyPending = false;
if (retained.recoveryPromise) {
// Keep the exact in-flight candidate addressable until its cache
// attempt settles; the newer result must write strictly after it.
await retained.recoveryPromise;
}
if (state.retainedReplacementFallback === retained) {
state.retainedReplacementFallback = undefined;
}
}
};
const reexecuteAffected = (key: number, registrationOnly = false): void => {
const op = activeOps.get(key);
if (!op) return;
client.reexecuteOperation(
makeOperation(op.kind, op, {
...op.context,
requestPolicy:
op.context.requestPolicy === 'cache-only'
? 'cache-only'
: 'cache-first',
[AFFECTED_READ_CONTEXT_KEY]: true,
// activeOps observes every reissued operation. Explicitly clear the
// one-shot marker so a later ordinary invalidation can reach the API.
[REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY]: registrationOnly,
})
);
};
const recoverRetainedReplacementFallback = (key: number): void => {
const state = queryStates.get(key);
const retained = state?.retainedReplacementFallback;
if (!state || !retained || retained.invalidated || !activeOps.has(key))
return;
retained.readyPending = true;
if (retained.recovering || state.networkBoundQueries > 0) return;
retained.recovering = true;
const recovery = (async () => {
while (
queryStates.get(key) === state &&
state.retainedReplacementFallback === retained &&
!retained.invalidated &&
retained.readyPending
) {
retained.readyPending = false;
try {
await host.writeQuery({
...retained.writeArgs,
registerDependencies: true,
});
if (
queryStates.get(key) !== state ||
state.retainedReplacementFallback !== retained ||
retained.invalidated ||
!activeOps.has(key)
) {
return;
}
if (
queryStates.get(key) !== state ||
state.retainedReplacementFallback !== retained ||
retained.invalidated
) {
return;
}
state.retainedReplacementFallback = undefined;
state.replacementFallback = false;
state.deferredAffected = false;
state.completedReplacementFallback = false;
state.networkRegistrationSatisfied = false;
return;
} catch (error) {
if (
queryStates.get(key) !== state ||
state.retainedReplacementFallback !== retained ||
retained.invalidated
) {
return;
}
const active = activeOps.get(key);
if (active) options.onCacheError?.(error, active);
// Preserve the successful payload for a later replacement-ready
// notification. A notification received during this attempt sets
// readyPending and safely drives exactly one subsequent attempt.
}
}
})().catch(() => undefined);
retained.recoveryPromise = recovery;
fireAndForget(
recovery.then(() => {
if (retained.recoveryPromise === recovery) {
retained.recoveryPromise = undefined;
}
if (
queryStates.get(key) !== state ||
state.retainedReplacementFallback !== retained
)
return;
retained.recovering = false;
if (retained.invalidated) {
state.retainedReplacementFallback = undefined;
} else if (retained.readyPending) {
recoverRetainedReplacementFallback(key);
}
}),
'graphql-cache-exchange'
);
};
const pendingAffectedReads = new Set<Promise<void>>();
const trackAffectedRead = (read: Promise<void>): void => {
pendingAffectedReads.add(read);
const settled = () => pendingAffectedReads.delete(read);
void read.then(settled, settled);
};
const emitAffectedWhileNetworkBound = async (
key: number
): Promise<void> => {
const operation = activeOps.get(key);
if (!operation) return;
const state = queryState(key);
// Supersede the initial cache snapshot, but let a newer published result
// supersede this read too. Pending local edits are reconciled against the
// new server snapshot after persistence, never through an older snapshot.
const readVersion = beginCacheRead(key);
await documentReader
.read({
opKey: operation.key,
query: queryText(operation),
operationName: operationName(operation),
variables: operation.variables as Record<string, unknown> | undefined,
priority: 'user-visible',
entityResolvers,
})
.then((read) => {
const active = activeOps.get(key);
if (!readVersion.isCurrent() || read.kind !== 'hit' || !active)
return;
// Preserve the authoritative request while immediately surfacing the
// newer local view. Its eventual result still gets the deferred
// cache reread below when it could not register fresh dependencies.
emitAffectedResult(
cacheResult(
active,
read.data,
state.networkRequestsInFlight > 0,
'affected-cache-reread'
)
);
})
.catch((error) => reportReadError(error, operation));
};
// Deliver cache changes directly. Reexecuting through urql first replays
// the previous network result as stale, which can reset collection sources
// and replay their persistence acknowledgements during an optimistic edit.
const emitWatchedQuery = async (
key: number,
retrying = false
): Promise<void> => {
const operation = activeOps.get(key);
if (!operation) return;
const readVersion = beginCacheRead(key);
let read: ReadResult | undefined;
try {
read = await documentReader.read({
opKey: key,
query: queryText(operation),
operationName: operationName(operation),
variables: operation.variables as Record<string, unknown> | undefined,
priority: 'user-visible',
entityResolvers,
});
} catch (error) {
reportReadError(error, operation);
}
if (!readVersion.isCurrent()) {
if (!readVersion.isLatest()) return;
if (!retrying) {
await Telemetry.anonymousSpan(
'graphql_cache.read_retry',
async (span) => {
span.setAttr('cache.retry.reason', 'generation-change');
span.setAttr('cache.retry.count', 1);
span.setAttr('cache.retry.read_type', 'affected');
await emitWatchedQuery(key, true);
}
);
return;
}
} else if (read?.kind === 'hit') {
emitAffectedResult(
cacheResult(operation, read.data, false, 'affected-cache-reread')
);
return;
}
reexecuteAffected(key);
};
const affectedRereads = createDeferredQueryRereads(
(key, registrationOnly) => {
if (!activeOps.has(key)) return;
const state = queryStates.get(key);
// A request or worker replacement may have started while this read was
// deferred. Re-check current state instead of replaying a stale action.
if (state?.retainedReplacementFallback) {
recoverRetainedReplacementFallback(key);
} else if (state && state.networkBoundQueries > 0) {
state.deferredAffected = true;
if (!state.replacementFallback)
trackAffectedRead(emitAffectedWhileNetworkBound(key));
} else if (
host.watchQuery &&
!registrationOnly &&
liveQueries.has(key) &&
!liveQueries.get(key)?.result.error &&
!liveQueries.get(key)?.result.hasNext
) {
trackAffectedRead(emitWatchedQuery(key));
} else {
reexecuteAffected(key, registrationOnly);
}
}
);
const unsubscribePush = host.onOpsAffected((opKeys) =>
batch(() => {
for (const key of opKeys) {
if (!activeOps.has(key)) continue;
const state = queryState(key);
if (state.networkBoundQueries > 0) {
state.deferredAffected = true;
if (
!state.replacementFallback &&
!state.retainedReplacementFallback
) {
affectedRereads.request(key);
}
continue;
}
const registrationOnly = state.completedReplacementFallback;
state.completedReplacementFallback = false;
state.replacementFallback = false;
if (state.retainedReplacementFallback) {
recoverRetainedReplacementFallback(key);
continue;
}
affectedRereads.request(key, registrationOnly);
}
})
);
return (ops$) => {
const shared = pipe(ops$, share);
// Async cache reads re-inject network-bound operations here.
const { source: forwardQueue$, next: enqueueForward } =
makeSubject<Operation>();
const hydrationRequests = new Set<number>();
const atMutationVersion = (op: Operation): Operation =>
makeOperation('query', op, {
...op.context,
[QUERY_MUTATION_VERSION_CONTEXT_KEY]: mutationVersion,
externalCacheWriteVersion: externalWriteVersion(host),
externalCacheWriteTypes:
op.context.externalCacheWriteTypes ??
options.externalWriteTypes?.(op),
});
const enqueueHydrationForward = (op: Operation): void => {
const request = atMutationVersion(hydrationTransportOperation(op));
hydrationRequests.add(op.key);
enqueueForward(request);
};
const enqueueQueryForward = (op: Operation): void => {
const state = queryState(op.key);
state.networkBoundQueries += 1;
state.networkRequestsInFlight += 1;
state.networkError = undefined;
enqueueForward(atMutationVersion(op));
};
const predatesMutation = (op: Operation): boolean => {
const version: unknown = op.context[QUERY_MUTATION_VERSION_CONTEXT_KEY];
return typeof version === 'number' && version < mutationVersion;
};
// A response from before an acknowledged write cannot safely replace
// either live data or normalized records. Fetch a new snapshot without
// replaying urql's previous result or dropping the mounted subscription.
const refreshObsoleteQuery = (op: Operation): void => {
const active = activeOps.get(op.key);
if (active && active.context.requestPolicy !== 'cache-only') {
enqueueQueryForward(active);
}
};
const finishNetworkQuery = (
key: number,
state: QueryState,
replacementRegistrationSatisfied: boolean
): void => {
if (queryStates.get(key) !== state) return;
const remaining = state.networkBoundQueries - 1;
if (remaining > 0) {
state.networkBoundQueries = remaining;
return;
}
state.networkBoundQueries = 0;
const deferred = state.deferredAffected;
state.deferredAffected = false;
const replacementFallback = state.replacementFallback;
state.replacementFallback = false;
if (deferred) {
state.completedReplacementFallback = false;
if (!replacementRegistrationSatisfied) {
if (state.retainedReplacementFallback) {
recoverRetainedReplacementFallback(key);
} else if (activeOps.has(key)) {
affectedRereads.request(key, true);
}
}
} else if (replacementFallback) {
// A fast fallback completed before replacement initialization. The
// later affected notification must register cache dependencies but
// must not issue the API request a second time.
state.completedReplacementFallback = true;
}
};
const queueOwner = `exchange:${host.clientId}`;
const queueTelemetry =
options.mutationQueueTelemetry ?? NOOP_MUTATION_QUEUE_TELEMETRY;
const mutationQueue = createMutationQueueRunner({
host,
client,
options,
owner: queueOwner,
forward: enqueueForward,
writeThrough,
cacheDocument: (op) => ({
query: queryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
}),
deleteReportedRecords,
replayExplicitEffects: (op, data, isCurrent) => {
const effects = operationCacheEffects(data);
// Commit already normalized the complete result. Replay only mixed
// explicit effects so their final write/delete order is identical
// to a non-optimistic operation.
return effects.some((effect) => effect.kind === 'delete')
? applyOperationCacheEffects(op, effects, isCurrent)
: undefined;
},
revalidate: revalidateAfterSettlement,
});
const subscriptionEffectChains = new Map<number, Promise<boolean>>();
// Teardown invalidates queued effects, including when the same operation
// is immediately resubscribed after a back/forward-cache restore.
const subscriptionGenerations = new Map<number, object>();
async function revalidateAfterSettlement(
revalidations: QueryRevalidationWire[],
mutation?: Operation
): Promise<void> {
const reportError = (error: unknown, operation = mutation) => {
// Diagnostics cannot turn a durably settled attempt back into a retry.
if (!operation) return;
try {
options.onCacheError?.(error, operation);
} catch {
// The settlement is already final.
}
};
const repairs: Promise<void>[] = [];
async function refresh(revalidation: QueryRevalidationWire) {
try {
const variables: unknown = JSON.parse(revalidation.variablesJson);
if (
variables === null ||
typeof variables !== 'object' ||
Array.isArray(variables)
) {
throw new Error('cache revalidation variables are not an object');
}
const document = replayDocument(
revalidation.query,
revalidation.operationName
);
if (
options.delegateRevalidation?.(client, {
document,
variables: variables as Record<string, unknown>,
})
)
return;
const result = await revalidationQuery(
client,
document,
variables as Record<string, unknown>,
revalidation.onlyOnLinkFailure === true
).toPromise();
if (result.error)
reportError(result.error, mutation ?? result.operation);
const metadata = normalizedCacheResultMetadata(result);
if (metadata?.source === 'live-network') await metadata.persistence;
} catch (error) {
reportError(error);
}
}
for (const revalidation of revalidations) {
const pending = refresh(revalidation);
// Ordinary membership refreshes continue in the background.
if (revalidation.onlyOnLinkFailure) repairs.push(pending);
}
if (repairs.length === 0 && pendingAffectedReads.size === 0) return;
const deliver = async () => {
await Promise.all(repairs);
// Persistence schedules subscriber reads but does not publish their
// values. Even a healthy commit must hand off optimism to those reads.
while (pendingAffectedReads.size > 0) {
await Promise.allSettled([...pendingAffectedReads]);
}
};
let timeout: ReturnType<typeof setTimeout> | undefined;
try {
// Include shared requests, persistence, and subscriber publication.
// A slow read must not block the mutation queue indefinitely.
await Promise.race([
deliver(),
new Promise<never>((_, reject) => {
timeout = setTimeout(
() =>
reject(new Error('Timed out delivering mutation updates')),
QUEUE_REQUEST_TIMEOUT_MS
);
}),
]);
} catch (error) {
reportError(error);
} finally {
clearTimeout(timeout);
}
}
async function readThenRoute(
op: Operation,
previousAttempt?: { networkForwarded: boolean }
): Promise<OperationResult | undefined> {
if (isHydrateOnly(op)) {
enqueueHydrationForward(op);
return undefined;
}
const readState = queryState(op.key);
const readVersion = beginCacheRead(op.key);
const policy = op.context.requestPolicy;
if (policy === 'network-only') {
enqueueQueryForward(op);
return undefined;
}
const registrationOnly =
op.context[REPLACEMENT_REGISTRATION_ONLY_CONTEXT_KEY] === true;
let networkForwarded = previousAttempt?.networkForwarded ?? false;
let read: ReadResult | undefined;
try {
const pendingRead = documentReader.read({
opKey: op.key,
query: queryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
entityResolvers,
priority:
op.context[AFFECTED_READ_CONTEXT_KEY] === true
? 'user-visible'
: undefined,
});
// Admit the cache read first, but never wait for the worker's queue
// before starting a request that needs the network regardless.
if (
policy === 'cache-and-network' &&
!registrationOnly &&
!networkForwarded
) {
networkForwarded = true;
enqueueQueryForward(op);
}
read = await pendingRead;
} catch (error) {
reportReadError(error, op);
if (
isOwnerEpochLostError(error) &&
queryStates.get(op.key) === readState &&
(readVersion.isCurrent() || readState.networkBoundQueries > 0)
) {
readState.replacementFallback = true;
}
}
if (!readVersion.isCurrent()) {
// Teardown, remount, or a newer result still fences this attempt.
if (!readVersion.isLatest()) return undefined;
if (!previousAttempt) {
// Only the generation changed. The host may have routed this read
// to the replacement without emitting another affected-key push.
// Retry here: urql deduplicates reexecutions of a pending query.
return await Telemetry.anonymousSpan(
'graphql_cache.read_retry',
async (span) => {
span.setAttr('cache.retry.reason', 'generation-change');
span.setAttr('cache.retry.count', 1);
span.setAttr('cache.retry.read_type', 'operation');
span.setAttr('cache.request_policy', policy);
const result = await readThenRoute(op, { networkForwarded });
span.setAttr('cache.retry.cache_result', result !== undefined);
span.setAttr(
'cache.retry.has_data',
result?.data !== undefined
);
return result;
}
);
}
// Bound churn to one fresh read, then use the normal policy fallback.
// Never publish a snapshot from the invalidated generation.
} else if (read?.kind === 'hit') {
const state = queryState(op.key);
const stale = networkForwarded && state.networkRequestsInFlight > 0;
return {
...cacheResult(op, read.data, stale),
// A fast offline failure must not discard a slower usable cache
// hit, nor may that hit erase the failed revalidation's error.
error: networkForwarded ? state.networkError : undefined,
};
}
// `cache-only` must never touch the network, including after churn.
if (policy === 'cache-only') return cacheResult(op, undefined, false);
if (!networkForwarded && !registrationOnly) enqueueQueryForward(op);
return undefined;
}
/** Durably queues optimism before allowing the ordered runner to send. */
async function prepareMutation(
op: Operation
): Promise<OperationResult | undefined> {
const epoch = mutationQueue.epoch();
if (host.disabled) {
notifyOptimisticMutationEnqueued(op);
enqueueForward(op);
return undefined;
}
// Reconstructed startup retries already have a durable transaction.
if (queueAttemptOf(op)) {
enqueueForward(withQueueRequestTimeout(op));
return undefined;
}
const optimistic = optimisticContextOf(op);
if (!optimistic) {
enqueueForward(op);
return undefined;
}
const args = {
uuid: optimistic.uuid,
query: queryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
data: optimistic.optimisticResponse,
linkPatches: optimistic.linkPatches,
revalidations: optimistic.revalidations,
identityBindings: optimistic.identityBindings,
clientMetadata: optimistic.clientMetadata,
uncertainCalendarEventKeys: optimistic.uncertainCalendarEventKeys,
};
const now = Date.now();
const claim = {
owner: queueOwner,
nowMs: now,
leaseExpiresAtMs: now + QUEUE_LEASE_MS,
};
const enqueueTelemetry = queueTelemetry.enqueue({
uuid: args.uuid,
operationName: args.operationName,
});
let enqueue: EnqueueOptimisticMutationResult;
let linkPatchesDegraded = false;
try {
enqueue = await host.enqueueOptimisticMutation(args, claim);
} catch (error) {
if (!mutationQueue.isCurrent(epoch)) {
enqueueTelemetry.failed('storage-changed');
return uncertainEnqueueResult(
op,
new Error('cache storage changed during enqueue', {
cause: error,
})
);
}
if (isAdmittedEnqueueUncertainError(error)) {
enqueueTelemetry.failed('uncertain');
options.onCacheError?.(error, op);
// Fencing the old engine does not remove a committed queue entry.
// Never forward or retry an enqueue whose reply was lost.
return uncertainEnqueueResult(op, error);
}
// Another context holds the database, so the enqueue never reached
// an engine. Send it as a disabled cache would.
if (isOwnerLockUnavailableError(error)) {
enqueueTelemetry.failed('owner-lock');
enqueueForward(op);
return undefined;
}
// A cached bin/page may disappear between inspect and enqueue. Do
// not expose a partial relation move: retain entity optimism and
// the post-success revalidation descriptors instead.
if (args.linkPatches.length === 0) {
enqueueTelemetry.failed('rejected');
options.onCacheError?.(error, op);
enqueueForward(op);
return undefined;
}
linkPatchesDegraded = true;
// Deliberately loud: this fallback is durable but invisible until
// reconnect — the mutation's optimistic list membership silently
// becomes eventual. A systematic rejection (schema drift, a patch
// path the cache cannot resolve) looks identical to a transient
// race without this trace, and production wires no onCacheError.
const degraded = new Error(
'optimistic link patches rejected at enqueue; degrading to ' +
`post-commit revalidations for ${args.operationName ?? 'mutation'}`,
{ cause: error }
);
console.warn(`[graphql-cache] ${degraded.message}`, error);
options.onCacheError?.(degraded, op);
try {
enqueue = await host.enqueueOptimisticMutation(
{
...args,
linkPatches: [],
revalidations: [
...args.revalidations,
// Fragment recipes are not executable queries. Their callers
// provide targeted recovery queries in args.revalidations.
...args.linkPatches
.filter((patch) => !patch.recordRoot)
.map((patch) => ({
query: patch.query,
operationName: patch.operationName,
variablesJson: patch.variablesJson,
})),
],
},
claim
);
} catch (fallbackError) {
if (!mutationQueue.isCurrent(epoch)) {
enqueueTelemetry.failed('storage-changed');
return uncertainEnqueueResult(
op,
new Error('cache storage changed during enqueue', {
cause: fallbackError,
})
);
}
options.onCacheError?.(fallbackError, op);
if (isAdmittedEnqueueUncertainError(fallbackError)) {
enqueueTelemetry.failed('uncertain');
return uncertainEnqueueResult(op, fallbackError);
}
enqueueTelemetry.failed('rejected');
enqueueForward(op);
return undefined;
}
}
if (!mutationQueue.isCurrent(epoch)) {
enqueueTelemetry.failed('storage-changed');
return uncertainEnqueueResult(
op,
new Error('cache storage changed during enqueue')
);
}
enqueueTelemetry.persisted({
transactionId: enqueue.transactionId,
replaced: enqueue.upsertKind.kind === 'replaced-pending',
claimed: enqueue.initialClaim.kind === 'claimed',
linkPatchesDegraded,
});
return await mutationQueue.admit(op, enqueue, epoch);
}
/** Applies operation cache effects serially and isolates every failure. */
async function applyOperationCacheEffects(
op: Operation,
effects: CacheEffect[],
isCurrent: () => boolean = () => true,
span?: Span
): Promise<boolean> {
let applied = true;
span?.setAttr('cache.effect_count', effects.length);
for (const effect of effects) {
if (!isCurrent()) return false;
const effectSpan = span?.span(
effect.kind === 'write'
? 'graphql.subscription.cache_write'
: 'graphql.subscription.cache_delete'
);
try {
if (effect.kind === 'write') {
await host.writeQuery({
query: queryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
data: effect.data,
});
} else {
await host.deleteRecords([effect.key]);
}
} catch (error) {
applied = false;
span?.error('Subscription cache effect failed');
span?.setAttr('cache.failure', classifyCacheError(error));
effectSpan?.setAttr('cache.failure', classifyCacheError(error));
// One failed cache effect must neither skip later effects nor
// prevent delivery of the original operation result.
effectSpan?.error('Subscription cache effect failed');
options.onCacheError?.(error, op);
} finally {
effectSpan?.end();
}
}
return applied && isCurrent();
}
// Persistence is still ordered/durable, but foreground query consumers do
// not await it. The acknowledgement carries only a revision: replaying the
// old payload here would overwrite later network or optimistic results.
async function persistQueryResult(
result: OperationResult,
state: QueryState,
resultVersion: number
): Promise<CacheRevision | undefined> {
const op = result.operation;
const releaseTurn = await acquireQueryResultTurn(op.key);
const reportError = (error: unknown): void => {
try {
options.onCacheError?.(error, op);
} catch {
// A diagnostic callback must not reject an unobserved background
// acknowledgement or prevent releasing this query's write turn.
}
};
try {
await invalidateOlderRetainedFallback(state, resultVersion);
// A previous write turn may have delayed this response until after
// mutation settlement, even though publication happened earlier.
if (
predatesMutation(op) ||
predatesExternalWrite(
host,
op.context.externalCacheWriteVersion,
result.data,
op.context.externalCacheWriteTypes
)
) {
refreshObsoleteQuery(op);
return undefined;
}
// Resolver failures must not persist partial nulls as authoritative absence.
if (result.data == null || result.error) return undefined;
const isActive = () =>
queryStates.get(op.key) === state && activeOps.has(op.key);
const writeArgs = {
opKey: op.key,
query: queryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
entityResolvers,
data: result.data,
identity: options.extractIdentity?.(result.data),
registerDependencies: isActive(),
};
const retained: RetainedReplacementFallback | undefined =
result.error === undefined && result.hasNext !== true && isActive()
? {
version: resultVersion,
writeArgs,
readyPending: false,
recovering: false,
invalidated: false,
}
: undefined;
if (retained && state.replacementFallback) {
state.retainedReplacementFallback = retained;
}
try {
const write = await host.writeQuery(writeArgs);
const deletion = await deleteReportedRecords(result);
state.networkRegistrationSatisfied = writeArgs.registerDependencies;
if (host.watchQuery && isActive()) {
const generation = cacheGeneration;
void documentReader
.read(writeArgs)
.then((read) => {
const live = liveQueries.get(op.key);
if (
generation === cacheGeneration &&
read.kind === 'hit' &&
isQueryObject(read.data) &&
isActive() &&
state.networkResultVersion === resultVersion &&
live &&
live.view.snapshot === result.data
) {
live.view.replace(read.data);
}
})
.catch((error) => {
if (!(error instanceof QueryReadInvalidatedError))
reportError(error);
});
}
if (state.retainedReplacementFallback === retained) {
state.retainedReplacementFallback = undefined;
}
return deletion?.revision ?? write.revision;
} catch (error) {
reportError(error);
// An old-owner failure can arrive after this write started. Retain
// only the latest successful response for replacement registration.
if (
retained &&
isActive() &&
state.networkResultVersion === resultVersion &&
(state.replacementFallback || isOwnerEpochLostError(error))
) {
state.replacementFallback = true;
state.retainedReplacementFallback = retained;
}
return undefined;
}
} catch (error) {
reportError(error);
return undefined;
} finally {
try {
if (result.hasNext !== true) {
const registered = state.networkRegistrationSatisfied;
state.networkRegistrationSatisfied = false;
finishNetworkQuery(op.key, state, registered);
}
} catch (error) {
reportError(error);
} finally {
releaseTurn();
}
}
}
async function deleteReportedRecords(result: OperationResult) {
const op = result.operation;
if (result.error || result.hasNext || result.data == null) return;
try {
const keys = options.deletedRecordKeys?.(result) ?? [];
if (keys.length) return await host.deleteRecords(keys);
} catch (error) {
options.onCacheError?.(error, op);
}
}
async function writeThrough(
result: OperationResult
): Promise<OperationResult | undefined> {
const op = result.operation;
if (
op.kind === 'mutation' &&
result.data != null &&
!result.error &&
!result.hasNext
) {
mutationVersion += 1;
}
const output =
op.kind === 'query'
? withResultMetadata(result, { source: 'live-network' })
: result;
if (op.kind === 'subscription' && result.data != null) {
// Serialize effects across every emission for this operation, as
// well as within buffered payloads, so a slower earlier write cannot
// overtake a later delete. Subscribers still receive each original
// result after its effects settle.
const previousEffects =
subscriptionEffectChains.get(op.key) ?? Promise.resolve(true);
const generation = subscriptionGenerations.get(op.key);
const effects = runSubscriptionCacheEffects(
result,
previousEffects,
(span) =>
applyOperationCacheEffects(
op,
operationCacheEffects(result.data),
() =>
generation !== undefined &&
subscriptionGenerations.get(op.key) === generation,
span
)
);
subscriptionEffectChains.set(op.key, effects);
try {
const cacheEffectsApplied = await effects;
return withResultMetadata(result, {
source: 'live-network',
cacheEffectsApplied,
});
} finally {
if (subscriptionEffectChains.get(op.key) === effects) {
subscriptionEffectChains.delete(op.key);
}
}
} else if (op.kind === 'query' && isHydrateOnly(op)) {
if (
predatesMutation(op) ||
predatesExternalWrite(
host,
op.context.externalCacheWriteVersion,
result.data,
op.context.externalCacheWriteTypes
)
) {
if (!result.hasNext && hydrationRequests.has(op.key)) {
enqueueHydrationForward(op);
}
return undefined;
}
if (!result.hasNext) hydrationRequests.delete(op.key);
if (result.error) return { ...result, data: undefined };
if (result.data == null) return result;
try {
const hydration = await host.hydrateQuery({
query: cacheQueryText(op),
operationName: operationName(op),
variables: op.variables as Record<string, unknown> | undefined,
data: result.data,
identity: options.extractIdentity?.(result.data),
entityResolvers,
});
const deletion = await deleteReportedRecords(result);
return withResultMetadata(
{
...result,
data: hydration.kind === 'data' ? hydration.data : undefined,
},
{
source: 'live-network',
revision: deletion?.revision ?? hydration.revision,
}
);
} catch (error) {
options.onCacheError?.(error, op);
return {
...result,
data: undefined,
error: new CombinedError({
networkError:
error instanceof Error ? error : new Error(String(error)),
}),
};
}
} else if (op.kind === 'query') {
const state = queryState(op.key);
if (
predatesMutation(op) ||
predatesExternalWrite(
host,
op.context.externalCacheWriteVersion,
result.data,
op.context.externalCacheWriteTypes
)
) {
if (result.hasNext !== true) {
state.networkRequestsInFlight = Math.max(
0,
state.networkRequestsInFlight - 1
);
refreshObsoleteQuery(op);
finishNetworkQuery(op.key, state, false);
}
return undefined;
}
const version = ++state.networkResultVersion;
if (result.hasNext !== true) {
state.networkRequestsInFlight = Math.max(
0,
state.networkRequestsInFlight - 1
);
}
state.networkError = result.error;
// Publication, not persistence, supersedes an older cache snapshot.
// A failed network request still permits a slower offline cache hit.
if (result.data != null && !result.error) state.cacheReadVersion += 1;
const persistence =
op.context.persistResult === false
? Promise.resolve(undefined)
: persistQueryResult(result, state, version);
return withResultMetadata(result, {
source: 'live-network',
persistence,
});
} else if (op.kind === 'mutation') {
const attempt = queueAttemptOf(op);
if (attempt) return await mutationQueue.settle(result, attempt);
const optimistic = optimisticContextOf(op);
if (result.data != null && !result.error) {
await applyOperationCacheEffects(
op,
operationCacheEffects(result.data)
);
await deleteReportedRecords(result);
}
if (optimistic) {
return withOptimisticMutationDisposition(result, {
kind:
result.data != null && !result.error
? 'committed'
: 'permanently-failed',
});
}
}
return output;
}
const cacheResults$ = pipe(
shared,
filter((op) => op.kind === 'query'),
mergeMap((op) => {
// A contextless same-key revalidation shares the mounted reader's scope.
const types =
op.context.externalCacheWriteTypes ??
activeOps.get(op.key)?.context.externalCacheWriteTypes;
const operation =
types === undefined
? op
: makeOperation('query', op, {
...op.context,
externalCacheWriteTypes: types,
});
if (!isHydrateOnly(operation))
activeOps.set(operation.key, operation);
return pipe(
fromPromise(readThenRoute(operation)),
mergeMap((result) =>
result ? fromValue(result) : (empty as Source<OperationResult>)
)
);
})
);
// Optimistic mutations are held after durable enqueue until the strict
// queue runner claims them. Operations behind the head emit a queued
// disposition immediately; the head emits its network disposition.
const mutationPrep$ = pipe(
shared,
filter((op) => op.kind === 'mutation'),
mergeMap((op) =>
pipe(
fromPromise(prepareMutation(op)),
mergeMap((result) =>
result ? fromValue(result) : (empty as Source<OperationResult>)
)
)
)
);
const passthrough$ = pipe(
shared,
filter((op) => op.kind !== 'query' && op.kind !== 'mutation'),
tap((op) => {
if (op.kind === 'subscription') {
subscriptionGenerations.set(op.key, {});
}
if (op.kind === 'teardown') {
hydrationRequests.delete(op.key);
subscriptionGenerations.delete(op.key);
activeOps.delete(op.key);
liveQueries.delete(op.key);
documentReader.forget(op.key);
queryStates.delete(op.key);
affectedRereads.forget(op.key);
host.teardown(op.key).catch(() => undefined);
}
})
);
const forwarded$ = pipe(
merge([forwardQueue$, passthrough$]),
forward,
mergeMap((result) => fromPromise(writeThrough(result))),
filter((result): result is OperationResult => result !== undefined)
);
if (!host.disabled) {
mutationQueue.start();
// Includes BFCache restoration, even with no active query keys. The
// host gates claims on initialization; durable leases still decide
// which head is runnable after reconnecting.
host.onCacheGenerationChanged((change) => {
cacheGeneration += 1;
if (change.storage === 'reset') mutationQueue.resetStorage();
liveQueries.clear();
documentReader.clear();
mutationQueue.wake();
});
if (typeof addEventListener === 'function') {
addEventListener('online', mutationQueue.wake);
}
}
void unsubscribePush;
return pipe(
merge([affectedResults$, cacheResults$, mutationPrep$, forwarded$]),
map((result) => {
if (
result.operation.kind !== 'query' ||
isHydrateOnly(result.operation) ||
!activeOps.has(result.operation.key)
)
return result;
const current = liveQueries.get(result.operation.key);
// As with persistence, a failed network response (partial nulls or
// no data at all) is not authoritative: mounted readers keep the view
// they hold and later results keep updating it. Cache reads still
// apply when they carry that failure's error.
if (
current &&
result.error !== undefined &&
normalizedCacheResultMetadata(result)?.source === 'live-network'
) {
const liveResult = withLiveQueryData(
{ ...result },
current.view.data
);
liveQueries.set(result.operation.key, {
view: current.view,
result: liveResult,
});
return liveResult;
}
if (
!isQueryObject(result.data) ||
!supportsStoreReconciliation(result.data)
) {
liveQueries.delete(result.operation.key);
return result;
}
const view =
current?.view ??
new LiveQuery(result.data, queryShape(result.operation.query));
if (current) view.replace(result.data);
const liveResult = withLiveQueryData({ ...result }, view.data);
liveQueries.set(result.operation.key, { view, result: liveResult });
return liveResult;
})
);
};
};
}