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
src/adapters/http/http-effect-certainty.ts
-32
View File
@@ -104,38 +104,6 @@ export function classifyProblemEffect<Problem>(
});
}
export type MutationIntent = Readonly<{
intentId: string;
operationId: string;
canonicalInputIdentity: string;
idempotencyKey?: string;
createdAtMonotonicMs: number;
}>;
export type MutationIntentContext = Readonly<{
intentId: string;
idempotencyKey?: string;
startedBy: "USER" | "FOREGROUND_RETRY" | "OUTBOX_REPLAY";
}>;
export function createMutationIntent(
input: Readonly<{
operationId: string;
canonicalInputIdentity: string;
idempotencyKey?: string;
monotonicNow?: () => number;
}>,
): MutationIntent {
const now = input.monotonicNow ?? (() => performance.now());
return Object.freeze({
intentId: crypto.randomUUID(),
operationId: input.operationId,
canonicalInputIdentity: input.canonicalInputIdentity,
...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
createdAtMonotonicMs: now(),
});
}
/** §8.10. Certainty to UI intent. The copy itself is owned by the i18n catalog. */
export function projectCertaintyToUi(
certainty: MutationEffectCertainty,
src/adapters/http/http-execution-v3.ts
+3 -3
View File
@@ -4,6 +4,7 @@ import {
type InstalledHttpContract,
} from "../../contracts/external-contract-runtime.ts";
import type { CacheScopeSnapshot } from "../../contracts/server-state-scope.ts";
import type { MutationIntent } from "../../contracts/mutation-intent.ts";
import {
decodeJsonBytes,
isEffectivelyEmpty,
@@ -19,7 +20,6 @@ import {
import {
certaintyForAbandonedAttempt,
classifyProblemEffect,
type MutationIntentContext,
type PhysicalAttemptState,
} from "./http-effect-certainty.ts";
import { parseRetryAfter } from "./retry-policy.ts";
@@ -130,7 +130,7 @@ export type CancellationOwner =
export interface HttpExecutionContext {
readonly signal?: AbortSignal;
readonly scope: CacheScopeSnapshot;
readonly intent?: MutationIntentContext;
readonly intent?: MutationIntent;
}
export interface ContractHttpExecutor {
@@ -370,7 +370,7 @@ export function createContractHttpExecutor(
if (contract.requestBody === "JSON") {
headers["Content-Type"] = "application/json";
}
if (context.intent?.idempotencyKey) {
if (isCommand && context.intent?.idempotencyKey) {
headers["Idempotency-Key"] = context.intent.idempotencyKey;
}
src/adapters/platform/browser-mutation-intent-factory.ts
+50
View File
@@ -0,0 +1,50 @@
import type { MutationIntentFactory } from "../../application/ports/mutation-intent-factory.ts";
import { defineMutationIntent } from "../../contracts/mutation-intent.ts";
export type BrowserMutationIntentFactoryDependencies = Readonly<{
randomUUID?: () => string;
monotonicNow?: () => number;
}>;
export function createBrowserMutationIntentFactory(
dependencies: BrowserMutationIntentFactoryDependencies = {},
): MutationIntentFactory {
const randomUUID =
dependencies.randomUUID ??
(() => {
if (
typeof globalThis.crypto === "undefined" ||
typeof globalThis.crypto.randomUUID !== "function"
) {
throw new TypeError("Secure mutation identity generation is unavailable.");
}
return globalThis.crypto.randomUUID();
});
const monotonicNow =
dependencies.monotonicNow ??
(() => {
if (
typeof globalThis.performance === "undefined" ||
typeof globalThis.performance.now !== "function"
) {
throw new TypeError("Monotonic time is unavailable.");
}
return globalThis.performance.now();
});
return Object.freeze({
create(input) {
const intentId = randomUUID();
const idempotencyKey = input.requiresIdempotencyKey
? randomUUID()
: undefined;
return defineMutationIntent({
intentId,
operationId: input.operationId,
canonicalInputIdentity: input.canonicalInputIdentity,
...(idempotencyKey === undefined ? {} : { idempotencyKey }),
createdAtMonotonicMs: monotonicNow(),
});
},
});
}
src/application/ports/mutation-intent-factory.ts
+11
View File
@@ -0,0 +1,11 @@
import type { MutationIntent } from "../../contracts/mutation-intent.ts";
export type MutationIntentFactoryInput = Readonly<{
operationId: string;
canonicalInputIdentity: string;
requiresIdempotencyKey: boolean;
}>;
export type MutationIntentFactory = Readonly<{
create(input: MutationIntentFactoryInput): MutationIntent;
}>;
src/bootstrap/runtime-adapters.ts
+11 -17
View File
@@ -15,11 +15,13 @@ import { createQueryClient } from "../adapters/query-cache/tanstack-query-cache.
import { createServerStateScopeRuntime } from "../adapters/query-cache/server-state-scope-runtime.ts";
import { createConditionalValidatorStore } from "../adapters/query-cache/conditional-validator-store.ts";
import { createBrowserStorageAdapter } from "../adapters/storage/browser-storage-adapter.ts";
import { createBrowserMutationIntentFactory } from "../adapters/platform/browser-mutation-intent-factory.ts";
import { createTelemetryAdapter } from "../adapters/telemetry/best-effort-telemetry.ts";
import type { AuthSessionPort } from "../application/ports/auth-session-port.ts";
import type { ReleaseInfo } from "../application/ports/release-info-port.ts";
import { createRestProviderProfile } from "../contracts/rest-profiles.ts";
import type { ClockPort } from "../application/ports/clock-port.ts";
import type { MutationIntent } from "../contracts/mutation-intent.ts";
import { createInstalledFeatureInputs } from "../features/installed-feature-adapters.ts";
import {
INVALIDATION_REGISTRY,
@@ -166,6 +168,7 @@ export async function createRuntimeAdapters(
const host =
context.host ?? (globalThis as unknown as Record<string, unknown>);
const config = context.runtime.config;
const mutationIntentFactory = createBrowserMutationIntentFactory();
const externalOwner = externalOwnerFrom(host);
const authSession =
config.AUTH_MODE === "demo"
@@ -343,12 +346,14 @@ export async function createRuntimeAdapters(
}
},
});
let contractExecutionSequence = 0;
const contractOperations = Object.freeze({
async execute(
operationId: string,
input: unknown,
executionContext: Readonly<{ signal?: AbortSignal }> = {},
executionContext: Readonly<{
signal?: AbortSignal;
intent?: MutationIntent;
}> = {},
) {
const operation =
COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.get(operationId);
@@ -362,26 +367,14 @@ export async function createRuntimeAdapters(
}),
});
}
contractExecutionSequence += 1;
const intentId = `http-intent-${contractExecutionSequence}`;
const isCommand = operation.contract.commandEffect !== null;
const requiresKey = operation.contract.retrySemantics === "KEYED";
const outcome = await contractHttp.execute(operation, input, {
scope: serverStateScope.getSnapshot(),
...(executionContext.signal === undefined
? {}
: { signal: executionContext.signal }),
...(isCommand
? {
intent: Object.freeze({
intentId,
startedBy: "USER" as const,
...(requiresKey
? { idempotencyKey: `http-key-${contractExecutionSequence}` }
: {}),
}),
}
: {}),
...(executionContext.intent === undefined
? {}
: { intent: executionContext.intent }),
});
if (outcome.kind === "UNAUTHENTICATED") {
authSession.onUnauthenticated();
@@ -412,6 +405,7 @@ export async function createRuntimeAdapters(
},
serverStateGeneration,
serverStateScope,
mutationIntentFactory,
conditionalValidators,
crossContextInvalidationStatus: () =>
serverStateGeneration.getSnapshot().crossContextStatus(),
src/bootstrap/runtime-application.tsx
+3
View File
@@ -31,6 +31,9 @@ export function RuntimeApplication({
<ServerStateGenerationProvider
store={composition.infrastructure.serverStateGeneration}
scope={composition.infrastructure.serverStateScope}
mutationIntentFactory={
composition.infrastructure.mutationIntentFactory
}
transitionFallback={
<div
aria-busy="true"
src/contracts/mutation-intent.ts
+59
View File
@@ -0,0 +1,59 @@
export const MUTATION_INTENT_BOUNDS = Object.freeze({
intentIdMaxBytes: 256,
operationIdMaxBytes: 256,
canonicalInputIdentityMaxBytes: 16_384,
idempotencyKeyMaxBytes: 256,
} as const);
export type MutationIntent = Readonly<{
intentId: string;
operationId: string;
canonicalInputIdentity: string;
idempotencyKey?: string;
createdAtMonotonicMs: number;
}>;
const UTF8 = new TextEncoder();
function validBoundedString(value: unknown, maxBytes: number): value is string {
return (
typeof value === "string" &&
value.trim().length > 0 &&
UTF8.encode(value).byteLength <= maxBytes
);
}
export function defineMutationIntent(intent: MutationIntent): MutationIntent {
if (
!validBoundedString(
intent.intentId,
MUTATION_INTENT_BOUNDS.intentIdMaxBytes,
) ||
!validBoundedString(
intent.operationId,
MUTATION_INTENT_BOUNDS.operationIdMaxBytes,
) ||
!validBoundedString(
intent.canonicalInputIdentity,
MUTATION_INTENT_BOUNDS.canonicalInputIdentityMaxBytes,
) ||
(intent.idempotencyKey !== undefined &&
!validBoundedString(
intent.idempotencyKey,
MUTATION_INTENT_BOUNDS.idempotencyKeyMaxBytes,
)) ||
!Number.isFinite(intent.createdAtMonotonicMs) ||
intent.createdAtMonotonicMs < 0
) {
throw new TypeError("Mutation intent is invalid.");
}
return Object.freeze({
intentId: intent.intentId,
operationId: intent.operationId,
canonicalInputIdentity: intent.canonicalInputIdentity,
...(intent.idempotencyKey === undefined
? {}
: { idempotencyKey: intent.idempotencyKey }),
createdAtMonotonicMs: intent.createdAtMonotonicMs,
});
}
src/contracts/server-state.ts
+3 -1
View File
@@ -6,6 +6,7 @@ import {
type RuntimeIdentityBinding,
} from "./query-keys.ts";
import type { CacheScopeSnapshot } from "./server-state-scope.ts";
import type { MutationIntent } from "./mutation-intent.ts";
/**
* §10.2. The four fixed profiles. A feature selects one by ID; it never
@@ -234,12 +235,13 @@ export type BoundMutation<Input, Value> = Readonly<{
definitionId: string;
definitionVersion: number;
operationId: string;
requiresIdempotencyKey: boolean;
owner: string;
duplicatePolicy: MutationDuplicatePolicy;
scope: CacheScopeSnapshot;
execute(
input: Input,
context: Readonly<{ signal: AbortSignal }>,
context: Readonly<{ signal: AbortSignal; intent: MutationIntent }>,
): Promise<Result<Value>>;
invalidate: readonly QueryInvalidationTopic[];
optimistic?: Readonly<{
src/features/reference-feature/adapters/create-reference-feature-input.ts
+10 -2
View File
@@ -1,6 +1,7 @@
import type { Result } from "../../../application/result.ts";
import type { ApiFailure, FailureKind } from "../../../contracts/errors.ts";
import type { FailureEffectCertainty } from "../../../contracts/errors.ts";
import type { MutationIntent } from "../../../contracts/mutation-intent.ts";
import {
createFailure,
kindForStatus,
@@ -22,7 +23,10 @@ export type InstalledContractOperationExecutor = Readonly<{
execute(
operationId: string,
input: unknown,
context?: Readonly<{ signal?: AbortSignal }>,
context?: Readonly<{
signal?: AbortSignal;
intent?: MutationIntent;
}>,
): Promise<HttpExecutionOutcome<unknown, unknown>>;
}>;
@@ -39,10 +43,14 @@ export function createReferenceFeatureInstalledInput(context: Readonly<{
const operationId = request.operationId;
const input = inputFor(request);
const signal = "signal" in request ? request.signal : undefined;
const intent = "intent" in request ? request.intent : undefined;
const outcome = await context.contractOperations.execute(
operationId,
input,
signal === undefined ? {} : { signal },
{
...(signal === undefined ? {} : { signal }),
...(intent === undefined ? {} : { intent }),
},
);
return projectExecutionOutcome(operationId, outcome);
},
src/features/reference-feature/adapters/reference-http-gateway.ts
+7 -1
View File
@@ -9,6 +9,7 @@ import type {
ReferenceListFilters,
} from "../application/reference-feature-api.ts";
import type { ReferenceResource } from "../domain/reference-resource.ts";
import type { MutationIntent } from "../../../contracts/mutation-intent.ts";
type ReferenceOperationMap = Readonly<{
LIST_REFERENCE_RESOURCES: Readonly<{
@@ -26,6 +27,7 @@ type ReferenceOperationMap = Readonly<{
routeId: "REFERENCE_RESOURCE_LIST";
body: ReferenceCreateCommand;
signal?: AbortSignal;
intent?: MutationIntent;
}>;
value: ReferenceResource;
}>;
@@ -74,13 +76,17 @@ export function createReferenceHttpGateway(
},
async create(
command: ReferenceCreateCommand,
context?: Readonly<{ signal?: AbortSignal }>,
context?: Readonly<{
signal?: AbortSignal;
intent?: MutationIntent;
}>,
) {
const result = await http.execute({
operationId: "CREATE_REFERENCE_RESOURCE",
routeId: "REFERENCE_RESOURCE_LIST",
body: command,
signal: context?.signal,
intent: context?.intent,
});
return projectResourceResult("CREATE_REFERENCE_RESOURCE", result);
},
src/features/reference-feature/application/reference-feature-api.ts
+9 -2
View File
@@ -5,6 +5,7 @@ import {
type ReferenceResourceView,
} from "../contracts/reference-mapper.ts";
import type { ReferenceResource } from "../domain/reference-resource.ts";
import type { MutationIntent } from "../../../contracts/mutation-intent.ts";
export type ReferenceListFilters = Readonly<{
cursor?: string;
@@ -26,7 +27,10 @@ export type ReferenceFeatureInput = Readonly<{
): Promise<ReferenceResult<readonly ReferenceResourceView[]>>;
createResource(
command: ReferenceCreateCommand,
context?: Readonly<{ signal?: AbortSignal }>,
context?: Readonly<{
signal?: AbortSignal;
intent?: MutationIntent;
}>,
): Promise<ReferenceResult<ReferenceResourceView>>;
getResource(
resourceId: string,
@@ -47,7 +51,10 @@ export type ReferenceGateway = Readonly<{
): Promise<ReferenceResult<readonly ReferenceResource[]>>;
create(
command: ReferenceCreateCommand,
context?: Readonly<{ signal?: AbortSignal }>,
context?: Readonly<{
signal?: AbortSignal;
intent?: MutationIntent;
}>,
): Promise<ReferenceResult<ReferenceResource>>;
get(
resourceId: string,
src/features/reference-feature/presentation/use-reference-feature.ts
+2
View File
@@ -87,6 +87,7 @@ export function useReferenceCreate() {
definitionId: "reference-resource-create-v1",
definitionVersion: 1,
operationId: "CREATE_REFERENCE_RESOURCE",
requiresIdempotencyKey: true,
owner: REFERENCE_FEATURE_ID,
duplicatePolicy: "REJECT_WHILE_ACTIVE",
scope,
@@ -123,6 +124,7 @@ export function useReferenceFeature() {
definitionId: "reference-resource-create-v1",
definitionVersion: 1,
operationId: "CREATE_REFERENCE_RESOURCE",
requiresIdempotencyKey: true,
owner: REFERENCE_FEATURE_ID,
duplicatePolicy: "REJECT_WHILE_ACTIVE",
scope,
src/presentation/adapters/query/application-query.ts
+47 -4
View File
@@ -21,6 +21,7 @@ import {
type AppFailure,
} from "../../../contracts/errors.ts";
import type { QueryInvalidationTopic } from "../../../contracts/query-invalidation.ts";
import type { MutationIntent } from "../../../contracts/mutation-intent.ts";
import {
admitQueryResult,
type BoundMutation,
@@ -29,6 +30,7 @@ import {
} from "../../../contracts/server-state.ts";
import { runtimeIdentityToken } from "../../../contracts/query-keys.ts";
import { useQueryInvalidationCoordinator } from "./query-invalidation-provider.tsx";
import { useMutationIntentFactory } from "./mutation-intent-provider.tsx";
import {
createOptimisticLayerRuntime,
type OptimisticLayerLease,
@@ -196,6 +198,10 @@ type ApplicationMutationController<Input, Value> = Readonly<{
resolveConflict(): Promise<void>;
}>;
type MutationExecution<Input> =
| Readonly<{ kind: "BOUND"; input: Input; intent: MutationIntent }>
| Readonly<{ kind: "LEGACY"; input: Input }>;
export function useApplicationMutation<Input, Value>(
options: BoundMutation<Input, Value>,
): ApplicationMutationController<Input, Value>;
@@ -207,6 +213,7 @@ export function useApplicationMutation<Input, Value>(
): ApplicationMutationController<Input, Value> {
const queryClient = useQueryClient();
const invalidationCoordinator = useQueryInvalidationCoordinator();
const mutationIntentFactory = useMutationIntentFactory();
const invalidate = useMemo(
() => options.invalidate ?? [],
[options.invalidate],
@@ -219,9 +226,20 @@ export function useApplicationMutation<Input, Value>(
"duplicatePolicy" in options ? options.duplicatePolicy : "REJECT_WHILE_ACTIVE";
const [conflict, setConflict] = useState<AppFailure | null>(null);
const scope = "scope" in options ? options.scope : undefined;
const mutation = useMutation<Value, ApplicationQueryError, Input>({
const mutationOperationId =
"operationId" in options ? options.operationId : definitionId;
const requiresIdempotencyKey =
"requiresIdempotencyKey" in options
? options.requiresIdempotencyKey
: false;
const mutation = useMutation<
Value,
ApplicationQueryError,
MutationExecution<Input>
>({
retry: false,
mutationFn: async (input) => {
mutationFn: async (execution) => {
const input = execution.input;
if (scope && !scope.isCurrent()) {
throw new ApplicationQueryError(
createFailure(
@@ -234,7 +252,17 @@ export function useApplicationMutation<Input, Value>(
}
const result =
"scope" in options
? await options.execute(input, { signal: options.scope.signal })
? 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 =
@@ -311,6 +339,18 @@ export function useApplicationMutation<Input, Value>(
mutation.reset();
const pending = (async (): Promise<ApplicationResult<Value>> => {
const execution: MutationExecution<Input> =
scope
? Object.freeze({
kind: "BOUND" as const,
input,
intent: mutationIntentFactory.create({
operationId: mutationOperationId,
canonicalInputIdentity: identity,
requiresIdempotencyKey,
}),
})
: Object.freeze({ kind: "LEGACY" as const, input });
const mutationLease =
invalidate.length === 0
? null
@@ -346,7 +386,7 @@ export function useApplicationMutation<Input, Value>(
let value: Value;
try {
value = await mutation.mutateAsync(input);
value = await mutation.mutateAsync(execution);
} catch (error: unknown) {
if (optimistic) {
if (optimisticLayer) {
@@ -411,6 +451,9 @@ export function useApplicationMutation<Input, Value>(
queryClient,
definitionId,
duplicatePolicy,
mutationIntentFactory,
mutationOperationId,
requiresIdempotencyKey,
scope,
],
);
src/presentation/adapters/query/mutation-intent-provider.tsx
+35
View File
@@ -0,0 +1,35 @@
import {
createContext,
type ReactNode,
useContext,
} from "react";
import type { MutationIntentFactory } from "../../../application/ports/mutation-intent-factory.ts";
const unavailableMutationIntentFactory: MutationIntentFactory = Object.freeze({
create() {
throw new TypeError("Mutation intent factory is not installed.");
},
});
const MutationIntentFactoryContext = createContext<MutationIntentFactory>(
unavailableMutationIntentFactory,
);
export function MutationIntentProvider({
factory,
children,
}: Readonly<{
factory: MutationIntentFactory;
children: ReactNode;
}>) {
return (
<MutationIntentFactoryContext.Provider value={factory}>
{children}
</MutationIntentFactoryContext.Provider>
);
}
export function useMutationIntentFactory(): MutationIntentFactory {
return useContext(MutationIntentFactoryContext);
}
src/presentation/adapters/query/server-state-generation-provider.tsx
+18 -12
View File
@@ -6,6 +6,8 @@ import { type ReactNode, useSyncExternalStore } from "react";
import type { QueryInvalidationCoordinator } from "../../../contracts/query-invalidation.ts";
import type { ServerStateScopeRuntime } from "../../../contracts/server-state-scope.ts";
import type { MutationIntentFactory } from "../../../application/ports/mutation-intent-factory.ts";
import { MutationIntentProvider } from "./mutation-intent-provider.tsx";
import { QueryInvalidationProvider } from "./query-invalidation-provider.tsx";
import { ServerStateScopeProvider } from "./server-state-scope-provider.tsx";
@@ -21,11 +23,13 @@ export type ServerStateGenerationSource = Readonly<{
export function ServerStateGenerationProvider({
store,
scope,
mutationIntentFactory,
children,
transitionFallback,
}: Readonly<{
store: ServerStateGenerationSource;
scope: ServerStateScopeRuntime;
mutationIntentFactory: MutationIntentFactory;
children: ReactNode;
transitionFallback?: ReactNode;
}>) {
@@ -35,18 +39,20 @@ export function ServerStateGenerationProvider({
store.getSnapshot,
);
return (
<QueryClientProvider
key={generation.generation}
client={generation.queryClient}
>
<ServerStateScopeProvider
runtime={scope}
transitionFallback={transitionFallback}
<MutationIntentProvider factory={mutationIntentFactory}>
<QueryClientProvider
key={generation.generation}
client={generation.queryClient}
>
<QueryInvalidationProvider coordinator={generation.queryInvalidation}>
{children}
</QueryInvalidationProvider>
</ServerStateScopeProvider>
</QueryClientProvider>
<ServerStateScopeProvider
runtime={scope}
transitionFallback={transitionFallback}
>
<QueryInvalidationProvider coordinator={generation.queryInvalidation}>
{children}
</QueryInvalidationProvider>
</ServerStateScopeProvider>
</QueryClientProvider>
</MutationIntentProvider>
);
}