2197 lines
71 KiB
TypeScript
2197 lines
71 KiB
TypeScript
// @vitest-environment jsdom
|
|
|
|
import {
|
|
act,
|
|
renderHook,
|
|
waitFor,
|
|
} from "@testing-library/react";
|
|
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
|
import type { ReactNode } from "react";
|
|
import { renderToString } from "react-dom/server";
|
|
import { describe, expect, it, vi } from "vitest";
|
|
|
|
import {
|
|
type ApplicationResult,
|
|
useApplicationMutation,
|
|
useApplicationQuery,
|
|
} from "../../src/presentation/adapters/query/application-query.ts";
|
|
import type { MutationIntentFactory } from "../../src/application/ports/mutation-intent-factory.ts";
|
|
import { MutationIntentProvider } from "../../src/presentation/adapters/query/mutation-intent-provider.tsx";
|
|
import { QueryInvalidationProvider } from "../../src/presentation/adapters/query/query-invalidation-provider.tsx";
|
|
import {
|
|
defineQueryInvalidationTopic,
|
|
type QueryInvalidationCoordinator,
|
|
} from "../../src/contracts/query-invalidation.ts";
|
|
import { createFailure } from "../../src/contracts/errors.ts";
|
|
import {
|
|
createQueryInvalidationPrefix,
|
|
createRuntimeIdentityRegistry,
|
|
defineQueryNamespaceIdentity,
|
|
} from "../../src/contracts/query-keys.ts";
|
|
import {
|
|
bindQuery,
|
|
MUTATION_COORDINATOR_BOUNDS,
|
|
type QueryResultMeasure,
|
|
} from "../../src/contracts/server-state.ts";
|
|
import type { CacheScopeSnapshot } from "../../src/contracts/server-state-scope.ts";
|
|
|
|
const RESOURCE_INVALIDATION_TOPIC =
|
|
defineQueryInvalidationTopic("resource");
|
|
|
|
/**
|
|
* §24.12: the scope-bound commit fence is common runtime, so it is verified
|
|
* here with a local scope fixture rather than through the removable sample
|
|
* feature.
|
|
*/
|
|
function scopeSnapshot(
|
|
generation = 1,
|
|
fingerprint = "scope-fingerprint-0001",
|
|
): CacheScopeSnapshot & { fence(): void } {
|
|
let current = true;
|
|
const lifetime = new AbortController();
|
|
const identities = createRuntimeIdentityRegistry({
|
|
tokenFactory: () => "scope-identity-token-0001",
|
|
});
|
|
return {
|
|
generation,
|
|
fingerprint,
|
|
identities,
|
|
signal: lifetime.signal,
|
|
isCurrent: () => current,
|
|
fence() {
|
|
current = false;
|
|
lifetime.abort();
|
|
},
|
|
};
|
|
}
|
|
|
|
function measureOne(): QueryResultMeasure {
|
|
return { itemCount: 1, estimatedBytes: 8 };
|
|
}
|
|
|
|
function queryClient() {
|
|
return new QueryClient({
|
|
defaultOptions: {
|
|
queries: { retry: false, staleTime: 0, gcTime: Infinity },
|
|
mutations: { retry: false },
|
|
},
|
|
});
|
|
}
|
|
|
|
function deterministicMutationIntentFactory(): MutationIntentFactory {
|
|
let sequence = 0;
|
|
return Object.freeze({
|
|
create(input) {
|
|
sequence += 1;
|
|
return Object.freeze({
|
|
intentId: `intent-${sequence}`,
|
|
operationId: input.operationId,
|
|
canonicalInputIdentity: input.canonicalInputIdentity,
|
|
...(input.requiresIdempotencyKey
|
|
? { idempotencyKey: `key-${sequence}` }
|
|
: {}),
|
|
createdAtMonotonicMs: sequence,
|
|
});
|
|
},
|
|
});
|
|
}
|
|
|
|
function wrapper(
|
|
client: QueryClient,
|
|
mutationIntentFactory = deterministicMutationIntentFactory(),
|
|
) {
|
|
const coordinator: QueryInvalidationCoordinator = {
|
|
async invalidate(topics) {
|
|
for (const topic of topics) {
|
|
await client.invalidateQueries({
|
|
queryKey: [topic],
|
|
exact: false,
|
|
refetchType: "active",
|
|
});
|
|
}
|
|
},
|
|
beginMutation() {
|
|
return { release: async () => {} };
|
|
},
|
|
async resetLocal() {
|
|
await client.cancelQueries();
|
|
client.clear();
|
|
},
|
|
dispose() {},
|
|
};
|
|
return function QueryWrapper({ children }: { children: ReactNode }) {
|
|
return (
|
|
<MutationIntentProvider factory={mutationIntentFactory}>
|
|
<QueryClientProvider client={client}>
|
|
<QueryInvalidationProvider coordinator={coordinator}>
|
|
{children}
|
|
</QueryInvalidationProvider>
|
|
</QueryClientProvider>
|
|
</MutationIntentProvider>
|
|
);
|
|
};
|
|
}
|
|
|
|
describe("application query inbound bridge", () => {
|
|
it("latches a background failure over stale data and clears it on retry success", async () => {
|
|
const client = queryClient();
|
|
const responses: ApplicationResult<string[]>[] = [
|
|
{ ok: true, value: ["first"] },
|
|
{
|
|
ok: false,
|
|
error: createFailure("SERVER_FAILURE", "LIST", 0),
|
|
},
|
|
{ ok: true, value: ["recovered"] },
|
|
];
|
|
const execute = vi.fn(async () => responses.shift() ?? responses[0]);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery({
|
|
queryKey: ["resource", "list"],
|
|
execute,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await waitFor(() => expect(hook.result.current.data).toEqual(["first"]));
|
|
await act(() => hook.result.current.retry());
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.indicator).toBe("stale-degraded"),
|
|
);
|
|
expect(hook.result.current.state.base).toBe("success");
|
|
expect(hook.result.current.data).toEqual(["first"]);
|
|
|
|
await act(() => hook.result.current.retry());
|
|
await waitFor(() =>
|
|
expect(hook.result.current.data).toEqual(["recovered"]),
|
|
);
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
expect(execute).toHaveBeenCalledTimes(3);
|
|
});
|
|
|
|
it("projects an initial application failure into terminal state", async () => {
|
|
const client = queryClient();
|
|
const failure = createFailure("FORBIDDEN", "LIST", 0);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery({
|
|
queryKey: ["forbidden"],
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.base).toBe("terminal-error"),
|
|
);
|
|
expect(hook.result.current.state.failure).toBe(failure);
|
|
});
|
|
|
|
it("normalizes an unexpected execute rejection into a safe terminal failure", async () => {
|
|
const client = queryClient();
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery({
|
|
queryKey: ["unexpected-rejection"],
|
|
execute: async () => {
|
|
throw new Error("private upstream detail");
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.base).toBe("terminal-error"),
|
|
);
|
|
expect(hook.result.current.state.failure).toMatchObject({
|
|
kind: "UNKNOWN_FAILURE",
|
|
operationId: "APPLICATION_QUERY",
|
|
userMessageKey: "error.unknown_failure",
|
|
action: "contact-support",
|
|
});
|
|
expect(JSON.stringify(hook.result.current.state.failure)).not.toContain(
|
|
"private upstream detail",
|
|
);
|
|
});
|
|
|
|
it("passes cancellation to the application and does not retain an unmounted error", async () => {
|
|
const client = queryClient();
|
|
let aborted = false;
|
|
const execute = vi.fn(
|
|
({ signal }: { signal: AbortSignal }) =>
|
|
new Promise<ApplicationResult<unknown>>((resolve) => {
|
|
signal.addEventListener(
|
|
"abort",
|
|
() => {
|
|
aborted = true;
|
|
resolve({
|
|
ok: false,
|
|
error: createFailure("REQUEST_ABORTED", "LIST", 0),
|
|
});
|
|
},
|
|
{ once: true },
|
|
);
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery({
|
|
queryKey: ["cancelled"],
|
|
execute,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await waitFor(() => expect(execute).toHaveBeenCalledOnce());
|
|
hook.unmount();
|
|
await waitFor(() => expect(aborted).toBe(true));
|
|
expect(client.getQueryState(["cancelled"])?.status).not.toBe("error");
|
|
});
|
|
});
|
|
|
|
describe("scope-bound query commit fence", () => {
|
|
it("binds the namespace-first V2 query key", () => {
|
|
const scope = scopeSnapshot();
|
|
const definition = {
|
|
definitionId: "resource-detail-v1",
|
|
definitionVersion: 1,
|
|
owner: "platform-test",
|
|
namespace: "resource",
|
|
namespaceVersion: 1,
|
|
operationId: "GET_RESOURCE",
|
|
profileId: "DETAIL_STANDARD" as const,
|
|
measureResult: measureOne,
|
|
execute: async () => ({ ok: true as const, value: "value" }),
|
|
};
|
|
|
|
const bound = bindQuery(definition, "resource-1", scope);
|
|
|
|
expect(bound.queryKey).toEqual([
|
|
"query",
|
|
2,
|
|
"resource",
|
|
1,
|
|
"scope-fingerprint-0001",
|
|
1,
|
|
"scope-identity-token-0001",
|
|
]);
|
|
expect(bound.queryKey.slice(0, 4)).toEqual(
|
|
createQueryInvalidationPrefix(
|
|
defineQueryNamespaceIdentity("resource", 1),
|
|
),
|
|
);
|
|
});
|
|
|
|
it("discards a successful result whose scope was fenced during execution", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
let complete: (value: ApplicationResult<string>) => void = () => {};
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery(
|
|
bindQuery(
|
|
{
|
|
definitionId: "fenced-detail-v1",
|
|
definitionVersion: 1,
|
|
owner: "platform-test",
|
|
namespace: "fenced",
|
|
namespaceVersion: 1,
|
|
operationId: "GET_FENCED",
|
|
profileId: "DETAIL_STANDARD",
|
|
measureResult: measureOne,
|
|
execute: () =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
complete = resolve;
|
|
}),
|
|
},
|
|
"input",
|
|
scope,
|
|
),
|
|
),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
// §10.8: the scope goes stale after dispatch but before commit.
|
|
scope.fence();
|
|
await act(async () => {
|
|
complete({ ok: true, value: "late" });
|
|
});
|
|
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.failure?.kind).toBe(
|
|
"SCOPE_GENERATION_CHANGED",
|
|
),
|
|
);
|
|
expect(hook.result.current.data).toBeUndefined();
|
|
});
|
|
|
|
it("refuses to start when the captured scope is already stale", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const execute = vi.fn(async () => ({ ok: true as const, value: "v" }));
|
|
scope.fence();
|
|
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery(
|
|
bindQuery(
|
|
{
|
|
definitionId: "stale-detail-v1",
|
|
definitionVersion: 1,
|
|
owner: "platform-test",
|
|
namespace: "stale",
|
|
namespaceVersion: 1,
|
|
operationId: "GET_STALE",
|
|
profileId: "DETAIL_STANDARD",
|
|
measureResult: measureOne,
|
|
execute,
|
|
},
|
|
"input",
|
|
scope,
|
|
),
|
|
),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.failure?.kind).toBe(
|
|
"SCOPE_GENERATION_CHANGED",
|
|
),
|
|
);
|
|
expect(execute).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("rejects a result that exceeds the profile budget instead of caching it", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery(
|
|
bindQuery(
|
|
{
|
|
definitionId: "oversized-list-v1",
|
|
definitionVersion: 1,
|
|
owner: "platform-test",
|
|
namespace: "oversized",
|
|
namespaceVersion: 1,
|
|
operationId: "LIST_OVERSIZED",
|
|
profileId: "VOLATILE_STATUS",
|
|
// §10.4: VOLATILE_STATUS admits 1 item and 64KiB.
|
|
measureResult: (): QueryResultMeasure => ({
|
|
itemCount: 2,
|
|
estimatedBytes: 8,
|
|
}),
|
|
execute: async () => ({ ok: true as const, value: "value" }),
|
|
},
|
|
"input",
|
|
scope,
|
|
),
|
|
),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.failure?.kind).toBe(
|
|
"RESULT_LIMIT_EXCEEDED",
|
|
),
|
|
);
|
|
expect(hook.result.current.data).toBeUndefined();
|
|
});
|
|
|
|
it("treats a throwing measurement as a measurement failure, not a cache commit", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationQuery(
|
|
bindQuery(
|
|
{
|
|
definitionId: "unmeasurable-v1",
|
|
definitionVersion: 1,
|
|
owner: "platform-test",
|
|
namespace: "unmeasurable",
|
|
namespaceVersion: 1,
|
|
operationId: "GET_UNMEASURABLE",
|
|
profileId: "DETAIL_STANDARD",
|
|
measureResult: (): QueryResultMeasure => {
|
|
throw new Error("estimator defect");
|
|
},
|
|
execute: async () => ({ ok: true as const, value: "value" }),
|
|
},
|
|
"input",
|
|
scope,
|
|
),
|
|
),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.failure?.kind).toBe(
|
|
"RESULT_LIMIT_EXCEEDED",
|
|
),
|
|
);
|
|
expect(hook.result.current.data).toBeUndefined();
|
|
});
|
|
});
|
|
|
|
describe("scope-bound mutation fence", () => {
|
|
it("rejects a submit whose scope is already fenced", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const execute = vi.fn(async () => ({ ok: true as const, value: "v" }));
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "fenced-mutation-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE_FENCED",
|
|
requiresIdempotencyKey: false,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE",
|
|
scope,
|
|
execute,
|
|
invalidate: [],
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
scope.fence();
|
|
const outcome = await hook.result.current.submit("value");
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "SCOPE_GENERATION_CHANGED",
|
|
effect: "NOT_STARTED",
|
|
},
|
|
});
|
|
expect(execute).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("discards a mutation result whose scope was fenced after dispatch", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const execute = vi.fn(async () => {
|
|
scope.fence();
|
|
return { ok: true as const, value: "committed" };
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "late-mutation-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE_LATE",
|
|
requiresIdempotencyKey: false,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
scope,
|
|
execute,
|
|
invalidate: [],
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
const outcome = await hook.result.current.submit("value");
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: { kind: "SCOPE_GENERATION_CHANGED" },
|
|
});
|
|
expect(execute).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("aborts a hung mutation when its captured scope is fenced", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
let observedSignal: AbortSignal | undefined;
|
|
const execute = vi.fn(
|
|
(_input: string, context: Readonly<{ signal: AbortSignal }>) =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
observedSignal = context.signal;
|
|
context.signal.addEventListener(
|
|
"abort",
|
|
() =>
|
|
resolve({
|
|
ok: false,
|
|
error: createFailure("REQUEST_ABORTED", "CREATE_HUNG", 0),
|
|
}),
|
|
{ once: true },
|
|
);
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "hung-mutation-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE_HUNG",
|
|
requiresIdempotencyKey: false,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE",
|
|
scope,
|
|
execute,
|
|
invalidate: [],
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
const outcome = hook.result.current.submit("value");
|
|
await waitFor(() => expect(observedSignal).toBe(scope.signal));
|
|
|
|
scope.fence();
|
|
|
|
expect(observedSignal?.aborted).toBe(true);
|
|
await expect(outcome).resolves.toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "SCOPE_GENERATION_CHANGED",
|
|
effect: "MAYBE_APPLIED",
|
|
retryable: false,
|
|
action: "contact-support",
|
|
},
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("application mutation inbound bridge", () => {
|
|
it.each([
|
|
["NOT_STARTED", ["existing"], 0, null],
|
|
["NOT_APPLIED", ["existing"], 0, null],
|
|
["APPLIED_CONFIRMED", ["existing", "created"], 1, null],
|
|
[
|
|
"MAYBE_APPLIED",
|
|
["existing", "created"],
|
|
0,
|
|
"mutation-effect-unknown",
|
|
],
|
|
] as const)(
|
|
"settles an optimistic failure with %s certainty",
|
|
async (effect, expectedData, expectedInvalidations, expectedIndicator) => {
|
|
const client = queryClient();
|
|
const key = ["resource", `certainty-${effect}`];
|
|
client.setQueryData(key, ["existing"]);
|
|
const invalidateQueries = vi.spyOn(client, "invalidateQueries");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect,
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome: ApplicationResult<string> | undefined;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("created");
|
|
});
|
|
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: { kind: failure.kind, effect },
|
|
});
|
|
expect(client.getQueryData(key)).toEqual([...expectedData]);
|
|
expect(invalidateQueries).toHaveBeenCalledTimes(expectedInvalidations);
|
|
expect(hook.result.current.state.indicator).toBe(expectedIndicator);
|
|
if (effect === "MAYBE_APPLIED") {
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: { retryable: false, action: "contact-support" },
|
|
});
|
|
expect(hook.result.current.state.overlay).toMatchObject({
|
|
mutationEffectUnknown: true,
|
|
mutationPending: false,
|
|
mutationConflict: false,
|
|
});
|
|
}
|
|
if (effect === "APPLIED_CONFIRMED") {
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: { retryable: false, action: "none" },
|
|
});
|
|
}
|
|
},
|
|
);
|
|
|
|
it("keeps an applied-confirmed layer committed when invalidation fails", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "applied-invalidation-failure"];
|
|
client.setQueryData(key, ["base"]);
|
|
const invalidateQueries = vi
|
|
.spyOn(client, "invalidateQueries")
|
|
.mockImplementation(async () => {
|
|
expect(client.getQueryData(key)).toEqual(["base", "created"]);
|
|
throw new Error("refresh failed");
|
|
});
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "APPLIED_CONFIRMED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-applied-invalidation-failure-v1",
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome: ApplicationResult<string> | undefined;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("created");
|
|
});
|
|
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
effect: "APPLIED_CONFIRMED",
|
|
retryable: false,
|
|
action: "none",
|
|
},
|
|
});
|
|
expect(invalidateQueries).toHaveBeenCalledOnce();
|
|
expect(client.getQueryData(key)).toEqual(["base", "created"]);
|
|
});
|
|
|
|
it("treats a command failure with missing effect certainty as maybe applied", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "missing-effect"];
|
|
client.setQueryData(key, ["existing"]);
|
|
const invalidateQueries = vi.spyOn(client, "invalidateQueries");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0);
|
|
const execute = vi.fn(async () => ({ ok: false as const, error: failure }));
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute,
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome: ApplicationResult<string> | undefined;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("created");
|
|
});
|
|
|
|
expect(execute).toHaveBeenCalledOnce();
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
effect: "MAYBE_APPLIED",
|
|
retryable: false,
|
|
action: "contact-support",
|
|
},
|
|
});
|
|
expect(client.getQueryData(key)).toEqual(["existing", "created"]);
|
|
expect(invalidateQueries).not.toHaveBeenCalled();
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
});
|
|
|
|
it.each([
|
|
["APPLIED", ["existing", "created"], 1],
|
|
["NOT_APPLIED", ["existing"], 0],
|
|
] as const)(
|
|
"reconciles an unknown optimistic effect as %s exactly once",
|
|
async (resolution, expectedData, expectedInvalidations) => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const key = ["resource", `reconcile-${resolution}`];
|
|
client.setQueryData(key, ["existing"]);
|
|
const invalidateQueries = vi.spyOn(client, "invalidateQueries");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: `reconcile-${resolution}-v1`,
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE",
|
|
scope,
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => hook.result.current.submit("created"));
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
|
|
await act(() => hook.result.current.reconcileUnknownEffect(resolution));
|
|
await act(() =>
|
|
hook.result.current.reconcileUnknownEffect(
|
|
resolution === "APPLIED" ? "NOT_APPLIED" : "APPLIED",
|
|
),
|
|
);
|
|
|
|
expect(client.getQueryData(key)).toEqual([...expectedData]);
|
|
expect(invalidateQueries).toHaveBeenCalledTimes(expectedInvalidations);
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
},
|
|
);
|
|
|
|
it("reconciles parallel unknown effects without losing either lease", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const key = ["resource", "parallel-unknown"];
|
|
client.setQueryData(key, ["base"]);
|
|
const invalidateQueries = vi.spyOn(client, "invalidateQueries");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const resolvers: Array<(value: ApplicationResult<string>) => void> = [];
|
|
const execute = vi.fn(
|
|
(_input: string) =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
resolvers.push(resolve);
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "parallel-unknown-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
scope,
|
|
execute,
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let first: Promise<ApplicationResult<string>> | undefined;
|
|
let second: Promise<ApplicationResult<string>> | undefined;
|
|
act(() => {
|
|
first = hook.result.current.submit("created");
|
|
second = hook.result.current.submit("created");
|
|
});
|
|
await waitFor(() => expect(resolvers).toHaveLength(2));
|
|
act(() => resolvers[0]?.({ ok: false, error: failure }));
|
|
if (!first) throw new Error("expected first mutation");
|
|
await act(() => first);
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
act(() => resolvers[1]?.({ ok: false, error: failure }));
|
|
if (!second) throw new Error("expected second mutation");
|
|
await act(() => second);
|
|
|
|
expect(client.getQueryData(key)).toEqual(["base", "created", "created"]);
|
|
await act(() => hook.result.current.reconcileUnknownEffect("NOT_APPLIED"));
|
|
expect(client.getQueryData(key)).toEqual(["base", "created"]);
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
|
|
await act(() => hook.result.current.reconcileUnknownEffect("APPLIED"));
|
|
expect(client.getQueryData(key)).toEqual(["base", "created"]);
|
|
expect(invalidateQueries).toHaveBeenCalledOnce();
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
});
|
|
|
|
it("closes an unknown optimistic effect safely after scope expiry", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const key = ["resource", "expired-unknown"];
|
|
client.setQueryData(key, ["existing"]);
|
|
const invalidateQueries = vi.spyOn(client, "invalidateQueries");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "expired-unknown-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE",
|
|
scope,
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => hook.result.current.submit("created"));
|
|
scope.fence();
|
|
await act(() => hook.result.current.reconcileUnknownEffect("APPLIED"));
|
|
|
|
expect(client.getQueryState(key)).toBeUndefined();
|
|
expect(invalidateQueries).not.toHaveBeenCalled();
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
});
|
|
|
|
it("reconciles a legacy unknown effect without an optimistic layer", async () => {
|
|
const client = queryClient();
|
|
const invalidateQueries = vi.spyOn(client, "invalidateQueries");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-no-layer-reconcile-v1",
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => hook.result.current.submit("created"));
|
|
expect(invalidateQueries).not.toHaveBeenCalled();
|
|
|
|
await act(() => hook.result.current.reconcileUnknownEffect("APPLIED"));
|
|
expect(invalidateQueries).toHaveBeenCalledOnce();
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
});
|
|
|
|
it("preserves a later legacy commit when an earlier unknown effect is not applied", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "legacy-ordered-unknown"];
|
|
client.setQueryData(key, ["base"]);
|
|
const uncertainFailure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const resolvers = new Map<
|
|
string,
|
|
(value: ApplicationResult<string>) => void
|
|
>();
|
|
const execute = vi.fn(
|
|
(input: string) =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
resolvers.set(input, resolve);
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-active-after-unknown-v1",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
execute,
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let first: Promise<ApplicationResult<string>> | undefined;
|
|
let second: Promise<ApplicationResult<string>> | undefined;
|
|
act(() => {
|
|
first = hook.result.current.submit("first");
|
|
second = hook.result.current.submit("second");
|
|
});
|
|
await waitFor(() => expect(resolvers.size).toBe(2));
|
|
act(() =>
|
|
resolvers.get("first")?.({ ok: false, error: uncertainFailure }),
|
|
);
|
|
if (!first) throw new Error("expected first mutation");
|
|
await act(() => first);
|
|
act(() =>
|
|
resolvers.get("second")?.({ ok: true, value: "second" }),
|
|
);
|
|
if (!second) throw new Error("expected second mutation");
|
|
await act(() => second);
|
|
|
|
expect(client.getQueryData(key)).toEqual(["base", "first", "second"]);
|
|
await act(() => hook.result.current.reconcileUnknownEffect("NOT_APPLIED"));
|
|
expect(client.getQueryData(key)).toEqual(["base", "second"]);
|
|
});
|
|
|
|
it("keeps a newer submit pending while reconciling an older unknown effect", async () => {
|
|
const client = queryClient();
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
let completeSecond: (value: ApplicationResult<string>) => void = () => {};
|
|
const execute = vi.fn((input: string) =>
|
|
input === "first"
|
|
? Promise.resolve({ ok: false as const, error: failure })
|
|
: new Promise<ApplicationResult<string>>((resolve) => {
|
|
completeSecond = resolve;
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-active-after-unknown-no-layer-v1",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
execute,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => hook.result.current.submit("first"));
|
|
let second: Promise<ApplicationResult<string>> | undefined;
|
|
act(() => {
|
|
second = hook.result.current.submit("second");
|
|
});
|
|
await waitFor(() => expect(execute).toHaveBeenCalledTimes(2));
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
|
|
await act(() => hook.result.current.reconcileUnknownEffect("NOT_APPLIED"));
|
|
expect(hook.result.current.state.indicator).toBe("mutation-pending");
|
|
|
|
completeSecond({ ok: true, value: "second" });
|
|
if (!second) throw new Error("expected second mutation");
|
|
await act(() => second);
|
|
await waitFor(() => expect(hook.result.current.state.indicator).toBeNull());
|
|
});
|
|
|
|
it("serializes reconciliation so a double action cannot settle the next intent", async () => {
|
|
const client = queryClient();
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
let finishInvalidation: () => void = () => {};
|
|
const invalidation = new Promise<void>((resolve) => {
|
|
finishInvalidation = resolve;
|
|
});
|
|
vi.spyOn(client, "invalidateQueries").mockImplementation(
|
|
async () => invalidation,
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-applied-double-action-v1",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(async () => {
|
|
await Promise.all([
|
|
hook.result.current.submit("first"),
|
|
hook.result.current.submit("second"),
|
|
]);
|
|
});
|
|
|
|
let firstResolution: Promise<void> | undefined;
|
|
let duplicateResolution: Promise<void> | undefined;
|
|
act(() => {
|
|
firstResolution = hook.result.current.reconcileUnknownEffect("APPLIED");
|
|
duplicateResolution = hook.result.current.reconcileUnknownEffect(
|
|
"NOT_APPLIED",
|
|
);
|
|
});
|
|
await expect(duplicateResolution).resolves.toBeUndefined();
|
|
expect(hook.result.current.state.indicator).toBe("mutation-pending");
|
|
|
|
finishInvalidation();
|
|
if (!firstResolution) throw new Error("expected reconciliation");
|
|
await act(() => firstResolution);
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
await act(() => hook.result.current.reconcileUnknownEffect("NOT_APPLIED"));
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
});
|
|
|
|
it("keeps the next intent unresolved after a synchronous not-applied double action", async () => {
|
|
const client = queryClient();
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-not-applied-double-action-v1",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(async () => {
|
|
await Promise.all([
|
|
hook.result.current.submit("first"),
|
|
hook.result.current.submit("second"),
|
|
]);
|
|
});
|
|
|
|
let firstResolution: Promise<void> | undefined;
|
|
let duplicateResolution: Promise<void> | undefined;
|
|
act(() => {
|
|
firstResolution = hook.result.current.reconcileUnknownEffect(
|
|
"NOT_APPLIED",
|
|
);
|
|
duplicateResolution = hook.result.current.reconcileUnknownEffect(
|
|
"APPLIED",
|
|
);
|
|
});
|
|
await expect(duplicateResolution).resolves.toBeUndefined();
|
|
if (!firstResolution) throw new Error("expected reconciliation");
|
|
await act(() => firstResolution);
|
|
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
await act(() => hook.result.current.reconcileUnknownEffect("NOT_APPLIED"));
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
});
|
|
|
|
it("clears every stale-scope unknown effect without touching new data", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const key = ["resource", "scope-unknown-queue"];
|
|
client.setQueryData(key, ["base"]);
|
|
const invalidateQueries = vi.spyOn(client, "invalidateQueries");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "scope-unknown-queue-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
scope,
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(async () => {
|
|
await Promise.all([
|
|
hook.result.current.submit("created"),
|
|
hook.result.current.submit("created"),
|
|
]);
|
|
});
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
|
|
act(() => scope.fence());
|
|
await waitFor(() => expect(hook.result.current.state.indicator).toBeNull());
|
|
expect(client.getQueryState(key)).toBeUndefined();
|
|
client.setQueryData(key, ["new-generation"]);
|
|
await act(() => hook.result.current.reconcileUnknownEffect("APPLIED"));
|
|
|
|
expect(client.getQueryData(key)).toEqual(["new-generation"]);
|
|
expect(invalidateQueries).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("restores a bound unknown-effect head after controller remount", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const key = ["resource", "durable-unknown"];
|
|
client.setQueryData(key, ["base"]);
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const mutationOptions = {
|
|
definitionId: "durable-unknown-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE" as const,
|
|
scope,
|
|
execute: vi.fn(async () => ({ ok: false as const, error: failure })),
|
|
invalidate: [] as const,
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous: unknown, input: string) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
};
|
|
const first = renderHook(
|
|
() => useApplicationMutation<string, string>(mutationOptions),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => first.result.current.submit("created"));
|
|
expect(first.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
first.unmount();
|
|
|
|
const remounted = renderHook(
|
|
() => useApplicationMutation<string, string>(mutationOptions),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
expect(remounted.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
await act(() =>
|
|
remounted.result.current.reconcileUnknownEffect("NOT_APPLIED"),
|
|
);
|
|
|
|
expect(client.getQueryData(key)).toEqual(["base"]);
|
|
expect(remounted.result.current.state.indicator).toBeNull();
|
|
expect(mutationOptions.execute).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("restores a non-optimistic legacy unknown effect by stable definition after remount", async () => {
|
|
const client = queryClient();
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const mutationOptions = {
|
|
definitionId: "legacy-durable-create-v1",
|
|
execute: vi.fn(async () => ({ ok: false as const, error: failure })),
|
|
};
|
|
const first = renderHook(
|
|
() => useApplicationMutation<string, string>(mutationOptions),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => first.result.current.submit("created"));
|
|
expect(first.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
first.unmount();
|
|
|
|
const remounted = renderHook(
|
|
() => useApplicationMutation<string, string>(mutationOptions),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
expect(remounted.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
await act(() =>
|
|
remounted.result.current.reconcileUnknownEffect("NOT_APPLIED"),
|
|
);
|
|
|
|
expect(remounted.result.current.state.indicator).toBeNull();
|
|
expect(mutationOptions.execute).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("does not allocate unknown-effect channels for abandoned server renders", async () => {
|
|
const client = queryClient();
|
|
const selectedScopes = Array.from(
|
|
{ length: MUTATION_COORDINATOR_BOUNDS.activeDefinitionsPerRuntime },
|
|
(_, index) => scopeSnapshot(1, `server-render-scope-${index}`),
|
|
);
|
|
|
|
function AbandonedMutation({ index }: Readonly<{ index: number }>) {
|
|
useApplicationMutation<string, string>({
|
|
definitionId: `server-render-abandoned-${index}`,
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE",
|
|
scope: selectedScopes[index]!,
|
|
execute: async (input) => ({ ok: true, value: input }),
|
|
invalidate: [],
|
|
});
|
|
return null;
|
|
}
|
|
|
|
const ServerWrapper = wrapper(client);
|
|
renderToString(
|
|
<ServerWrapper>
|
|
{selectedScopes.map((_, index) => (
|
|
<AbandonedMutation key={index} index={index} />
|
|
))}
|
|
</ServerWrapper>,
|
|
);
|
|
|
|
const scope = scopeSnapshot(1, "committed-after-server-render");
|
|
const execute = vi.fn(async (input: string) => ({
|
|
ok: true as const,
|
|
value: input,
|
|
}));
|
|
const committed = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "committed-after-server-render",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE",
|
|
scope,
|
|
execute,
|
|
invalidate: [],
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await expect(committed.result.current.submit("created")).resolves.toEqual({
|
|
ok: true,
|
|
value: "created",
|
|
});
|
|
expect(execute).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("isolates channels when a reused fingerprint advances generation", async () => {
|
|
const client = queryClient();
|
|
const firstScope = scopeSnapshot(1, "reused-scope-fingerprint");
|
|
const secondScope = scopeSnapshot(2, "reused-scope-fingerprint");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const definition = {
|
|
definitionId: "generation-channel-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE" as const,
|
|
invalidate: [] as const,
|
|
};
|
|
const first = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
...definition,
|
|
scope: firstScope,
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
await act(() => first.result.current.submit("first"));
|
|
expect(first.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
|
|
const secondExecute = vi.fn(async () => ({
|
|
ok: true as const,
|
|
value: "second",
|
|
}));
|
|
const second = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
...definition,
|
|
scope: secondScope,
|
|
execute: secondExecute,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
expect(second.result.current.state.indicator).toBeNull();
|
|
await expect(second.result.current.submit("second")).resolves.toEqual({
|
|
ok: true,
|
|
value: "second",
|
|
});
|
|
expect(secondExecute).toHaveBeenCalledOnce();
|
|
expect(first.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
});
|
|
|
|
it("isolates unrelated non-optimistic legacy controllers", async () => {
|
|
const client = queryClient();
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const first = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-isolation-first-v1",
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
const second = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-isolation-second-v1",
|
|
execute: async (input) => ({ ok: true, value: input }),
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => first.result.current.submit("first"));
|
|
expect(first.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
expect(second.result.current.state.indicator).toBeNull();
|
|
await act(() => second.result.current.reconcileUnknownEffect("APPLIED"));
|
|
expect(first.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
});
|
|
|
|
it("fails closed when identical bound metadata is mounted with a different scope owner", async () => {
|
|
const client = queryClient();
|
|
const firstScope = scopeSnapshot(1, "same-owner-fingerprint");
|
|
const secondScope = scopeSnapshot(1, "same-owner-fingerprint");
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const definition = {
|
|
definitionId: "scope-owner-channel-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE" as const,
|
|
invalidate: [] as const,
|
|
};
|
|
const first = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
...definition,
|
|
scope: firstScope,
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
await act(() => first.result.current.submit("first"));
|
|
|
|
const secondExecute = vi.fn(async () => ({
|
|
ok: true as const,
|
|
value: "second",
|
|
}));
|
|
const second = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
...definition,
|
|
scope: secondScope,
|
|
execute: secondExecute,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
expect(second.result.current.state.indicator).toBeNull();
|
|
await expect(second.result.current.submit("second")).resolves.toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "IDENTITY_INTERN_LIMIT_EXCEEDED",
|
|
code: "UNKNOWN_EFFECT_CHANNEL_LIMIT_EXCEEDED",
|
|
effect: "NOT_STARTED",
|
|
},
|
|
});
|
|
expect(secondExecute).not.toHaveBeenCalled();
|
|
expect(first.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
});
|
|
|
|
it("releases empty unmounted channels after their active mutation settles", async () => {
|
|
const client = queryClient();
|
|
const firstScope = scopeSnapshot(1, "release-owner-fingerprint");
|
|
const secondScope = scopeSnapshot(1, "release-owner-fingerprint");
|
|
let resolveFirst: (value: ApplicationResult<string>) => void = () => {};
|
|
const definition = {
|
|
definitionId: "release-channel-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "ALLOW_PARALLEL" as const,
|
|
invalidate: [] as const,
|
|
};
|
|
const first = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
...definition,
|
|
scope: firstScope,
|
|
execute: () =>
|
|
new Promise((resolve) => {
|
|
resolveFirst = resolve;
|
|
}),
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
let pending: Promise<ApplicationResult<string>> | undefined;
|
|
act(() => {
|
|
pending = first.result.current.submit("created");
|
|
});
|
|
await waitFor(() =>
|
|
expect(first.result.current.state.indicator).toBe("mutation-pending"),
|
|
);
|
|
first.unmount();
|
|
resolveFirst({ ok: true, value: "created" });
|
|
if (!pending) throw new Error("expected active mutation");
|
|
await act(() => pending);
|
|
|
|
const execute = vi.fn(async () => ({
|
|
ok: true as const,
|
|
value: "after-release",
|
|
}));
|
|
const afterRelease = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
...definition,
|
|
scope: secondScope,
|
|
execute,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await expect(afterRelease.result.current.submit("created")).resolves.toEqual({
|
|
ok: true,
|
|
value: "after-release",
|
|
});
|
|
expect(execute).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("enforces the active intent bound across all QueryClient channels", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const never = () => new Promise<ApplicationResult<string>>(() => {});
|
|
const options = (definitionId: string) => ({
|
|
definitionId,
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "ALLOW_PARALLEL" as const,
|
|
scope,
|
|
execute: never,
|
|
invalidate: [] as const,
|
|
});
|
|
const first = renderHook(
|
|
() => useApplicationMutation<string, string>(options("bound-a")),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
const second = renderHook(
|
|
() => useApplicationMutation<string, string>(options("bound-b")),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
const half = MUTATION_COORDINATOR_BOUNDS.activeIntentsTotal / 2;
|
|
|
|
act(() => {
|
|
for (let index = 0; index < half; index += 1) {
|
|
void first.result.current.submit("same-input");
|
|
void second.result.current.submit("same-input");
|
|
}
|
|
});
|
|
|
|
await expect(first.result.current.submit("same-input")).resolves.toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "IDENTITY_INTERN_LIMIT_EXCEEDED",
|
|
code: "UNKNOWN_EFFECT_CHANNEL_LIMIT_EXCEEDED",
|
|
effect: "NOT_STARTED",
|
|
},
|
|
});
|
|
act(() => scope.fence());
|
|
});
|
|
|
|
it("reconciles parallel unknown effects in submit order after reverse completion", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "reverse-completion"];
|
|
client.setQueryData(key, ["base"]);
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const resolvers = new Map<
|
|
string,
|
|
(value: ApplicationResult<string>) => void
|
|
>();
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
execute: (input) =>
|
|
new Promise((resolve) => {
|
|
resolvers.set(input, resolve);
|
|
}),
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let first: Promise<ApplicationResult<string>> | undefined;
|
|
let second: Promise<ApplicationResult<string>> | undefined;
|
|
act(() => {
|
|
first = hook.result.current.submit("first");
|
|
second = hook.result.current.submit("second");
|
|
});
|
|
await waitFor(() => expect(resolvers.size).toBe(2));
|
|
act(() => resolvers.get("second")?.({ ok: false, error: failure }));
|
|
if (!second) throw new Error("expected second mutation");
|
|
await act(() => second);
|
|
expect(hook.result.current.state.indicator).toBe("mutation-pending");
|
|
|
|
act(() => resolvers.get("first")?.({ ok: false, error: failure }));
|
|
if (!first) throw new Error("expected first mutation");
|
|
await act(() => first);
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
|
|
await act(() => hook.result.current.reconcileUnknownEffect("NOT_APPLIED"));
|
|
expect(client.getQueryData(key)).toEqual(["base", "second"]);
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
await act(() => hook.result.current.reconcileUnknownEffect("APPLIED"));
|
|
expect(client.getQueryData(key)).toEqual(["base", "second"]);
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
});
|
|
|
|
it("removes committed old-scope data when scope fences during reconciliation invalidation", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const key = ["resource", "reconcile-fence-race"];
|
|
client.setQueryData(key, ["base"]);
|
|
let finishInvalidation: () => void = () => {};
|
|
const invalidation = new Promise<void>((resolve) => {
|
|
finishInvalidation = resolve;
|
|
});
|
|
const invalidateQueries = vi
|
|
.spyOn(client, "invalidateQueries")
|
|
.mockImplementation(async () => invalidation);
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "MAYBE_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "reconcile-fence-race-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "REJECT_WHILE_ACTIVE",
|
|
scope,
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(() => hook.result.current.submit("created"));
|
|
let reconciliation: Promise<void> | undefined;
|
|
act(() => {
|
|
reconciliation = hook.result.current.reconcileUnknownEffect("APPLIED");
|
|
});
|
|
await waitFor(() => expect(invalidateQueries).toHaveBeenCalledOnce());
|
|
act(() => scope.fence());
|
|
finishInvalidation();
|
|
if (!reconciliation) throw new Error("expected reconciliation");
|
|
await act(() => reconciliation);
|
|
|
|
expect(client.getQueryState(key)).toBeUndefined();
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
});
|
|
|
|
it.each(["NOT_APPLICABLE", undefined] as const)(
|
|
"treats %s conflict effect certainty as unknown without conflict retry",
|
|
async (effect) => {
|
|
const client = queryClient();
|
|
const key = ["resource", `ambiguous-conflict-${String(effect)}`];
|
|
client.setQueryData(key, ["base"]);
|
|
const conflict = createFailure("CONFLICT", "CREATE", 0, {
|
|
...(effect ? { effect } : {}),
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute: async () => ({ ok: false, error: conflict }),
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome: ApplicationResult<string> | undefined;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("created");
|
|
});
|
|
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
effect: "MAYBE_APPLIED",
|
|
retryable: false,
|
|
action: "contact-support",
|
|
},
|
|
});
|
|
expect(client.getQueryData(key)).toEqual(["base", "created"]);
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
},
|
|
);
|
|
|
|
it("retains optimistic data when execute throws after dispatch begins", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "thrown-unknown-effect"];
|
|
client.setQueryData(key, ["base"]);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute: async () => {
|
|
throw new Error("private transport defect");
|
|
},
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome: ApplicationResult<string> | undefined;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("created");
|
|
});
|
|
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
effect: "MAYBE_APPLIED",
|
|
retryable: false,
|
|
action: "contact-support",
|
|
},
|
|
});
|
|
expect(JSON.stringify(outcome)).not.toContain("private transport defect");
|
|
expect(client.getQueryData(key)).toEqual(["base", "created"]);
|
|
expect(hook.result.current.state.indicator).toBe(
|
|
"mutation-effect-unknown",
|
|
);
|
|
});
|
|
|
|
it("creates a distinct logical intent for each independently admitted submit", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const observedIntents: unknown[] = [];
|
|
const execute = vi.fn(
|
|
async (
|
|
input: string,
|
|
context: Readonly<{ signal: AbortSignal; intent?: unknown }>,
|
|
) => {
|
|
observedIntents.push(context.intent);
|
|
return { ok: true as const, value: input };
|
|
},
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "independent-intent-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE_WITH_INTENT",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "ALLOW_PARALLEL",
|
|
scope,
|
|
execute,
|
|
invalidate: [],
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
await act(async () => {
|
|
await hook.result.current.submit("same-input");
|
|
await hook.result.current.submit("same-input");
|
|
});
|
|
|
|
expect(observedIntents).toHaveLength(2);
|
|
expect(observedIntents[0]).toMatchObject({
|
|
intentId: "intent-1",
|
|
operationId: "CREATE_WITH_INTENT",
|
|
idempotencyKey: "key-1",
|
|
});
|
|
expect(observedIntents[1]).toMatchObject({
|
|
intentId: "intent-2",
|
|
operationId: "CREATE_WITH_INTENT",
|
|
idempotencyKey: "key-2",
|
|
});
|
|
expect(observedIntents[0]).not.toEqual(observedIntents[1]);
|
|
});
|
|
|
|
it("creates no second intent when JOIN_IDENTICAL shares an admitted submit", async () => {
|
|
const client = queryClient();
|
|
const scope = scopeSnapshot();
|
|
const deterministicFactory = deterministicMutationIntentFactory();
|
|
const createIntent = vi.fn(deterministicFactory.create);
|
|
const factory: MutationIntentFactory = Object.freeze({
|
|
create: createIntent,
|
|
});
|
|
let complete: (value: ApplicationResult<string>) => void = () => {};
|
|
const execute = vi.fn(
|
|
() =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
complete = resolve;
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "joined-intent-v1",
|
|
definitionVersion: 1,
|
|
operationId: "CREATE_JOINED",
|
|
requiresIdempotencyKey: true,
|
|
owner: "platform-test",
|
|
duplicatePolicy: "JOIN_IDENTICAL",
|
|
scope,
|
|
execute,
|
|
invalidate: [],
|
|
}),
|
|
{ wrapper: wrapper(client, factory) },
|
|
);
|
|
|
|
let first: Promise<ApplicationResult<string>> | null = null;
|
|
let joined: Promise<ApplicationResult<string>> | null = null;
|
|
act(() => {
|
|
first = hook.result.current.submit("same-input");
|
|
joined = hook.result.current.submit("same-input");
|
|
});
|
|
|
|
expect(first).toBe(joined);
|
|
await waitFor(() => expect(execute).toHaveBeenCalledOnce());
|
|
expect(createIntent).toHaveBeenCalledOnce();
|
|
expect(createIntent).toHaveBeenCalledWith({
|
|
operationId: "CREATE_JOINED",
|
|
canonicalInputIdentity:
|
|
"scope-fingerprint-0001:joined-intent-v1:scope-identity-token-0001",
|
|
requiresIdempotencyKey: true,
|
|
});
|
|
|
|
complete({ ok: true, value: "same-input" });
|
|
if (!first) throw new Error("expected admitted mutation");
|
|
await act(() => first);
|
|
});
|
|
|
|
it("keeps the legacy raw mutation path outside the intent factory", async () => {
|
|
const client = queryClient();
|
|
const createIntent = vi.fn<MutationIntentFactory["create"]>();
|
|
const factory: MutationIntentFactory = Object.freeze({
|
|
create: createIntent,
|
|
});
|
|
const execute = vi.fn(async (input: string) => ({
|
|
ok: true as const,
|
|
value: input,
|
|
}));
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-raw-path-v1",
|
|
execute,
|
|
}),
|
|
{ wrapper: wrapper(client, factory) },
|
|
);
|
|
|
|
await act(() => hook.result.current.submit("legacy-input"));
|
|
|
|
expect(execute).toHaveBeenCalledOnce();
|
|
expect(createIntent).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("rejects a duplicate submit by default while one is active", async () => {
|
|
const client = queryClient();
|
|
let complete: (value: ApplicationResult<string>) => void = () => {};
|
|
const execute = vi.fn(
|
|
() =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
complete = resolve;
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-duplicate-rejection-v1",
|
|
execute,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let first: Promise<ApplicationResult<string>> | null = null;
|
|
let duplicate: Promise<ApplicationResult<string>> | null = null;
|
|
act(() => {
|
|
first = hook.result.current.submit("created");
|
|
duplicate = hook.result.current.submit("created");
|
|
});
|
|
|
|
if (!first || !duplicate) throw new Error("expected two submissions");
|
|
await expect(duplicate).resolves.toMatchObject({
|
|
ok: false,
|
|
error: { kind: "DUPLICATE_IN_FLIGHT" },
|
|
});
|
|
expect(execute).toHaveBeenCalledOnce();
|
|
|
|
complete({ ok: true, value: "created" });
|
|
await act(() => first as Promise<ApplicationResult<string>>);
|
|
});
|
|
|
|
it("deduplicates submit and commits one optimistic mutation", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "list"];
|
|
client.setQueryData(key, ["existing"]);
|
|
let complete: (value: ApplicationResult<string>) => void = () => {};
|
|
const execute = vi.fn(
|
|
() =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
complete = resolve;
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
// §11.2: joining is opt-in. The default is REJECT_WHILE_ACTIVE.
|
|
duplicatePolicy: "JOIN_IDENTICAL",
|
|
execute,
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let first: Promise<ApplicationResult<string>> | null = null;
|
|
let duplicate: Promise<ApplicationResult<string>> | null = null;
|
|
act(() => {
|
|
first = hook.result.current.submit("created");
|
|
duplicate = hook.result.current.submit("created");
|
|
});
|
|
expect(first).toBe(duplicate);
|
|
await waitFor(() =>
|
|
expect(client.getQueryData(key)).toEqual(["existing", "created"]),
|
|
);
|
|
await waitFor(() => expect(execute).toHaveBeenCalledOnce());
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.indicator).toBe("mutation-pending"),
|
|
);
|
|
|
|
complete({ ok: true, value: "created" });
|
|
if (!first) throw new Error("expected pending mutation");
|
|
await act(() => first);
|
|
expect(client.getQueryState(key)?.isInvalidated).toBe(true);
|
|
await waitFor(() =>
|
|
expect(hook.result.current.state.indicator).toBeNull(),
|
|
);
|
|
});
|
|
|
|
it("never joins distinct mutation inputs to the same runtime promise", async () => {
|
|
const client = queryClient();
|
|
const resolvers = new Map<
|
|
string,
|
|
(value: ApplicationResult<string>) => void
|
|
>();
|
|
const execute = vi.fn(
|
|
(input: string) =>
|
|
new Promise<ApplicationResult<string>>((resolve) => {
|
|
resolvers.set(input, resolve);
|
|
}),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
definitionId: "legacy-parallel-distinct-inputs-v1",
|
|
execute,
|
|
currentData: true,
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let first: Promise<ApplicationResult<string>> | undefined;
|
|
let second: Promise<ApplicationResult<string>> | undefined;
|
|
act(() => {
|
|
first = hook.result.current.submit("first");
|
|
second = hook.result.current.submit("second");
|
|
});
|
|
expect(first).not.toBe(second);
|
|
await waitFor(() => expect(execute).toHaveBeenCalledTimes(2));
|
|
|
|
resolvers.get("first")?.({ ok: true, value: "first" });
|
|
resolvers.get("second")?.({ ok: true, value: "second" });
|
|
if (!first || !second) throw new Error("expected pending mutations");
|
|
await act(async () => {
|
|
await Promise.all([first, second]);
|
|
});
|
|
});
|
|
|
|
it("cancels an in-flight query before taking the optimistic snapshot", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "ordered-update"];
|
|
client.setQueryData(key, ["existing"]);
|
|
let finishCancellation: () => void = () => {};
|
|
const cancellation = new Promise<void>((resolve) => {
|
|
finishCancellation = resolve;
|
|
});
|
|
const cancelQueries = vi
|
|
.spyOn(client, "cancelQueries")
|
|
.mockImplementation(async () => cancellation);
|
|
const getQueryData = vi.spyOn(client, "getQueryData");
|
|
const update = vi.fn((previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
]);
|
|
const execute = vi.fn(async () => ({
|
|
ok: true as const,
|
|
value: "created",
|
|
}));
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute,
|
|
currentData: ["existing"],
|
|
optimistic: { queryKey: key, update },
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let pending: Promise<ApplicationResult<string>> | undefined;
|
|
act(() => {
|
|
pending = hook.result.current.submit("created");
|
|
});
|
|
expect(cancelQueries).toHaveBeenCalledWith({
|
|
queryKey: key,
|
|
exact: true,
|
|
});
|
|
expect(getQueryData).not.toHaveBeenCalled();
|
|
expect(update).not.toHaveBeenCalled();
|
|
expect(execute).not.toHaveBeenCalled();
|
|
|
|
finishCancellation();
|
|
if (!pending) throw new Error("expected pending mutation");
|
|
await act(() => pending);
|
|
|
|
expect(getQueryData).toHaveBeenCalledWith(key);
|
|
expect(update).toHaveBeenCalledWith(["existing"], "created");
|
|
expect(execute).toHaveBeenCalledOnce();
|
|
expect(client.getQueryData(key)).toEqual(["existing", "created"]);
|
|
});
|
|
|
|
it("keeps a committed optimistic update when invalidation fails", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "committed-update"];
|
|
client.setQueryData(key, ["existing"]);
|
|
vi.spyOn(client, "invalidateQueries").mockRejectedValue(
|
|
new Error("cache refresh failed"),
|
|
);
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute: async () => ({ ok: true, value: "created" }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
currentData: ["existing"],
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("created");
|
|
});
|
|
|
|
expect(outcome).toEqual({ ok: true, value: "created" });
|
|
expect(client.getQueryData(key)).toEqual(["existing", "created"]);
|
|
});
|
|
|
|
it("normalizes an optimistic preparation defect without running the command", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "invalid-optimistic-update"];
|
|
client.setQueryData(key, ["existing"]);
|
|
const execute = vi.fn(async () => ({
|
|
ok: true as const,
|
|
value: "created",
|
|
}));
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute,
|
|
currentData: ["existing"],
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: () => {
|
|
throw new Error("private optimistic detail");
|
|
},
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("created");
|
|
});
|
|
|
|
expect(outcome).toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "UNKNOWN_FAILURE",
|
|
effect: "NOT_STARTED",
|
|
operationId: "APPLICATION_MUTATION",
|
|
userMessageKey: "error.unknown_failure",
|
|
},
|
|
});
|
|
expect(JSON.stringify(outcome)).not.toContain("private optimistic detail");
|
|
expect(execute).not.toHaveBeenCalled();
|
|
expect(client.getQueryData(key)).toEqual(["existing"]);
|
|
});
|
|
|
|
it("removes an optimistic cache entry when no prior data existed", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "new-optimistic-entry"];
|
|
const failure = createFailure("SERVER_FAILURE", "CREATE", 0, {
|
|
effect: "NOT_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute: async () => ({ ok: false, error: failure }),
|
|
currentData: true,
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (_previous, input) => [input],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("temporary");
|
|
});
|
|
|
|
expect(outcome).toEqual({ ok: false, error: failure });
|
|
expect(client.getQueryData(key)).toBeUndefined();
|
|
expect(client.getQueryState(key)).toBeUndefined();
|
|
});
|
|
|
|
it("rolls optimistic data back and exposes a resolvable conflict", async () => {
|
|
const client = queryClient();
|
|
const key = ["resource", "list"];
|
|
client.setQueryData(key, ["existing"]);
|
|
const conflict = createFailure("CONFLICT", "CREATE", 0, {
|
|
effect: "NOT_APPLIED",
|
|
});
|
|
const hook = renderHook(
|
|
() =>
|
|
useApplicationMutation<string, string>({
|
|
execute: async () => ({ ok: false, error: conflict }),
|
|
invalidate: [RESOURCE_INVALIDATION_TOPIC],
|
|
currentData: client.getQueryData(key),
|
|
optimistic: {
|
|
queryKey: key,
|
|
update: (previous, input) => [
|
|
...(previous as string[]),
|
|
input,
|
|
],
|
|
},
|
|
}),
|
|
{ wrapper: wrapper(client) },
|
|
);
|
|
|
|
let outcome;
|
|
await act(async () => {
|
|
outcome = await hook.result.current.submit("conflicting");
|
|
});
|
|
expect(outcome).toEqual({ ok: false, error: conflict });
|
|
expect(client.getQueryData(key)).toEqual(["existing"]);
|
|
expect(hook.result.current.state.indicator).toBe("mutation-conflict");
|
|
expect(hook.result.current.state.overlay).toMatchObject({
|
|
mutationPending: false,
|
|
mutationConflict: true,
|
|
});
|
|
|
|
await act(() => hook.result.current.resolveConflict());
|
|
expect(hook.result.current.state.indicator).toBeNull();
|
|
expect(client.getQueryState(key)?.isInvalidated).toBe(true);
|
|
});
|
|
});
|