feat: execute HTTP and query runtime contracts
This commit is contained in:
donghyeon-ka
+109
-32
@@ -12,6 +12,7 @@ import {
|
||||
validateOperationPayload,
|
||||
validateOperationRequest,
|
||||
} from "./schema-registry.js";
|
||||
import { buildRequestTarget } from "./request-builder.js";
|
||||
|
||||
const noAuthSession =
|
||||
/** @type {import("../../application/ports/auth-session-port.js").AuthSessionPort} */ ({
|
||||
@@ -22,6 +23,14 @@ const noAuthSession =
|
||||
});
|
||||
|
||||
/** @typedef {import("../../contracts/errors.js").ApiFailure} HttpFailure */
|
||||
/** @typedef {import("./request-builder.js").OperationRequestInput} OperationRequestInput */
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* setTimeout(callback: () => void, milliseconds: number): unknown,
|
||||
* clearTimeout(handle: unknown): void
|
||||
* }} Scheduler
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {{ ok: true, value: unknown, meta: Record<string, string> } |
|
||||
@@ -38,7 +47,11 @@ const noAuthSession =
|
||||
* validatePayload?: (schemaId: string, value: unknown) =>
|
||||
* { success: true, data: unknown } | { success: false },
|
||||
* mapPayload?: (operationId: string, payload: unknown) => unknown,
|
||||
* idempotencyKeyFactory?: () => string
|
||||
* idempotencyKeyFactory?: () => string,
|
||||
* timeoutMs?: number,
|
||||
* maxRetryAttempts?: number,
|
||||
* scheduler?: Scheduler,
|
||||
* getOperation?: typeof getApiOperation
|
||||
* }} dependencies
|
||||
*/
|
||||
export function createHttpClient(dependencies) {
|
||||
@@ -51,19 +64,46 @@ export function createHttpClient(dependencies) {
|
||||
const mapPayload = dependencies.mapPayload ?? mapOperationPayload;
|
||||
const idempotencyKeyFactory =
|
||||
dependencies.idempotencyKeyFactory ?? (() => crypto.randomUUID());
|
||||
const defaultTimeoutMs = dependencies.timeoutMs ?? 10_000;
|
||||
const maxRetryAttempts = dependencies.maxRetryAttempts ?? 2;
|
||||
const selectOperation = dependencies.getOperation ?? getApiOperation;
|
||||
const scheduler =
|
||||
dependencies.scheduler ??
|
||||
/** @type {Scheduler} */ ({
|
||||
setTimeout: (callback, milliseconds) =>
|
||||
globalThis.setTimeout(callback, milliseconds),
|
||||
clearTimeout: (handle) =>
|
||||
globalThis.clearTimeout(
|
||||
/** @type {ReturnType<typeof setTimeout>} */ (handle),
|
||||
),
|
||||
});
|
||||
|
||||
/**
|
||||
* @param {string} operationId
|
||||
* @param {string | OperationRequestInput} request
|
||||
* @param {{
|
||||
* body?: unknown,
|
||||
* routeId?: string,
|
||||
* signal?: AbortSignal,
|
||||
* idempotencyKey?: string
|
||||
* }} [input]
|
||||
* @returns {Promise<HttpResult>}
|
||||
*/
|
||||
async function execute(operationId, input = {}) {
|
||||
const operation = getApiOperation(operationId);
|
||||
* body?: unknown,
|
||||
* routeId?: string,
|
||||
* pathParams?: Record<string, string | number>,
|
||||
* searchParams?: unknown,
|
||||
* signal?: AbortSignal,
|
||||
* idempotencyKey?: string
|
||||
* }} [legacyInput]
|
||||
* @returns {Promise<HttpResult>}
|
||||
*/
|
||||
async function execute(request, legacyInput = {}) {
|
||||
const input =
|
||||
typeof request === "string"
|
||||
? {
|
||||
operationId: request,
|
||||
routeId: legacyInput.routeId ?? "UNSPECIFIED_ROUTE",
|
||||
pathParams: legacyInput.pathParams,
|
||||
searchParams: legacyInput.searchParams,
|
||||
body: legacyInput.body,
|
||||
signal: legacyInput.signal,
|
||||
idempotencyKey: legacyInput.idempotencyKey,
|
||||
}
|
||||
: request;
|
||||
const operation = selectOperation(input.operationId);
|
||||
const logicalIdempotencyKey =
|
||||
operation.idempotency === "keyed"
|
||||
? input.idempotencyKey ?? idempotencyKeyFactory()
|
||||
@@ -105,7 +145,14 @@ export function createHttpClient(dependencies) {
|
||||
return outcome;
|
||||
}
|
||||
|
||||
if (!shouldRetry(operation, outcome.error, retryCount)) {
|
||||
if (
|
||||
!shouldRetry(
|
||||
operation,
|
||||
outcome.error,
|
||||
retryCount,
|
||||
maxRetryAttempts,
|
||||
)
|
||||
) {
|
||||
return outcome;
|
||||
}
|
||||
|
||||
@@ -117,7 +164,7 @@ export function createHttpClient(dependencies) {
|
||||
} catch {
|
||||
return {
|
||||
ok: false,
|
||||
error: failure("REQUEST_ABORTED", operationId, retryCount, {
|
||||
error: failure("REQUEST_ABORTED", input.operationId, retryCount, {
|
||||
code: "REQUEST_ABORTED",
|
||||
}),
|
||||
};
|
||||
@@ -128,7 +175,7 @@ export function createHttpClient(dependencies) {
|
||||
/**
|
||||
* @param {{
|
||||
* operation: ReturnType<typeof getApiOperation>,
|
||||
* input: { body?: unknown, routeId?: string, signal?: AbortSignal },
|
||||
* input: OperationRequestInput,
|
||||
* attempt: number,
|
||||
* idempotencyKey?: string
|
||||
* }} context
|
||||
@@ -136,23 +183,19 @@ export function createHttpClient(dependencies) {
|
||||
*/
|
||||
async function performAttempt(context) {
|
||||
const { operation, input, attempt, idempotencyKey } = context;
|
||||
const controller = new AbortController();
|
||||
let timedOut = false;
|
||||
const timeout = setTimeout(() => {
|
||||
timedOut = true;
|
||||
controller.abort("timeout");
|
||||
}, operation.timeoutMs);
|
||||
const onExternalAbort = () => controller.abort(input.signal?.reason);
|
||||
input.signal?.addEventListener("abort", onExternalAbort, { once: true });
|
||||
|
||||
const headers = new Headers({ Accept: "application/json" });
|
||||
if (input.body !== undefined) headers.set("Content-Type", "application/json");
|
||||
if (idempotencyKey) headers.set("Idempotency-Key", idempotencyKey);
|
||||
|
||||
if (input.body !== undefined) {
|
||||
/** @type {unknown} */
|
||||
let parsedSearch = {};
|
||||
let parsedBody;
|
||||
const requestValue =
|
||||
operation.requestSource === "search"
|
||||
? input.searchParams ?? {}
|
||||
: operation.requestSource === "body"
|
||||
? input.body
|
||||
: {};
|
||||
if (operation.requestSource !== "none") {
|
||||
const requestValidation = validateOperationRequest(
|
||||
operation.requestSchema,
|
||||
input.body,
|
||||
requestValue,
|
||||
);
|
||||
if (!requestValidation.success) {
|
||||
return {
|
||||
@@ -162,12 +205,46 @@ export function createHttpClient(dependencies) {
|
||||
}),
|
||||
};
|
||||
}
|
||||
if (operation.requestSource === "search") {
|
||||
parsedSearch = requestValidation.data;
|
||||
} else {
|
||||
parsedBody = requestValidation.data;
|
||||
}
|
||||
}
|
||||
|
||||
let request = new Request(new URL(operation.path, dependencies.baseUrl), {
|
||||
const target = buildRequestTarget(
|
||||
dependencies.baseUrl,
|
||||
operation,
|
||||
input.pathParams,
|
||||
parsedSearch,
|
||||
);
|
||||
if (!target.success) {
|
||||
return {
|
||||
ok: false,
|
||||
error: failure("VALIDATION_REJECTED", operation.operationId, attempt, {
|
||||
code: target.code,
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
const controller = new AbortController();
|
||||
let timedOut = false;
|
||||
const timeout = scheduler.setTimeout(() => {
|
||||
timedOut = true;
|
||||
controller.abort("timeout");
|
||||
}, operation.timeoutMs ?? defaultTimeoutMs);
|
||||
const onExternalAbort = () => controller.abort(input.signal?.reason);
|
||||
input.signal?.addEventListener("abort", onExternalAbort, { once: true });
|
||||
if (input.signal?.aborted) onExternalAbort();
|
||||
|
||||
const headers = new Headers({ Accept: "application/json" });
|
||||
if (parsedBody !== undefined) headers.set("Content-Type", "application/json");
|
||||
if (idempotencyKey) headers.set("Idempotency-Key", idempotencyKey);
|
||||
|
||||
let request = new Request(target.url, {
|
||||
method: operation.method,
|
||||
headers,
|
||||
body: input.body === undefined ? undefined : JSON.stringify(input.body),
|
||||
body: parsedBody === undefined ? undefined : JSON.stringify(parsedBody),
|
||||
signal: controller.signal,
|
||||
});
|
||||
|
||||
@@ -237,7 +314,7 @@ export function createHttpClient(dependencies) {
|
||||
}),
|
||||
};
|
||||
} finally {
|
||||
clearTimeout(timeout);
|
||||
scheduler.clearTimeout(timeout);
|
||||
input.signal?.removeEventListener("abort", onExternalAbort);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
import type { ApiOperation } from "../../contracts/api-operations.js";
|
||||
|
||||
export type OperationRequestInput = Readonly<{
|
||||
operationId: string;
|
||||
routeId: string;
|
||||
pathParams?: Readonly<Record<string, string | number>>;
|
||||
searchParams?: unknown;
|
||||
body?: unknown;
|
||||
signal?: AbortSignal;
|
||||
idempotencyKey?: string;
|
||||
}>;
|
||||
|
||||
export type RequestTargetResult =
|
||||
| Readonly<{ success: true; url: URL }>
|
||||
| Readonly<{
|
||||
success: false;
|
||||
code: "PATH_PARAMETER_MISSING" | "SEARCH_PARAMETER_INVALID";
|
||||
}>;
|
||||
|
||||
const pathParameterPattern = /:([A-Za-z][A-Za-z0-9_]*)|\{([A-Za-z][A-Za-z0-9_]*)\}/g;
|
||||
|
||||
export function buildRequestTarget(
|
||||
baseUrl: string,
|
||||
operation: ApiOperation,
|
||||
pathParams: Readonly<Record<string, string | number>> = {},
|
||||
parsedSearch: unknown = {},
|
||||
): RequestTargetResult {
|
||||
let missingPathParameter = false;
|
||||
const pathname = operation.path.replace(
|
||||
pathParameterPattern,
|
||||
(_token, colonName: string | undefined, braceName: string | undefined) => {
|
||||
const name = colonName ?? braceName ?? "";
|
||||
const value = pathParams[name];
|
||||
if (value === undefined) {
|
||||
missingPathParameter = true;
|
||||
return "";
|
||||
}
|
||||
return encodeURIComponent(String(value));
|
||||
},
|
||||
);
|
||||
if (missingPathParameter) {
|
||||
return { success: false, code: "PATH_PARAMETER_MISSING" };
|
||||
}
|
||||
|
||||
if (
|
||||
parsedSearch === null ||
|
||||
typeof parsedSearch !== "object" ||
|
||||
Array.isArray(parsedSearch)
|
||||
) {
|
||||
return { success: false, code: "SEARCH_PARAMETER_INVALID" };
|
||||
}
|
||||
|
||||
const url = new URL(pathname, baseUrl);
|
||||
const search = parsedSearch as Readonly<Record<string, unknown>>;
|
||||
for (const key of Object.keys(search).sort((left, right) =>
|
||||
left.localeCompare(right),
|
||||
)) {
|
||||
const value = search[key];
|
||||
if (value === undefined || value === null) continue;
|
||||
const values = Array.isArray(value) ? value : [value];
|
||||
for (const item of values) {
|
||||
if (
|
||||
typeof item !== "string" &&
|
||||
typeof item !== "number" &&
|
||||
typeof item !== "boolean"
|
||||
) {
|
||||
return { success: false, code: "SEARCH_PARAMETER_INVALID" };
|
||||
}
|
||||
url.searchParams.append(key, String(item));
|
||||
}
|
||||
}
|
||||
return { success: true, url };
|
||||
}
|
||||
@@ -35,12 +35,13 @@ export function parseRetryAfter(value, now = Date.now()) {
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{ idempotency: "safe" | "keyed" | "none" }} operation
|
||||
* @param {{ idempotency: "safe" | "keyed" | "none", retry?: "runtime" | "never" }} operation
|
||||
* @param {{ kind: string, retryAfterMs?: number, httpStatus?: number }} failure
|
||||
* @param {number} retryCount
|
||||
* @param {number} [maxRetries]
|
||||
*/
|
||||
export function shouldRetry(operation, failure, retryCount, maxRetries = 2) {
|
||||
if (operation.retry === "never") return false;
|
||||
if (retryCount >= maxRetries) return false;
|
||||
if (!retryKinds.has(failure.kind)) return false;
|
||||
if (
|
||||
|
||||
@@ -57,6 +57,7 @@ const requestSchemas =
|
||||
.object({
|
||||
cursor: z.string().optional(),
|
||||
limit: z.int().min(1).max(100).default(20),
|
||||
tags: z.array(z.string().trim().min(1)).optional(),
|
||||
})
|
||||
.strict(),
|
||||
CreateSampleResourceCommand: z
|
||||
|
||||
@@ -8,9 +8,13 @@ export const systemClock = Object.freeze({
|
||||
return;
|
||||
}
|
||||
|
||||
const timer = setTimeout(resolve, milliseconds);
|
||||
const timer = setTimeout(() => {
|
||||
signal?.removeEventListener("abort", onAbort);
|
||||
resolve();
|
||||
}, milliseconds);
|
||||
const onAbort = () => {
|
||||
clearTimeout(timer);
|
||||
signal?.removeEventListener("abort", onAbort);
|
||||
reject(signal?.reason);
|
||||
};
|
||||
signal?.addEventListener("abort", onAbort, { once: true });
|
||||
|
||||
@@ -1,81 +0,0 @@
|
||||
export const ASYNC_BASE_STATES = Object.freeze([
|
||||
"initial-loading",
|
||||
"success",
|
||||
"empty",
|
||||
"terminal-error",
|
||||
]);
|
||||
|
||||
export const ASYNC_OVERLAYS = Object.freeze([
|
||||
"refreshing",
|
||||
"stale-degraded",
|
||||
"mutation-pending",
|
||||
"mutation-conflict",
|
||||
]);
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* data?: unknown,
|
||||
* isInitialLoading?: boolean,
|
||||
* failure?: import("../../contracts/errors.js").ApiFailure,
|
||||
* isFetching?: boolean,
|
||||
* isStale?: boolean,
|
||||
* isDegraded?: boolean,
|
||||
* isMutationPending?: boolean,
|
||||
* hasMutationConflict?: boolean
|
||||
* }} AsyncSignals
|
||||
*/
|
||||
|
||||
/** @param {AsyncSignals} signals */
|
||||
export function deriveAsyncState(signals) {
|
||||
const hasData = signals.data !== undefined && signals.data !== null;
|
||||
const empty =
|
||||
hasData &&
|
||||
((Array.isArray(signals.data) && signals.data.length === 0) ||
|
||||
signals.data === "");
|
||||
|
||||
let base;
|
||||
if (signals.isInitialLoading && !hasData) {
|
||||
base = "initial-loading";
|
||||
} else if (signals.failure && !hasData) {
|
||||
base = "terminal-error";
|
||||
} else if (empty) {
|
||||
base = "empty";
|
||||
} else if (hasData) {
|
||||
base = "success";
|
||||
} else {
|
||||
base = "initial-loading";
|
||||
}
|
||||
|
||||
const overlay = Object.freeze({
|
||||
refreshing: Boolean(signals.isFetching && hasData),
|
||||
staleDegraded: Boolean(signals.isStale && signals.isDegraded && hasData),
|
||||
mutationPending: Boolean(signals.isMutationPending && hasData),
|
||||
mutationConflict: Boolean(signals.hasMutationConflict && hasData),
|
||||
});
|
||||
|
||||
const state = {
|
||||
base,
|
||||
data: base === "success" || base === "empty" ? signals.data : undefined,
|
||||
failure: base === "terminal-error" ? signals.failure : undefined,
|
||||
overlay,
|
||||
indicator: selectOverlayIndicator(overlay),
|
||||
};
|
||||
|
||||
return Object.freeze(state);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{
|
||||
* refreshing: boolean,
|
||||
* staleDegraded: boolean,
|
||||
* mutationPending: boolean,
|
||||
* mutationConflict: boolean
|
||||
* }} overlay
|
||||
*/
|
||||
export function selectOverlayIndicator(overlay) {
|
||||
if (overlay.mutationConflict) return "mutation-conflict";
|
||||
if (overlay.mutationPending) return "mutation-pending";
|
||||
if (overlay.staleDegraded) return "stale-degraded";
|
||||
if (overlay.refreshing) return "refreshing";
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,156 @@
|
||||
import type { ApiFailure } from "../../contracts/errors.js";
|
||||
|
||||
export const ASYNC_BASE_STATES = Object.freeze([
|
||||
"initial-loading",
|
||||
"success",
|
||||
"empty",
|
||||
"terminal-error",
|
||||
] as const);
|
||||
|
||||
export const ASYNC_OVERLAYS = Object.freeze([
|
||||
"refreshing",
|
||||
"stale-degraded",
|
||||
"mutation-pending",
|
||||
"mutation-conflict",
|
||||
] as const);
|
||||
|
||||
export type AsyncOverlay =
|
||||
| Readonly<{
|
||||
refreshing: false;
|
||||
staleDegraded: false;
|
||||
mutationPending: false;
|
||||
mutationConflict: false;
|
||||
}>
|
||||
| Readonly<{
|
||||
refreshing: true;
|
||||
staleDegraded: false;
|
||||
mutationPending: false;
|
||||
mutationConflict: false;
|
||||
}>
|
||||
| Readonly<{
|
||||
refreshing: false;
|
||||
staleDegraded: true;
|
||||
mutationPending: false;
|
||||
mutationConflict: false;
|
||||
}>
|
||||
| Readonly<{
|
||||
refreshing: false;
|
||||
staleDegraded: false;
|
||||
mutationPending: true;
|
||||
mutationConflict: false;
|
||||
}>
|
||||
| Readonly<{
|
||||
refreshing: false;
|
||||
staleDegraded: false;
|
||||
mutationPending: false;
|
||||
mutationConflict: true;
|
||||
}>;
|
||||
|
||||
export type AsyncSignals = Readonly<{
|
||||
data?: unknown;
|
||||
isInitialLoading?: boolean;
|
||||
failure?: ApiFailure;
|
||||
isFetching?: boolean;
|
||||
isStale?: boolean;
|
||||
isDegraded?: boolean;
|
||||
isMutationPending?: boolean;
|
||||
hasMutationConflict?: boolean;
|
||||
}>;
|
||||
|
||||
export type AsyncState = Readonly<{
|
||||
base: (typeof ASYNC_BASE_STATES)[number];
|
||||
data?: unknown;
|
||||
failure?: ApiFailure;
|
||||
overlay: AsyncOverlay;
|
||||
indicator: (typeof ASYNC_OVERLAYS)[number] | null;
|
||||
}>;
|
||||
|
||||
export function deriveAsyncState(signals: AsyncSignals): AsyncState {
|
||||
const hasData = signals.data !== undefined && signals.data !== null;
|
||||
const empty =
|
||||
hasData &&
|
||||
((Array.isArray(signals.data) && signals.data.length === 0) ||
|
||||
signals.data === "");
|
||||
|
||||
const base =
|
||||
signals.isInitialLoading && !hasData
|
||||
? "initial-loading"
|
||||
: signals.failure && !hasData
|
||||
? "terminal-error"
|
||||
: empty
|
||||
? "empty"
|
||||
: hasData
|
||||
? "success"
|
||||
: "initial-loading";
|
||||
|
||||
const indicator =
|
||||
signals.hasMutationConflict && hasData
|
||||
? "mutation-conflict"
|
||||
: signals.isMutationPending && hasData
|
||||
? "mutation-pending"
|
||||
: signals.isStale && signals.isDegraded && hasData
|
||||
? "stale-degraded"
|
||||
: signals.isFetching && hasData
|
||||
? "refreshing"
|
||||
: null;
|
||||
const overlay = overlayFor(indicator);
|
||||
|
||||
return Object.freeze({
|
||||
base,
|
||||
data: base === "success" || base === "empty" ? signals.data : undefined,
|
||||
failure: base === "terminal-error" ? signals.failure : undefined,
|
||||
overlay,
|
||||
indicator,
|
||||
});
|
||||
}
|
||||
|
||||
export function selectOverlayIndicator(
|
||||
overlay: AsyncOverlay,
|
||||
): AsyncState["indicator"] {
|
||||
if (overlay.mutationConflict) return "mutation-conflict";
|
||||
if (overlay.mutationPending) return "mutation-pending";
|
||||
if (overlay.staleDegraded) return "stale-degraded";
|
||||
if (overlay.refreshing) return "refreshing";
|
||||
return null;
|
||||
}
|
||||
|
||||
function overlayFor(indicator: AsyncState["indicator"]): AsyncOverlay {
|
||||
if (indicator === "refreshing") {
|
||||
return Object.freeze({
|
||||
refreshing: true,
|
||||
staleDegraded: false,
|
||||
mutationPending: false,
|
||||
mutationConflict: false,
|
||||
});
|
||||
}
|
||||
if (indicator === "stale-degraded") {
|
||||
return Object.freeze({
|
||||
refreshing: false,
|
||||
staleDegraded: true,
|
||||
mutationPending: false,
|
||||
mutationConflict: false,
|
||||
});
|
||||
}
|
||||
if (indicator === "mutation-pending") {
|
||||
return Object.freeze({
|
||||
refreshing: false,
|
||||
staleDegraded: false,
|
||||
mutationPending: true,
|
||||
mutationConflict: false,
|
||||
});
|
||||
}
|
||||
if (indicator === "mutation-conflict") {
|
||||
return Object.freeze({
|
||||
refreshing: false,
|
||||
staleDegraded: false,
|
||||
mutationPending: false,
|
||||
mutationConflict: true,
|
||||
});
|
||||
}
|
||||
return Object.freeze({
|
||||
refreshing: false,
|
||||
staleDegraded: false,
|
||||
mutationPending: false,
|
||||
mutationConflict: false,
|
||||
});
|
||||
}
|
||||
@@ -3,6 +3,7 @@ import {
|
||||
createExternalAuthSessionAdapter,
|
||||
createUnavailableSessionAdapter,
|
||||
} from "../adapters/auth/external-session-adapter.js";
|
||||
import { createHttpClient } from "../adapters/http/client.js";
|
||||
import {
|
||||
createQueryClient,
|
||||
} from "../adapters/query-cache/tanstack-query-cache.js";
|
||||
@@ -40,6 +41,30 @@ function storageOrUndefined(value) {
|
||||
: undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Runtime-aware transport factory. Feature gateway composition calls this
|
||||
* factory when a registered API capability is installed.
|
||||
*
|
||||
* @param {{
|
||||
* runtime: Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>,
|
||||
* authSession: import("../application/ports/auth-session-port.js").AuthSessionPort,
|
||||
* fetcher?: typeof fetch,
|
||||
* clock?: import("../application/ports/clock-port.js").ClockPort,
|
||||
* scheduler?: Parameters<typeof createHttpClient>[0]["scheduler"]
|
||||
* }} context
|
||||
*/
|
||||
export function createRuntimeHttpClient(context) {
|
||||
return createHttpClient({
|
||||
baseUrl: context.runtime.config.API_BASE_URL,
|
||||
timeoutMs: context.runtime.config.REQUEST_TIMEOUT_MS,
|
||||
maxRetryAttempts: context.runtime.config.MAX_RETRY_ATTEMPTS,
|
||||
authSession: context.authSession,
|
||||
fetcher: context.fetcher,
|
||||
clock: context.clock,
|
||||
scheduler: context.scheduler,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{
|
||||
* runtime: Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>,
|
||||
|
||||
@@ -4,8 +4,10 @@
|
||||
* path: string,
|
||||
* operationId: string,
|
||||
* auth: "none" | "external-session",
|
||||
* timeoutMs: number,
|
||||
* timeoutMs: number | null,
|
||||
* idempotency: "safe" | "keyed" | "none",
|
||||
* retry: "runtime" | "never",
|
||||
* requestSource: "search" | "body" | "none",
|
||||
* requestSchema: string,
|
||||
* responseSchema: string,
|
||||
* owner: string
|
||||
@@ -21,8 +23,10 @@ export const API_OPERATIONS = Object.freeze({
|
||||
path: "/api/sample/resources",
|
||||
operationId: "LIST_SAMPLE_RESOURCES",
|
||||
auth: "external-session",
|
||||
timeoutMs: 10_000,
|
||||
timeoutMs: null,
|
||||
idempotency: "safe",
|
||||
retry: "runtime",
|
||||
requestSource: "search",
|
||||
requestSchema: "SampleResourceListQuery",
|
||||
responseSchema: "SampleResourceListPayload",
|
||||
owner: "feature-sample-feature-slice-contract-fixture",
|
||||
@@ -32,8 +36,10 @@ export const API_OPERATIONS = Object.freeze({
|
||||
path: "/api/sample/resources",
|
||||
operationId: "CREATE_SAMPLE_RESOURCE",
|
||||
auth: "external-session",
|
||||
timeoutMs: 10_000,
|
||||
timeoutMs: null,
|
||||
idempotency: "keyed",
|
||||
retry: "runtime",
|
||||
requestSource: "body",
|
||||
requestSchema: "CreateSampleResourceCommand",
|
||||
responseSchema: "SampleResourcePayload",
|
||||
owner: "feature-sample-feature-slice-contract-fixture",
|
||||
|
||||
@@ -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",
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
export {
|
||||
useApplicationMutation,
|
||||
useApplicationQuery,
|
||||
type ApplicationResult,
|
||||
} from "./application-query.js";
|
||||
@@ -65,7 +65,7 @@ export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
|
||||
data-message-key={userMessageKey}
|
||||
>
|
||||
<h2 id={messageId}>{errorMessage(userMessageKey)}</h2>
|
||||
{action !== "none" && (
|
||||
{action !== "none" && onAction && (
|
||||
<Button onClick={onAction}>{actionLabels[action]}</Button>
|
||||
)}
|
||||
</section>
|
||||
@@ -76,10 +76,18 @@ export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
|
||||
* @param {{
|
||||
* state: ReturnType<typeof import("../../application/view-models/async-state.js").deriveAsyncState>,
|
||||
* children?: React.ReactNode,
|
||||
* onAction?: () => void
|
||||
* onAction?: () => void,
|
||||
* onRetry?: () => void,
|
||||
* onResolveConflict?: () => void
|
||||
* }} props
|
||||
*/
|
||||
export function AsyncSurface({ state, children, onAction }) {
|
||||
export function AsyncSurface({
|
||||
state,
|
||||
children,
|
||||
onAction,
|
||||
onRetry,
|
||||
onResolveConflict,
|
||||
}) {
|
||||
if (state.base === "initial-loading") return <LoadingSurface />;
|
||||
if (state.base === "empty") return <EmptySurface />;
|
||||
if (state.base === "terminal-error" && state.failure) {
|
||||
@@ -87,18 +95,24 @@ export function AsyncSurface({ state, children, onAction }) {
|
||||
<TerminalErrorSurface
|
||||
userMessageKey={state.failure.userMessageKey}
|
||||
action={state.failure.action}
|
||||
onAction={onAction}
|
||||
onAction={onRetry ?? onAction}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<section aria-busy={state.overlay.refreshing || state.overlay.mutationPending}>
|
||||
{state.indicator && (
|
||||
<p role="status" aria-live="polite">
|
||||
{state.indicator}
|
||||
</p>
|
||||
)}
|
||||
{state.indicator ? (
|
||||
<div role="status" aria-live="polite">
|
||||
<span>{state.indicator}</span>
|
||||
{state.indicator === "stale-degraded" && onRetry ? (
|
||||
<Button onClick={onRetry}>다시 시도</Button>
|
||||
) : null}
|
||||
{state.indicator === "mutation-conflict" && onResolveConflict ? (
|
||||
<Button onClick={onResolveConflict}>충돌 해결</Button>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
{children}
|
||||
</section>
|
||||
);
|
||||
|
||||
Reference in New Issue
Block a user