Files
clean-architecture-frontend…/src/presentation/adapters/query/application-query.ts
T
DongHyeonka 683ccfb56b fix(query): 키 없는 결과 불명 요청의 같은 입력 재제출을 훅이 막는다
문제
0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다.
- useApplicationMutation의 submit은 같은 canonical input의 결과 불명
  admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면
  서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과
  두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은
  항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이
  두 번째 POST를 보냈고 keys=[null,null]).
- AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을
  그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을
  그린다(실험 X3).

고른 방법
- submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면
  보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를
  돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다.
  KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트
  하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다.
- AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다.
  코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect).
- 기존 async-surface 테스트 "renders unknown mutation effects with
  confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이
  수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다.
- 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다.

버린 대안
FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다.
"같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로
충분하다.

위험·한계
- 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를
  넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다.
- 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다
  (런북 6.3-7의 한계 그대로).

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx
tests/component/async-surface.test.tsx tests/component/application-query.test.tsx

Refs: 0929/03-03
2026-11-06 02:33:16 +09:00

1027 lines
34 KiB
TypeScript

import {
useCallback,
useEffect,
useMemo,
useState,
useSyncExternalStore,
} from "react";
import {
hashKey,
type QueryClient,
useMutation,
useQuery,
useQueryClient,
} from "@tanstack/react-query";
import {
deriveAsyncState,
type AsyncState,
} from "../../../application/view-models/async-state.ts";
import type { Result } from "../../../contracts/result.ts";
import {
createFailure,
normalizeUnknownFailure,
withFailureEffect,
type AppFailure,
} from "../../../contracts/errors.ts";
import type {
QueryInvalidationCoordinator,
QueryInvalidationTopic,
} from "../../../contracts/query-invalidation.ts";
import type { MutationIntent } from "../../../contracts/mutation-intent.ts";
import type { CacheScopeSnapshot } from "../../../contracts/server-state-scope.ts";
import {
admitQueryResult,
type BoundMutation,
type BoundQuery,
MUTATION_COORDINATOR_BOUNDS,
type MutationDuplicatePolicy,
} from "../../../contracts/server-state.ts";
import {
QUERY_WITHOUT_INVALIDATION_META,
runtimeIdentityToken,
} from "../../../contracts/query-keys.ts";
import { useQueryInvalidationCoordinator } from "./query-invalidation-provider.tsx";
import { useMutationIntentFactory } from "./mutation-intent-provider.tsx";
import {
createOptimisticLayerRuntime,
type OptimisticLayerLease,
} from "./optimistic-layer-runtime.ts";
export type ApplicationResult<Value> = Result<Value>;
class ApplicationQueryError extends Error {
readonly failure: AppFailure;
constructor(failure: AppFailure) {
super(failure.kind);
this.name = "ApplicationQueryError";
this.failure = failure;
}
}
/**
* Prefer a `BoundQuery` (`bindQuery`).
*
* The raw `{ queryKey, execute }` form is a read path that runs without a
* scope and without a measurement profile: no generation check around
* `execute`, no result-size limit, default stale and gc times, and a key that
* carries no scope fingerprint. It does not show the previous session's answer
* only because `ServerStateGenerationProvider` unmounts it on FENCED and mounts
* it again on the next generation's empty QueryClient
* (`server-state-generation-provider.test.tsx`). Outside that provider nothing
* in this hook fences it. Kept for reads only (1101/08-03): a read can be sent
* again without side effects; a raw write cannot.
*/
export function useApplicationQuery<Value>(
options:
| BoundQuery<Value>
| Readonly<{
queryKey: readonly unknown[];
execute(context: Readonly<{ signal: AbortSignal }>): Promise<
ApplicationResult<Value>
>;
enabled?: boolean;
}>,
): Readonly<{
data: Value | undefined;
state: AsyncState;
retry(): Promise<void>;
}> {
const { queryKey, execute } = options;
const enabled = "enabled" in options ? options.enabled ?? true : true;
const profile = "profile" in options ? options.profile : undefined;
const scope = "scope" in options ? options.scope : undefined;
const identity = "identity" in options ? options.identity : undefined;
const measureResult =
"measureResult" in options ? options.measureResult : undefined;
const queryDefinitionId =
"definitionId" in options ? options.definitionId : "APPLICATION_QUERY";
const invalidation =
"invalidation" in options ? options.invalidation : undefined;
const [staleFailure, setStaleFailure] = useState(false);
useEffect(() => {
identity?.acquire();
return () => identity?.release();
}, [identity]);
const query = useQuery<Value, ApplicationQueryError>({
queryKey,
enabled,
...(invalidation === "NONE"
? { meta: QUERY_WITHOUT_INVALIDATION_META }
: {}),
retry: false,
staleTime: profile?.staleTimeMs,
gcTime: profile?.gcTimeMs,
refetchOnMount: profile?.refetchOnMount,
refetchOnWindowFocus: profile?.refetchOnFocus,
refetchOnReconnect: profile?.refetchOnReconnect,
queryFn: async ({ signal }) => {
identity?.acquire();
try {
if (scope && !scope.isCurrent()) {
throw new ApplicationQueryError(
createFailure(
"SCOPE_GENERATION_CHANGED",
queryDefinitionId,
0,
{ code: "QUERY_SCOPE_STALE" },
),
);
}
const result = await execute({ signal });
if (scope && !scope.isCurrent()) {
throw new ApplicationQueryError(
createFailure(
"SCOPE_GENERATION_CHANGED",
queryDefinitionId,
0,
{ code: "QUERY_SCOPE_CHANGED" },
),
);
}
if (result.ok) {
if (profile && measureResult) {
const admission = admitQueryResult(
measureResult,
result.value,
profile,
);
if (!admission.ok) {
throw new ApplicationQueryError(
createFailure(
"RESULT_LIMIT_EXCEEDED",
queryDefinitionId,
0,
{ code: admission.code },
),
);
}
}
return result.value;
}
if (signal.aborted) {
throw new DOMException("Query cancelled", "AbortError");
}
throw new ApplicationQueryError(result.error);
} catch (error) {
if (signal.aborted) {
throw new DOMException("Query cancelled", "AbortError");
}
if (error instanceof ApplicationQueryError) throw error;
throw new ApplicationQueryError(
normalizeUnknownFailure(error, {
operationId: "APPLICATION_QUERY",
}),
);
} finally {
identity?.release();
}
},
});
const hasData = query.data !== undefined && query.data !== null;
useEffect(() => {
if (query.isError && hasData) {
setStaleFailure(true);
} else if (query.isSuccess && !query.isFetching) {
setStaleFailure(false);
}
}, [hasData, query.isError, query.isFetching, query.isSuccess]);
const retry = useCallback(async () => {
setStaleFailure(false);
await query.refetch({ cancelRefetch: false });
}, [query]);
return Object.freeze({
data: query.data,
state: deriveAsyncState({
data: query.data,
// A disabled query is pending but idle; a paused offline first load is
// pending and still waiting, which `isLoading` would miss.
isInitialLoading: query.isPending && query.fetchStatus !== "idle",
failure:
!hasData && query.error instanceof ApplicationQueryError
? query.error.failure
: undefined,
isFetching: query.isFetching && !query.isPending,
isStale: staleFailure,
isDegraded: staleFailure,
}),
retry,
});
}
type LegacyMutationBase<Input, Value> = Readonly<{
execute(input: Input): Promise<ApplicationResult<Value>>;
duplicatePolicy?: MutationDuplicatePolicy;
invalidate?: readonly QueryInvalidationTopic[];
currentData?: unknown;
}>;
/**
* 1101/08-03. Raw mutation input: no scope, no intent, no `Idempotency-Key`,
* and `resendUnknownEffect()` resolves to `null`. `useApplicationMutation`
* rejects it; only the test harness passes it, by cast.
*/
export type LegacyMutationOptions<Input, Value> = LegacyMutationBase<Input, Value> &
(
| Readonly<{
/** Stable logical identity required to retain an unknown effect across remounts. */
definitionId: string;
optimistic?: never;
}>
| Readonly<{
definitionId?: string;
optimistic: Readonly<{
queryKey: readonly unknown[];
update(previous: unknown, input: Input): unknown;
}>;
}>
);
type ApplicationMutationController<Input, Value> = Readonly<{
state: AsyncState;
/**
* D-1. The same canonical input as an unknown-effect request is the same
* logical request: a keyed command sends it again with that request's
* key. 0929/03-03. Without a key it is not sent: the result is a
* `NOT_STARTED` `DUPLICATE_IN_FLIGHT` failure with code
* `UNKNOWN_EFFECT_PENDING` until the unknown request is reconciled.
*/
submit(input: Input): Promise<ApplicationResult<Value>>;
resolveConflict(): Promise<void>;
/**
* Settles the oldest unknown effect. `NOT_APPLIED` needs evidence (an
* inspect operation or a server read); without it, resend instead.
*/
reconcileUnknownEffect(
resolution: "APPLIED" | "NOT_APPLIED",
): Promise<void>;
/**
* D-1. Sends the oldest unknown-effect request again with its original
* intent, so a keyed command carries the same `Idempotency-Key`. Resolves
* to `null` when nothing is waiting to be resent, and (0929/03-03) when
* that request has no key: the server could not tell a second one from a
* new request, so it could apply twice.
*/
resendUnknownEffect(): Promise<ApplicationResult<Value> | null>;
/**
* 0929/03-03. `resendUnknownEffect` would send: the oldest request is
* unknown, carries an idempotency key and is not being reconciled.
* `state.unknownEffectResendable` carries the same answer to `AsyncSurface`.
*/
canResendUnknownEffect: boolean;
}>;
type MutationExecution<Input> =
| Readonly<{ kind: "BOUND"; input: Input; intent: MutationIntent }>
| Readonly<{ kind: "LEGACY"; input: Input }>;
type MutationAdmission = {
sequence: number;
state: "ACTIVE" | "UNKNOWN" | "RECONCILING" | "SETTLED";
readonly input: unknown;
intent: MutationIntent | null;
/** Held while UNKNOWN so the same input keeps the same identity token. */
identityLease: Readonly<{ release(): void }> | null;
/** `performance.now()` before which a resend waits (see RESEND_WAIT_CEILING_MS). */
resendNotBefore: number;
scope: CacheScopeSnapshot | null;
optimisticLayer: OptimisticLayerLease | null;
optimisticQueryKey: readonly unknown[] | null;
readonly invalidate: readonly QueryInvalidationTopic[];
invalidationCoordinator: QueryInvalidationCoordinator | null;
};
type UnknownEffectChannel = {
readonly key: string;
readonly registry: UnknownEffectRegistry;
readonly owner: QueryClient;
readonly scope: CacheScopeSnapshot | null;
nextSequence: number;
admissions: MutationAdmission[];
version: number;
reconciliationInFlight: boolean;
readonly listeners: Set<() => void>;
disposeScopeListener: (() => void) | null;
};
type UnknownEffectRegistry = {
readonly channels: Map<string, UnknownEffectChannel>;
activeAdmissions: number;
};
/**
* 백엔드 1101/02-01. An unknown answer may say when to ask again: the paired
* backend answers a same-key request while the first still runs with
* `409 IDEMPOTENT_IN_FLIGHT` and `Retry-After: 2`. A resend (the resend
* button, or saving the same input) before then only meets the same 409, so
* it waits, shown as pending. The wait is capped: an early resend carries the
* same key, so the server answers it again and never applies it twice.
* Same ceiling as the V3 executor's own Retry-After retries.
*/
const RESEND_WAIT_CEILING_MS = 5_000;
const LEGACY_OPTIMISTIC_SCOPE = Object.freeze({
isCurrent: () => true,
});
/**
* Takes a bound definition only (1101/08-03): the binding supplies the scope
* check, the intent and its `Idempotency-Key`, so a resend after an unknown
* result sends the same key.
*/
export function useApplicationMutation<Input, Value>(
options: BoundMutation<Input, Value>,
): ApplicationMutationController<Input, Value>;
// 1101/08-03. The raw (LEGACY) shape below is no longer a public overload. The
// runtime branch stays so `tests/helpers/legacy-application-query-harness.ts`
// keeps its assertions; reaching it takes an explicit cast. Removing the
// branch changes those tests and is a separate step.
export function useApplicationMutation<Input, Value>(
options: BoundMutation<Input, Value> | LegacyMutationOptions<Input, Value>,
): ApplicationMutationController<Input, Value> {
const queryClient = useQueryClient();
const invalidationCoordinator = useQueryInvalidationCoordinator();
const mutationIntentFactory = useMutationIntentFactory();
const invalidate = useMemo(
() => options.invalidate ?? [],
[options.invalidate],
);
const optimistic = "optimistic" in options ? options.optimistic : undefined;
const currentData = "currentData" in options ? options.currentData : undefined;
const definitionId =
"definitionId" in options
? options.definitionId ?? "LEGACY_MUTATION"
: "LEGACY_MUTATION";
const definitionVersion =
"definitionVersion" in options ? options.definitionVersion : 0;
const duplicatePolicy =
"duplicatePolicy" in options ? options.duplicatePolicy : "REJECT_WHILE_ACTIVE";
const [conflict, setConflict] = useState<AppFailure | null>(null);
const scope = "scope" in options ? options.scope : undefined;
const mutationOperationId =
"operationId" in options ? options.operationId : definitionId;
const requiresIdempotencyKey =
"requiresIdempotencyKey" in options
? options.requiresIdempotencyKey
: false;
const unknownEffectChannelKey = scope
? `bound:${scope.generation}:${scope.fingerprint}:${definitionId}:${definitionVersion}`
: `legacy:${definitionId}:${
optimistic
? hashKey(optimistic.queryKey)
: "non-optimistic"
}`;
const [acquiredUnknownEffectChannel, setAcquiredUnknownEffectChannel] =
useState<UnknownEffectChannel | null>(null);
const unknownEffectChannel =
acquiredUnknownEffectChannel?.owner === queryClient &&
acquiredUnknownEffectChannel.key === unknownEffectChannelKey &&
acquiredUnknownEffectChannel.scope === (scope ?? null)
? acquiredUnknownEffectChannel
: null;
useEffect(() => {
const acquired = acquireUnknownEffectChannel(
queryClient,
unknownEffectChannelKey,
scope,
);
setAcquiredUnknownEffectChannel(acquired);
return () => {
if (acquired) {
releaseUnknownEffectChannelIfUnused(queryClient, acquired);
}
};
}, [queryClient, scope, unknownEffectChannelKey]);
const subscribeToUnknownEffects = useCallback(
(listener: () => void) => {
if (!unknownEffectChannel) return () => {};
unknownEffectChannel.listeners.add(listener);
return () => {
unknownEffectChannel.listeners.delete(listener);
releaseUnknownEffectChannelIfUnused(
queryClient,
unknownEffectChannel,
);
};
},
[queryClient, unknownEffectChannel],
);
useSyncExternalStore(
subscribeToUnknownEffects,
() => unknownEffectChannel?.version ?? 0,
() => unknownEffectChannel?.version ?? 0,
);
const mutation = useMutation<
Value,
ApplicationQueryError,
MutationExecution<Input>
>({
retry: false,
mutationFn: async (execution) => {
const input = execution.input;
if (scope && !scope.isCurrent()) {
throw new ApplicationQueryError(
createFailure(
"SCOPE_GENERATION_CHANGED",
definitionId,
0,
{ code: "MUTATION_SCOPE_STALE", effect: "NOT_STARTED" },
),
);
}
const result =
"scope" in options
? await options.execute(input, {
signal: options.scope.signal,
intent:
execution.kind === "BOUND"
? execution.intent
: (() => {
throw new TypeError(
"Bound mutation execution requires an intent.",
);
})(),
})
: await options.execute(input);
if (scope && !scope.isCurrent()) {
const effect =
!result.ok && result.error.effect !== undefined
? result.error.effect
: "MAYBE_APPLIED";
throw new ApplicationQueryError(
createFailure(
"SCOPE_GENERATION_CHANGED",
definitionId,
0,
{ code: "MUTATION_SCOPE_CHANGED", effect },
),
);
}
if (result.ok) return result.value;
throw new ApplicationQueryError(result.error);
},
});
const submit = useCallback(
(input: Input): Promise<ApplicationResult<Value>> => {
let identity: string;
let identityLease: ReturnType<
NonNullable<typeof scope>["identities"]["intern"]
> | null = null;
try {
if (scope) {
if (!scope.isCurrent()) {
return Promise.resolve({
ok: false,
error: createFailure(
"SCOPE_GENERATION_CHANGED",
definitionId,
0,
{ code: "MUTATION_SCOPE_STALE", effect: "NOT_STARTED" },
),
});
}
identityLease = scope.identities.intern(input);
identityLease.acquire();
identity = `${scope.fingerprint}:${definitionId}:${identityLease.token}`;
} else {
identity = `${definitionId}:${runtimeIdentityToken(input)}`;
}
} catch (error) {
return Promise.resolve({
ok: false,
error: withFailureEffect(
normalizeUnknownFailure(error, {
operationId: definitionId,
}),
"NOT_STARTED",
),
});
}
const active = mutationExecutions(queryClient).get(identity) as
| RuntimeMutationExecution<Value>
| undefined;
if (active && duplicatePolicy === "JOIN_IDENTICAL") {
if (
active.joinedWaiters >=
MUTATION_COORDINATOR_BOUNDS.waitersPerJoinedIntent
) {
identityLease?.release();
return Promise.resolve({
ok: false,
error: createFailure(
"DUPLICATE_IN_FLIGHT",
definitionId,
0,
{
code: "JOIN_WAITER_LIMIT_EXCEEDED",
effect: "NOT_STARTED",
},
),
});
}
active.joinedWaiters += 1;
identityLease?.release();
return active.promise;
}
if (active && duplicatePolicy === "REJECT_WHILE_ACTIVE") {
identityLease?.release();
return Promise.resolve({
ok: false,
error: createFailure(
"DUPLICATE_IN_FLIGHT",
definitionId,
0,
{ code: "DUPLICATE_IN_FLIGHT", effect: "NOT_STARTED" },
),
});
}
if (
!unknownEffectChannel ||
unknownEffectChannel.registry.activeAdmissions >=
MUTATION_COORDINATOR_BOUNDS.activeIntentsTotal
) {
identityLease?.release();
return Promise.resolve({
ok: false,
error: createFailure(
"IDENTITY_INTERN_LIMIT_EXCEEDED",
definitionId,
0,
{
code: "UNKNOWN_EFFECT_CHANNEL_LIMIT_EXCEEDED",
effect: "NOT_STARTED",
},
),
});
}
// D-1. Saving the same canonical input again is the same logical
// request: it reuses the unknown admission's intent (and key).
const replayed = unknownEffectChannel.admissions.find(
(candidate) =>
candidate.state === "UNKNOWN" &&
candidate.intent?.canonicalInputIdentity === identity,
);
// 0929/03-03. Without an idempotency key the server cannot tell that
// request from this one, so saving the same input again could apply it
// twice. The unknown request is settled first (reconcileUnknownEffect),
// never repeated; a page that calls submit outside the form meets this
// too.
if (replayed && replayed.intent?.idempotencyKey === undefined) {
identityLease?.release();
return Promise.resolve({
ok: false,
error: createFailure("DUPLICATE_IN_FLIGHT", definitionId, 0, {
code: "UNKNOWN_EFFECT_PENDING",
effect: "NOT_STARTED",
}),
});
}
const admission: MutationAdmission = {
sequence: unknownEffectChannel.nextSequence++,
state: "ACTIVE",
input,
intent: null,
identityLease: null,
resendNotBefore: 0,
scope: scope ?? null,
optimisticLayer: null,
optimisticQueryKey: optimistic?.queryKey ?? null,
invalidate,
invalidationCoordinator: invalidationCoordinator ?? null,
};
unknownEffectChannel.admissions.push(admission);
unknownEffectChannel.registry.activeAdmissions += 1;
if (replayed) {
// The new attempt re-applies its own optimistic layer and owns the
// outcome from here.
replayed.optimisticLayer?.reconcile("NOT_APPLIED");
settleMutationAdmission(unknownEffectChannel, replayed);
}
notifyUnknownEffectChannel(unknownEffectChannel);
setConflict(null);
mutation.reset();
let runtimeExecution: RuntimeMutationExecution<Value> | undefined;
const pending = (async (): Promise<ApplicationResult<Value>> => {
let execution: MutationExecution<Input>;
if (scope) {
const intent =
replayed?.intent ??
mutationIntentFactory.create({
operationId: mutationOperationId,
canonicalInputIdentity: identity,
requiresIdempotencyKey,
});
admission.intent = intent;
execution = Object.freeze({ kind: "BOUND", input, intent });
} else {
execution = Object.freeze({ kind: "LEGACY", input });
}
const mutationLease =
invalidate.length === 0
? null
: invalidationCoordinator?.beginMutation(invalidate);
if (invalidate.length > 0 && !mutationLease) {
throw new Error("Query invalidation coordinator is not installed.");
}
try {
let optimisticLayer: OptimisticLayerLease | null = null;
if (optimistic) {
await queryClient.cancelQueries({
queryKey: optimistic.queryKey,
exact: true,
});
optimisticLayer = optimisticLayers(queryClient).begin(
optimistic.queryKey,
input,
optimistic.update,
scope ?? LEGACY_OPTIMISTIC_SCOPE,
);
admission.optimisticLayer = optimisticLayer;
}
const resendWaitMs =
(replayed?.resendNotBefore ?? 0) - performance.now();
if (resendWaitMs > 0) {
await new Promise<void>((resolve) => {
setTimeout(resolve, resendWaitMs);
});
}
let value: Value;
try {
value = await mutation.mutateAsync(execution);
} catch (error: unknown) {
const reportedFailure =
error instanceof ApplicationQueryError
? error.failure
: normalizeUnknownFailure(error, {
operationId: "APPLICATION_MUTATION",
});
const failure = mutationFailureWithEffect(reportedFailure);
switch (failure.effect) {
case "NOT_STARTED":
case "NOT_APPLIED":
optimisticLayer?.rollback();
if (failure.kind === "CONFLICT") setConflict(failure);
settleMutationAdmission(unknownEffectChannel, admission);
break;
case "APPLIED_CONFIRMED":
optimisticLayer?.commit();
if (!scope || scope.isCurrent()) {
try {
await invalidationCoordinator?.invalidate(invalidate);
} catch {
// A confirmed command remains committed if refresh fails.
}
}
settleMutationAdmission(unknownEffectChannel, admission);
break;
case "MAYBE_APPLIED":
optimisticLayer?.markUncertain();
if (!scope || scope.isCurrent()) {
admission.state = "UNKNOWN";
admission.resendNotBefore =
performance.now() +
Math.min(failure.retryAfterMs ?? 0, RESEND_WAIT_CEILING_MS);
if (identityLease) {
identityLease.acquire();
admission.identityLease = identityLease;
}
notifyUnknownEffectChannel(unknownEffectChannel);
} else {
settleMutationAdmission(unknownEffectChannel, admission);
}
break;
}
return { ok: false, error: failure };
}
optimisticLayer?.commit();
try {
await invalidationCoordinator?.invalidate(invalidate);
} catch {
// Cache refresh remains best effort after the server has committed.
}
settleMutationAdmission(unknownEffectChannel, admission);
return { ok: true, value };
} finally {
try {
await mutationLease?.release();
} catch {
// A cache coordination defect cannot change the committed command.
}
}
})()
.catch((error: unknown) => {
const failure = withFailureEffect(
normalizeUnknownFailure(error, {
operationId: "APPLICATION_MUTATION",
}),
"NOT_STARTED",
);
settleMutationAdmission(unknownEffectChannel, admission);
if (failure.kind === "CONFLICT") setConflict(failure);
return { ok: false as const, error: failure };
})
.finally(() => {
identityLease?.release();
if (
runtimeExecution &&
mutationExecutions(queryClient).get(identity) === runtimeExecution
) {
mutationExecutions(queryClient).delete(identity);
}
});
if (duplicatePolicy !== "ALLOW_PARALLEL") {
runtimeExecution = { promise: pending, joinedWaiters: 0 };
mutationExecutions(queryClient).set(identity, runtimeExecution);
}
return pending;
},
[
invalidate,
invalidationCoordinator,
mutation,
optimistic,
queryClient,
definitionId,
duplicatePolicy,
mutationIntentFactory,
mutationOperationId,
requiresIdempotencyKey,
scope,
unknownEffectChannel,
],
);
const resolveConflict = useCallback(async () => {
setConflict(null);
mutation.reset();
if (invalidate.length > 0 && !invalidationCoordinator) {
throw new Error("Query invalidation coordinator is not installed.");
}
await invalidationCoordinator?.invalidate(invalidate);
}, [invalidate, invalidationCoordinator, mutation]);
const reconcileUnknownEffect = useCallback(
async (resolution: "APPLIED" | "NOT_APPLIED") => {
if (
!unknownEffectChannel ||
unknownEffectChannel.reconciliationInFlight
) {
return;
}
const pending = unknownEffectChannel.admissions[0];
if (!pending || pending.state !== "UNKNOWN") return;
if (pending.scope && !pending.intent) return;
unknownEffectChannel.reconciliationInFlight = true;
pending.state = "RECONCILING";
notifyUnknownEffectChannel(unknownEffectChannel);
try {
pending.optimisticLayer?.reconcile(resolution);
if (
resolution === "APPLIED" &&
(!pending.scope || pending.scope.isCurrent())
) {
try {
await pending.invalidationCoordinator?.invalidate(
pending.invalidate,
);
} catch {
// Explicit reconciliation remains settled if refresh fails.
}
}
} finally {
if (pending.scope && !pending.scope.isCurrent()) {
removeAdmissionOptimisticQuery(queryClient, pending);
}
settleMutationAdmission(unknownEffectChannel, pending);
if (
!unknownEffectChannel.admissions.some(
(admission) => admission.state === "ACTIVE",
)
) {
mutation.reset();
}
// Keep the head intent locked through the current event turn so two
// clicks cannot consume two FIFO records when reconciliation itself
// has no asynchronous invalidation work.
await Promise.resolve();
unknownEffectChannel.reconciliationInFlight = false;
notifyUnknownEffectChannel(unknownEffectChannel);
}
},
[mutation, queryClient, unknownEffectChannel],
);
const resendUnknownEffect = useCallback(async () => {
const head = unknownEffectChannel?.admissions[0];
if (!head || !canResend(unknownEffectChannel, head)) return null;
return submit(head.input as Input);
}, [submit, unknownEffectChannel]);
const unknownEffectHead = unknownEffectChannel?.admissions[0];
const canResendUnknownEffect =
unknownEffectChannel !== null &&
unknownEffectHead !== undefined &&
canResend(unknownEffectChannel, unknownEffectHead);
return Object.freeze({
state: deriveAsyncState({
data: currentData ?? true,
isMutationPending:
mutation.isPending ||
unknownEffectHead?.state === "ACTIVE" ||
unknownEffectHead?.state === "RECONCILING",
hasMutationEffectUnknown: unknownEffectHead?.state === "UNKNOWN",
isUnknownEffectResendable: canResendUnknownEffect,
hasMutationConflict: conflict !== null,
}),
submit,
resolveConflict,
reconcileUnknownEffect,
resendUnknownEffect,
canResendUnknownEffect,
});
}
/**
* D-1 / 0929/03-03. A resend repeats the unknown request with its original
* intent. Without an idempotency key (a `NEVER` command) nothing lets the
* server recognise the repeat, so it is not offered.
*/
function canResend(
channel: UnknownEffectChannel,
head: MutationAdmission,
): boolean {
return (
head.state === "UNKNOWN" &&
head.intent?.idempotencyKey !== undefined &&
!channel.reconciliationInFlight
);
}
function mutationFailureWithEffect(failure: AppFailure): AppFailure {
switch (failure.effect) {
case "NOT_STARTED":
case "NOT_APPLIED":
case "APPLIED_CONFIRMED":
case "MAYBE_APPLIED":
return withFailureEffect(failure, failure.effect);
case "NOT_APPLICABLE":
case undefined:
return withFailureEffect(failure, "MAYBE_APPLIED");
}
}
const UNKNOWN_EFFECT_CHANNELS = new WeakMap<
object,
UnknownEffectRegistry
>();
function acquireUnknownEffectChannel(
queryClient: QueryClient,
key: string,
scope: CacheScopeSnapshot | undefined,
): UnknownEffectChannel | null {
let registry = UNKNOWN_EFFECT_CHANNELS.get(queryClient);
if (!registry) {
registry = { channels: new Map(), activeAdmissions: 0 };
UNKNOWN_EFFECT_CHANNELS.set(queryClient, registry);
}
const { channels } = registry;
const existing = channels.get(key);
if (existing) return existing.scope === (scope ?? null) ? existing : null;
if (
channels.size >= MUTATION_COORDINATOR_BOUNDS.activeDefinitionsPerRuntime
) {
return null;
}
const created: UnknownEffectChannel = {
key,
registry,
owner: queryClient,
scope: scope ?? null,
nextSequence: 1,
admissions: [],
version: 0,
reconciliationInFlight: false,
listeners: new Set(),
disposeScopeListener: null,
};
channels.set(key, created);
if (scope) {
const discardScope = () => {
for (const admission of created.admissions) {
removeAdmissionOptimisticQuery(queryClient, admission);
markMutationAdmissionSettled(created, admission);
}
created.admissions = [];
notifyUnknownEffectChannel(created);
releaseUnknownEffectChannelIfUnused(queryClient, created);
};
scope.signal.addEventListener("abort", discardScope, { once: true });
created.disposeScopeListener = () =>
scope.signal.removeEventListener("abort", discardScope);
if (scope.signal.aborted || !scope.isCurrent()) discardScope();
}
return created;
}
function releaseUnknownEffectChannelIfUnused(
queryClient: QueryClient,
channel: UnknownEffectChannel,
): void {
if (channel.admissions.length > 0 || channel.listeners.size > 0) return;
const registry = UNKNOWN_EFFECT_CHANNELS.get(queryClient);
const channels = registry?.channels;
if (channels?.get(channel.key) !== channel) return;
channel.disposeScopeListener?.();
channels.delete(channel.key);
if (channels.size === 0 && registry?.activeAdmissions === 0) {
UNKNOWN_EFFECT_CHANNELS.delete(queryClient);
}
}
function notifyUnknownEffectChannel(channel: UnknownEffectChannel): void {
channel.version += 1;
for (const listener of [...channel.listeners]) listener();
}
function settleMutationAdmission(
channel: UnknownEffectChannel,
admission: MutationAdmission,
): void {
markMutationAdmissionSettled(channel, admission);
while (channel.admissions[0]?.state === "SETTLED") {
channel.admissions.shift();
}
notifyUnknownEffectChannel(channel);
releaseUnknownEffectChannelIfUnused(channel.owner, channel);
}
function markMutationAdmissionSettled(
channel: UnknownEffectChannel,
admission: MutationAdmission,
): void {
if (admission.state === "SETTLED") return;
admission.state = "SETTLED";
admission.identityLease?.release();
admission.identityLease = null;
channel.registry.activeAdmissions = Math.max(
0,
channel.registry.activeAdmissions - 1,
);
}
function removeAdmissionOptimisticQuery(
queryClient: QueryClient,
admission: MutationAdmission,
): void {
if (!admission.optimisticQueryKey) return;
queryClient.removeQueries({
queryKey: admission.optimisticQueryKey,
exact: true,
});
}
type RuntimeMutationExecution<Value = unknown> = {
promise: Promise<ApplicationResult<Value>>;
joinedWaiters: number;
};
const RUNTIME_MUTATION_EXECUTIONS = new WeakMap<
object,
Map<string, RuntimeMutationExecution>
>();
function mutationExecutions(
owner: object,
): Map<string, RuntimeMutationExecution> {
const existing = RUNTIME_MUTATION_EXECUTIONS.get(owner);
if (existing) return existing;
const created = new Map<string, RuntimeMutationExecution>();
RUNTIME_MUTATION_EXECUTIONS.set(owner, created);
return created;
}
const OPTIMISTIC_LAYER_RUNTIMES = new WeakMap<
object,
ReturnType<typeof createOptimisticLayerRuntime>
>();
function optimisticLayers(
queryClient: Parameters<typeof createOptimisticLayerRuntime>[0],
): ReturnType<typeof createOptimisticLayerRuntime> {
const existing = OPTIMISTIC_LAYER_RUNTIMES.get(queryClient);
if (existing) return existing;
const created = createOptimisticLayerRuntime(queryClient);
OPTIMISTIC_LAYER_RUNTIMES.set(queryClient, created);
return created;
}