donghyeon.kang/clean-architecture-frontend-template
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

fix: preserve logical mutation intent

Browse Source
This commit is contained in:
DongHyeonka
2026-08-02 01:07:19 +09:00
parent 53d181fbe4
commit cbcc7b5ed7
21 changed files with 724 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/component/application-query.test.tsx
+156 -6
View File
@@ -14,6 +14,8 @@ import {
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,
@@ -71,7 +73,28 @@ function queryClient() {
});
}
function wrapper(client: QueryClient) {
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) {
@@ -93,11 +116,13 @@ function wrapper(client: QueryClient) {
};
return function QueryWrapper({ children }: { children: ReactNode }) {
return (
<QueryClientProvider client={client}>
<QueryInvalidationProvider coordinator={coordinator}>
{children}
</QueryInvalidationProvider>
</QueryClientProvider>
<MutationIntentProvider factory={mutationIntentFactory}>
<QueryClientProvider client={client}>
<QueryInvalidationProvider coordinator={coordinator}>
{children}
</QueryInvalidationProvider>
</QueryClientProvider>
</MutationIntentProvider>
);
};
}
@@ -415,6 +440,7 @@ describe("scope-bound mutation fence", () => {
definitionId: "fenced-mutation-v1",
definitionVersion: 1,
operationId: "CREATE_FENCED",
requiresIdempotencyKey: false,
owner: "platform-test",
duplicatePolicy: "REJECT_WHILE_ACTIVE",
scope,
@@ -446,6 +472,7 @@ describe("scope-bound mutation fence", () => {
definitionId: "late-mutation-v1",
definitionVersion: 1,
operationId: "CREATE_LATE",
requiresIdempotencyKey: false,
owner: "platform-test",
duplicatePolicy: "ALLOW_PARALLEL",
scope,
@@ -488,6 +515,7 @@ describe("scope-bound mutation fence", () => {
definitionId: "hung-mutation-v1",
definitionVersion: 1,
operationId: "CREATE_HUNG",
requiresIdempotencyKey: false,
owner: "platform-test",
duplicatePolicy: "REJECT_WHILE_ACTIVE",
scope,
@@ -516,6 +544,128 @@ describe("scope-bound mutation fence", () => {
});
describe("application mutation inbound bridge", () => {
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>({ 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 = () => {};
tests/component/server-state-generation-provider.test.tsx
+6
View File
@@ -43,6 +43,11 @@ describe("server-state generation provider", () => {
`scope-generation-provider-${String(token++).padStart(4, "0")}`,
});
const renderedClients: QueryClient[] = [];
const mutationIntentFactory = Object.freeze({
create() {
throw new Error("mutation intent is unused by this provider test");
},
});
function Probe() {
renderedClients.push(useQueryClient());
return <div>generation-content</div>;
@@ -52,6 +57,7 @@ describe("server-state generation provider", () => {
<ServerStateGenerationProvider
store={store}
scope={scope}
mutationIntentFactory={mutationIntentFactory}
transitionFallback={<div>scope-transition</div>}
>
<Probe />
tests/features/reference-feature/reference-page.test.tsx
+33 -14
View File
@@ -10,6 +10,7 @@ import { describe, expect, it, vi } from "vitest";
import { createDemoSessionAdapter } from "../../../src/adapters/auth/external-session-adapter.ts";
import type { AuthSessionPort } from "../../../src/application/ports/auth-session-port.ts";
import type { MutationIntentFactory } from "../../../src/application/ports/mutation-intent-factory.ts";
import type {
ReferenceFeatureInput,
ReferenceResult,
@@ -19,6 +20,7 @@ import type { ReferenceResourceView } from "../../../src/features/reference-feat
import { createFailure } from "../../../src/contracts/errors.ts";
import type { QueryInvalidationCoordinator } from "../../../src/contracts/query-invalidation.ts";
import { QueryInvalidationProvider } from "../../../src/presentation/adapters/query/query-invalidation-provider.tsx";
import { MutationIntentProvider } from "../../../src/presentation/adapters/query/mutation-intent-provider.tsx";
import { ServerStateScopeProvider } from "../../../src/presentation/adapters/query/server-state-scope-provider.tsx";
import { createServerStateScopeRuntime } from "../../../src/adapters/query-cache/server-state-scope-runtime.ts";
import { ApplicationProvider } from "../../../src/presentation/providers/application-provider.tsx";
@@ -51,21 +53,38 @@ function renderReference(
session,
queryInvalidation: invalidation,
});
let intentSequence = 0;
const mutationIntentFactory: MutationIntentFactory = Object.freeze({
create(input) {
intentSequence += 1;
return Object.freeze({
intentId: `reference-page-intent-${intentSequence}`,
operationId: input.operationId,
canonicalInputIdentity: input.canonicalInputIdentity,
...(input.requiresIdempotencyKey
? { idempotencyKey: `reference-page-key-${intentSequence}` }
: {}),
createdAtMonotonicMs: intentSequence,
});
},
});
return render(
<QueryClientProvider client={client}>
<ServerStateScopeProvider runtime={serverStateScope}>
<QueryInvalidationProvider coordinator={invalidation}>
<ApplicationProvider
application={createTestApplication({
session,
featureInputs: { [REFERENCE_FEATURE_ID]: input },
})}
>
<AppRouter />
</ApplicationProvider>
</QueryInvalidationProvider>
</ServerStateScopeProvider>
</QueryClientProvider>,
<MutationIntentProvider factory={mutationIntentFactory}>
<QueryClientProvider client={client}>
<ServerStateScopeProvider runtime={serverStateScope}>
<QueryInvalidationProvider coordinator={invalidation}>
<ApplicationProvider
application={createTestApplication({
session,
featureInputs: { [REFERENCE_FEATURE_ID]: input },
})}
>
<AppRouter />
</ApplicationProvider>
</QueryInvalidationProvider>
</ServerStateScopeProvider>
</QueryClientProvider>
</MutationIntentProvider>,
);
}
tests/integration/http-execution-contract.test.ts
+2
View File
@@ -124,9 +124,11 @@ describe("HTTP operation execution contract", () => {
expect(requests[0].url).toBe(
"https://api.test/api/entities?cursor=a%2Fb&limit=5&tags=open&tags=new",
);
expect(requests[0].headers.get("Idempotency-Key")).toBeNull();
expect(entityQueryKeys.list(filters).at(-1)).toEqual(filters);
await expect(requests[1].json()).resolves.toEqual({ name: "Trimmed" });
expect(requests[1].headers.get("Idempotency-Key")).toBe("logical-command");
expect(requests[1].url).not.toContain("logical-command");
expect(requests[0].headers.get("X-Correlation-ID")).toBeTruthy();
expect(requests[0].credentials).toBe("same-origin");
expect(requests[0].cache).toBe("no-store");
tests/unit/http-execution-v3.test.ts
+139 -2
View File
@@ -21,6 +21,20 @@ const scope = Object.freeze({
const createInstalled: InstalledHttpContract<unknown, unknown, unknown> =
TEST_CREATE_HTTP_CONTRACT;
function mutationIntent(
overrides: Readonly<{ intentId?: string; idempotencyKey?: string }> = {},
) {
return Object.freeze({
intentId: overrides.intentId ?? "intent-1",
operationId: "TEST_CREATE_ENTITY",
canonicalInputIdentity: "opaque-input-identity",
...(overrides.idempotencyKey === undefined
? { idempotencyKey: "key-1" }
: { idempotencyKey: overrides.idempotencyKey }),
createdAtMonotonicMs: 1,
});
}
function operation(
overrides: Readonly<{
deadlineMs?: number;
@@ -47,6 +61,129 @@ async function flushMicrotasks(): Promise<void> {
}
describe("descriptor-driven HTTP execution lifetime", () => {
it("reuses one supplied idempotency key across every physical retry", async () => {
const observedKeys: Array<string | null> = [];
let attempt = 0;
const fetcher = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
observedKeys.push(new Headers(init?.headers).get("Idempotency-Key"));
attempt += 1;
if (attempt === 1) throw new TypeError("synchronous pre-dispatch failure");
return Promise.resolve(
Response.json(
{ id: "created", name: "Created" },
{ status: 201 },
),
);
});
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 1,
attachCredentials: () => ({
kind: "READY",
headers: {},
credentials: "omit",
}),
fetcher,
sleep: async () => {},
random: () => 0,
});
const retryingCreate = {
...createInstalled,
frontend: {
...createInstalled.frontend,
retryBudget: 1 as const,
},
};
await expect(
executor.execute(
retryingCreate,
{ name: "created" },
{ scope, intent: mutationIntent({ idempotencyKey: "logical-key" }) },
),
).resolves.toMatchObject({ kind: "SUCCESS" });
expect(fetcher).toHaveBeenCalledTimes(2);
expect(observedKeys).toEqual(["logical-key", "logical-key"]);
});
it("never emits a mutation idempotency header for a query", async () => {
const observedKeys: Array<string | null> = [];
const fetcher = vi.fn(
async (_input: RequestInfo | URL, init?: RequestInit) => {
observedKeys.push(
new Headers(init?.headers).get("Idempotency-Key"),
);
return Response.json([]);
},
);
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY",
headers: {},
credentials: "omit",
}),
fetcher,
});
await expect(
executor.execute(
installed,
{ limit: 20 },
{ scope },
),
).resolves.toMatchObject({ kind: "SUCCESS" });
expect(fetcher).toHaveBeenCalledOnce();
expect(observedKeys).toEqual([null]);
});
it("keeps intent identities out of request URLs and safe observations", async () => {
const urls: string[] = [];
const observations: unknown[] = [];
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
attachCredentials: () => ({
kind: "READY",
headers: {},
credentials: "omit",
}),
fetcher: vi.fn(async (input) => {
urls.push(String(input));
return Response.json(
{ id: "created", name: "Created" },
{ status: 201 },
);
}),
observe: (observation) => observations.push(observation),
});
await expect(
executor.execute(
createInstalled,
{ name: "created" },
{
scope,
intent: Object.freeze({
intentId: "private-intent-id",
operationId: "TEST_CREATE_ENTITY",
canonicalInputIdentity: "private-canonical-input",
idempotencyKey: "private-idempotency-key",
createdAtMonotonicMs: 1,
}),
},
),
).resolves.toMatchObject({ kind: "SUCCESS" });
const safeEvidence = JSON.stringify({ urls, observations });
expect(urls).toEqual(["https://api.example/api/test-entities"]);
expect(observations).toHaveLength(1);
expect(safeEvidence).not.toContain("private-intent-id");
expect(safeEvidence).not.toContain("private-canonical-input");
expect(safeEvidence).not.toContain("private-idempotency-key");
});
it.each([
[{}, "limit=20"],
[{ limit: "7" }, "limit=7"],
@@ -127,7 +264,7 @@ describe("descriptor-driven HTTP execution lifetime", () => {
{ name: "created" },
{
scope,
intent: { intentId: "intent-1", startedBy: "USER", idempotencyKey: "key-1" },
intent: mutationIntent(),
},
),
).resolves.toMatchObject({
@@ -169,7 +306,7 @@ describe("descriptor-driven HTTP execution lifetime", () => {
{ name: "created" },
{
scope: fencedScope,
intent: { intentId: "intent-2", startedBy: "USER", idempotencyKey: "key-2" },
intent: mutationIntent({ intentId: "intent-2", idempotencyKey: "key-2" }),
},
),
).resolves.toMatchObject({
tests/unit/runtime-adapters.test.ts
+120
View File
@@ -4,6 +4,7 @@ import {
createRuntimeAdapters,
createRuntimeHttpClient,
} from "../../src/bootstrap/runtime-adapters.ts";
import { createBrowserMutationIntentFactory } from "../../src/adapters/platform/browser-mutation-intent-factory.ts";
import { TEST_HTTP_CONTRACT } from "../helpers/http-contract-fixture.ts";
type Runtime = Parameters<typeof createRuntimeAdapters>[0]["runtime"];
@@ -53,6 +54,65 @@ const release: Release = {
};
describe("runtime adapter composition", () => {
it("creates validated intent and idempotency identities with independent UUID calls", () => {
const randomUUID = vi
.fn<() => string>()
.mockReturnValueOnce("intent-uuid")
.mockReturnValueOnce("idempotency-uuid");
const factory = createBrowserMutationIntentFactory({
randomUUID,
monotonicNow: () => 12.5,
});
const intent = factory.create({
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "opaque-canonical-input",
requiresIdempotencyKey: true,
});
expect(intent).toEqual({
intentId: "intent-uuid",
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "opaque-canonical-input",
idempotencyKey: "idempotency-uuid",
createdAtMonotonicMs: 12.5,
});
expect(Object.isFrozen(intent)).toBe(true);
expect(randomUUID).toHaveBeenCalledTimes(2);
});
it("rejects invalid or unbounded mutation intent values", () => {
const factory = createBrowserMutationIntentFactory({
randomUUID: () => "opaque-runtime-identifier",
monotonicNow: () => 1,
});
expect(() =>
factory.create({
operationId: " ",
canonicalInputIdentity: "valid-identity",
requiresIdempotencyKey: false,
}),
).toThrow(TypeError);
expect(() =>
factory.create({
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "x".repeat(16_385),
requiresIdempotencyKey: false,
}),
).toThrow(TypeError);
expect(() =>
createBrowserMutationIntentFactory({
randomUUID: () => "opaque-runtime-identifier",
monotonicNow: () => -1,
}).create({
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "valid-identity",
requiresIdempotencyKey: false,
}),
).toThrow(TypeError);
});
it("constructs the local demo seam and infrastructure adapters", async () => {
const adapters = await createRuntimeAdapters({
runtime,
@@ -66,6 +126,7 @@ describe("runtime adapter composition", () => {
});
expect(adapters.infrastructure.queryClient).toBeDefined();
expect(adapters.infrastructure.queryInvalidation).toBeDefined();
expect(adapters.infrastructure.mutationIntentFactory).toBeDefined();
expect(
adapters.infrastructure.crossContextInvalidationStatus(),
).toBe("DEGRADED_LOCAL_ONLY");
@@ -81,6 +142,8 @@ describe("runtime adapter composition", () => {
const adapters = await createRuntimeAdapters({ runtime, release, host: {} });
const previousClient = adapters.infrastructure.queryClient;
const previousCoordinator = adapters.infrastructure.queryInvalidation;
const runtimeMutationIntentFactory =
adapters.infrastructure.mutationIntentFactory;
const clearPrevious = vi.spyOn(previousClient, "clear");
await adapters.outputPorts.session.beginSignIn();
@@ -91,6 +154,9 @@ describe("runtime adapter composition", () => {
expect(adapters.infrastructure.queryInvalidation).not.toBe(
previousCoordinator,
);
expect(adapters.infrastructure.mutationIntentFactory).toBe(
runtimeMutationIntentFactory,
);
const clearCallsAfterReplacement = clearPrevious.mock.calls.length;
await previousCoordinator.resetLocal();
@@ -99,6 +165,60 @@ describe("runtime adapter composition", () => {
adapters.infrastructure.dispose();
});
it("passes the supplied command intent unchanged and keeps private identity out of URLs and diagnostics", async () => {
const requests: Array<Readonly<{ url: string; headers: Headers }>> = [];
const fetcher = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
requests.push({
url: String(input),
headers: new Headers(init?.headers),
});
return Response.json(
{ id: "resource-1", name: "Created resource" },
{ status: 201 },
);
});
const adapters = await createRuntimeAdapters({
runtime,
release,
host: {},
fetcher,
});
await adapters.outputPorts.session.beginSignIn();
await vi.waitFor(() =>
expect(adapters.infrastructure.serverStateScope.getPhase()).toBe("READY"),
);
const intent = Object.freeze({
intentId: "private-intent-id",
operationId: "CREATE_REFERENCE_RESOURCE",
canonicalInputIdentity: "private-canonical-input",
idempotencyKey: "private-idempotency-key",
createdAtMonotonicMs: 42,
});
await expect(
adapters.featureInputs["reference-feature"].createResource(
{ name: "Created resource" },
{ intent },
),
).resolves.toMatchObject({ ok: true });
expect(requests).toHaveLength(1);
expect(requests[0]?.headers.get("Idempotency-Key")).toBe(
"private-idempotency-key",
);
expect(requests[0]?.url).toBe(
"http://localhost:8080/api/reference-resources",
);
const safeEvidence = JSON.stringify({
requests: requests.map((request) => request.url),
diagnostics: adapters.outputPorts.diagnostics.entries(),
});
expect(safeEvidence).not.toContain("private-intent-id");
expect(safeEvidence).not.toContain("private-canonical-input");
expect(safeEvidence).not.toContain("private-idempotency-key");
adapters.infrastructure.dispose();
});
it("does not fail boot when Web Storage capability getters throw", async () => {
const host: Record<string, unknown> = {};
Object.defineProperties(host, {