feat: execute HTTP and query runtime contracts

src/presentation/adapters/query/application-query.ts

@@ -0,0 +1,194 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
+
+import {
+  deriveAsyncState,
+  type AsyncState,
+} from "../../../application/view-models/async-state.js";
+import type { ApiFailure } from "../../../contracts/errors.js";
+
+export type ApplicationResult<Value> =
+  | Readonly<{ ok: true; value: Value }>
+  | Readonly<{ ok: false; error: ApiFailure }>;
+
+class ApplicationQueryError extends Error {
+  readonly failure: ApiFailure;
+
+  constructor(failure: ApiFailure) {
+    super(failure.kind);
+    this.name = "ApplicationQueryError";
+    this.failure = failure;
+  }
+}
+
+export function useApplicationQuery<Value>(
+  options: Readonly<{
+    queryKey: readonly unknown[];
+    execute(context: Readonly<{ signal: AbortSignal }>): Promise<
+      ApplicationResult<Value>
+    >;
+    enabled?: boolean;
+  }>,
+): Readonly<{
+  data: Value | undefined;
+  state: AsyncState;
+  retry(): Promise<void>;
+}> {
+  const { queryKey, execute, enabled = true } = options;
+  const [staleFailure, setStaleFailure] = useState(false);
+  const query = useQuery<Value, ApplicationQueryError>({
+    queryKey,
+    enabled,
+    retry: false,
+    queryFn: async ({ signal }) => {
+      const result = await execute({ signal });
+      if (result.ok) return result.value;
+      if (signal.aborted || result.error.kind === "REQUEST_ABORTED") {
+        throw new DOMException("Query cancelled", "AbortError");
+      }
+      throw new ApplicationQueryError(result.error);
+    },
+  });
+  const hasData = query.data !== undefined && query.data !== null;
+
+  useEffect(() => {
+    if (query.isError && hasData) {
+      setStaleFailure(true);
+    } else if (query.isSuccess && !query.isFetching) {
+      setStaleFailure(false);
+    }
+  }, [hasData, query.isError, query.isFetching, query.isSuccess]);
+
+  const retry = useCallback(async () => {
+    setStaleFailure(false);
+    await query.refetch();
+  }, [query]);
+
+  return Object.freeze({
+    data: query.data,
+    state: deriveAsyncState({
+      data: query.data,
+      isInitialLoading: query.isPending,
+      failure:
+        !hasData && query.error instanceof ApplicationQueryError
+          ? query.error.failure
+          : undefined,
+      isFetching: query.isFetching && !query.isPending,
+      isStale: staleFailure,
+      isDegraded: staleFailure,
+    }),
+    retry,
+  });
+}
+
+export function useApplicationMutation<Input, Value>(
+  options: Readonly<{
+    execute(input: Input): Promise<ApplicationResult<Value>>;
+    invalidate?: readonly (readonly unknown[])[];
+    optimistic?: Readonly<{
+      queryKey: readonly unknown[];
+      update(previous: unknown, input: Input): unknown;
+    }>;
+    currentData?: unknown;
+  }>,
+): Readonly<{
+  state: AsyncState;
+  submit(input: Input): Promise<ApplicationResult<Value>>;
+  resolveConflict(): Promise<void>;
+}> {
+  const queryClient = useQueryClient();
+  const { execute, invalidate = [], optimistic, currentData } = options;
+  const [conflict, setConflict] = useState<ApiFailure | null>(null);
+  const inFlight = useRef<Promise<ApplicationResult<Value>> | null>(null);
+  const mutation = useMutation<Value, ApplicationQueryError, Input>({
+    retry: false,
+    mutationFn: async (input) => {
+      const result = await execute(input);
+      if (result.ok) return result.value;
+      throw new ApplicationQueryError(result.error);
+    },
+  });
+
+  const submit = useCallback(
+    (input: Input): Promise<ApplicationResult<Value>> => {
+      if (inFlight.current) return inFlight.current;
+      setConflict(null);
+      mutation.reset();
+
+      const previous = optimistic
+        ? queryClient.getQueryData(optimistic.queryKey)
+        : undefined;
+      if (optimistic) {
+        queryClient.setQueryData(
+          optimistic.queryKey,
+          optimistic.update(previous, input),
+        );
+      }
+
+      const pending = mutation
+        .mutateAsync(input)
+        .then(async (value) => {
+          for (const queryKey of invalidate) {
+            await queryClient.invalidateQueries({ queryKey, exact: false });
+          }
+          return { ok: true as const, value };
+        })
+        .catch((error: unknown) => {
+          if (optimistic) {
+            queryClient.setQueryData(optimistic.queryKey, previous);
+          }
+          const failure =
+            error instanceof ApplicationQueryError
+              ? error.failure
+              : unexpectedMutationFailure();
+          if (failure.kind === "CONFLICT") setConflict(failure);
+          return { ok: false as const, error: failure };
+        })
+        .finally(() => {
+          inFlight.current = null;
+        });
+      inFlight.current = pending;
+      return pending;
+    },
+    [invalidate, mutation, optimistic, queryClient],
+  );
+
+  const resolveConflict = useCallback(async () => {
+    setConflict(null);
+    mutation.reset();
+    for (const queryKey of invalidate) {
+      await queryClient.invalidateQueries({ queryKey, exact: false });
+    }
+  }, [invalidate, mutation, queryClient]);
+
+  return Object.freeze({
+    state: deriveAsyncState({
+      data: currentData ?? true,
+      isMutationPending: mutation.isPending,
+      hasMutationConflict: conflict !== null,
+    }),
+    submit,
+    resolveConflict,
+  });
+}
+
+function unexpectedMutationFailure(): ApiFailure {
+  return {
+    kind: "UNKNOWN_FAILURE",
+    code: "UNKNOWN_FAILURE",
+    retryable: false,
+    operationId: "APPLICATION_MUTATION",
+    attemptCount: 1,
+    userMessageKey: "error.unknown_failure",
+    action: "contact-support",
+  };
+}

src/presentation/adapters/query/index.ts

@@ -0,0 +1,5 @@
+export {
+  useApplicationMutation,
+  useApplicationQuery,
+  type ApplicationResult,
+} from "./application-query.js";