feat: add removable reference feature vertical slice
This commit is contained in:
donghyeon-ka
@@ -0,0 +1,39 @@
|
||||
# Reference feature ownership and removal
|
||||
|
||||
이 모듈은 제품 도메인이 아니라 새 기능의 수직 경계를 검증하는 제거 가능한
|
||||
reference implementation이다.
|
||||
|
||||
## 소유 경계
|
||||
|
||||
- `domain`: 외부 DTO와 React를 모르는 불변 model
|
||||
- `application`: UI가 호출하는 list/create input과 gateway 계약
|
||||
- `adapters`: HTTP executor를 gateway로 투영하는 outbound adapter
|
||||
- `contracts`: route/API/query contribution, Zod DTO와 request schema, mapper
|
||||
- `presentation`: route input을 query/mutation controller로 연결하는 inbound
|
||||
adapter와 page
|
||||
|
||||
generic application은 `features.get(featureId)` catalog만 제공한다. feature hook이
|
||||
자신의 input shape를 확인하며 page는 HTTP client, storage, auth owner, output
|
||||
port나 TanStack API를 직접 import하지 않는다.
|
||||
|
||||
## 설치 지점
|
||||
|
||||
- 직렬화 계약: `src/features/installed-feature-contracts.js`
|
||||
- component/codec: `src/features/installed-feature-runtimes.tsx`
|
||||
- bootstrap input 조립: `src/features/installed-feature-adapters.ts`
|
||||
|
||||
새 기능도 이 세 지점에 contribution을 합성하되 feature ID를 generic application,
|
||||
router나 HTTP client에 하드코딩하지 않는다.
|
||||
|
||||
## 검증과 제거
|
||||
|
||||
```sh
|
||||
corepack pnpm test:reference-feature
|
||||
corepack pnpm test:sample-removal
|
||||
```
|
||||
|
||||
첫 명령은 URL filter와 query key/HTTP request의 동일성, schema/mapper, 모든
|
||||
query/mutation 상태와 production composition을 검증한다. 두 번째 명령은 임시
|
||||
복제본에서 이 source/test 디렉터리를 제거하고 installed catalog를 빈 목록으로
|
||||
재생성한 뒤 typecheck, architecture, registry, unit/integration, home smoke,
|
||||
production build와 fixture ID 잔여 0개를 검사한다.
|
||||
@@ -0,0 +1,43 @@
|
||||
import { createReferenceFeatureInput } from "../application/reference-feature-api.js";
|
||||
import {
|
||||
REFERENCE_FEATURE_CONTRACT,
|
||||
REFERENCE_FEATURE_ID,
|
||||
} from "../contracts/reference-feature-contract.js";
|
||||
import { mapReferenceOperation } from "../contracts/reference-mapper.js";
|
||||
import {
|
||||
validateReferencePayload,
|
||||
validateReferenceRequest,
|
||||
} from "../contracts/reference-schemas.js";
|
||||
import { createReferenceHttpGateway } from "./reference-http-gateway.js";
|
||||
|
||||
type HttpContract = Readonly<{
|
||||
getOperation(operationId: string): unknown;
|
||||
validatePayload: typeof validateReferencePayload;
|
||||
validateRequest: typeof validateReferenceRequest;
|
||||
mapPayload: typeof mapReferenceOperation;
|
||||
}>;
|
||||
|
||||
type HttpExecutor = Parameters<typeof createReferenceHttpGateway>[0];
|
||||
|
||||
export function createReferenceFeatureInstalledInput(context: Readonly<{
|
||||
createHttpClient(contract: HttpContract): HttpExecutor;
|
||||
}>) {
|
||||
const operations =
|
||||
REFERENCE_FEATURE_CONTRACT.apiOperations as Readonly<Record<string, unknown>>;
|
||||
const http = context.createHttpClient({
|
||||
getOperation(operationId) {
|
||||
const operation = operations[operationId];
|
||||
if (!operation) {
|
||||
throw new Error(`Unknown reference operation: ${operationId}`);
|
||||
}
|
||||
return operation;
|
||||
},
|
||||
validatePayload: validateReferencePayload,
|
||||
validateRequest: validateReferenceRequest,
|
||||
mapPayload: mapReferenceOperation,
|
||||
});
|
||||
return Object.freeze({
|
||||
featureId: REFERENCE_FEATURE_ID,
|
||||
input: createReferenceFeatureInput(createReferenceHttpGateway(http)),
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
import type { ApiFailure } from "../../../contracts/errors.js";
|
||||
import type {
|
||||
ReferenceGateway,
|
||||
ReferenceListFilters,
|
||||
} from "../application/reference-feature-api.js";
|
||||
import type { ReferenceResource } from "../domain/reference-resource.js";
|
||||
|
||||
type HttpResult =
|
||||
| Readonly<{ ok: true; value: unknown }>
|
||||
| Readonly<{ ok: false; error: ApiFailure }>;
|
||||
|
||||
type HttpExecutor = Readonly<{
|
||||
execute(
|
||||
request: Readonly<{
|
||||
operationId: string;
|
||||
routeId: string;
|
||||
searchParams?: unknown;
|
||||
body?: unknown;
|
||||
signal?: AbortSignal;
|
||||
}>,
|
||||
): Promise<HttpResult>;
|
||||
}>;
|
||||
|
||||
export function createReferenceHttpGateway(
|
||||
http: HttpExecutor,
|
||||
): ReferenceGateway {
|
||||
return Object.freeze({
|
||||
async list(
|
||||
filters: ReferenceListFilters,
|
||||
context?: Readonly<{ signal?: AbortSignal }>,
|
||||
) {
|
||||
const result = await http.execute({
|
||||
operationId: "LIST_REFERENCE_RESOURCES",
|
||||
routeId: "REFERENCE_RESOURCE_LIST",
|
||||
searchParams: filters,
|
||||
signal: context?.signal,
|
||||
});
|
||||
return result.ok
|
||||
? {
|
||||
ok: true as const,
|
||||
value: result.value as readonly ReferenceResource[],
|
||||
}
|
||||
: result;
|
||||
},
|
||||
async create(command: Readonly<{ name: string }>) {
|
||||
const result = await http.execute({
|
||||
operationId: "CREATE_REFERENCE_RESOURCE",
|
||||
routeId: "REFERENCE_RESOURCE_LIST",
|
||||
body: command,
|
||||
});
|
||||
return result.ok
|
||||
? { ok: true as const, value: result.value as ReferenceResource }
|
||||
: result;
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,58 @@
|
||||
import type { ApiFailure } from "../../../contracts/errors.js";
|
||||
import {
|
||||
toReferenceView,
|
||||
type ReferenceResourceView,
|
||||
} from "../contracts/reference-mapper.js";
|
||||
import type { ReferenceResource } from "../domain/reference-resource.js";
|
||||
|
||||
export type ReferenceListFilters = Readonly<{
|
||||
cursor?: string;
|
||||
limit: number;
|
||||
tags?: readonly string[];
|
||||
}>;
|
||||
|
||||
export type ReferenceResult<Value> =
|
||||
| Readonly<{ ok: true; value: Value }>
|
||||
| Readonly<{ ok: false; error: ApiFailure }>;
|
||||
|
||||
export type ReferenceFeatureInput = Readonly<{
|
||||
listResources(
|
||||
filters: ReferenceListFilters,
|
||||
context?: Readonly<{ signal?: AbortSignal }>,
|
||||
): Promise<ReferenceResult<readonly ReferenceResourceView[]>>;
|
||||
createResource(
|
||||
command: Readonly<{ name: string }>,
|
||||
): Promise<ReferenceResult<ReferenceResourceView>>;
|
||||
}>;
|
||||
|
||||
export type ReferenceGateway = Readonly<{
|
||||
list(
|
||||
filters: ReferenceListFilters,
|
||||
context?: Readonly<{ signal?: AbortSignal }>,
|
||||
): Promise<ReferenceResult<readonly ReferenceResource[]>>;
|
||||
create(
|
||||
command: Readonly<{ name: string }>,
|
||||
): Promise<ReferenceResult<ReferenceResource>>;
|
||||
}>;
|
||||
|
||||
export function createReferenceFeatureInput(
|
||||
gateway: ReferenceGateway,
|
||||
): ReferenceFeatureInput {
|
||||
return Object.freeze({
|
||||
async listResources(filters, context) {
|
||||
const result = await gateway.list(filters, context);
|
||||
return result.ok
|
||||
? {
|
||||
ok: true as const,
|
||||
value: result.value.map((resource) => toReferenceView(resource)),
|
||||
}
|
||||
: result;
|
||||
},
|
||||
async createResource(command) {
|
||||
const result = await gateway.create(command);
|
||||
return result.ok
|
||||
? { ok: true as const, value: toReferenceView(result.value) }
|
||||
: result;
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,75 @@
|
||||
import { canonicalize } from "../../../contracts/query-keys.js";
|
||||
|
||||
export const REFERENCE_FEATURE_ID = "reference-feature";
|
||||
const REFERENCE_NAMESPACE = Object.freeze(["reference-resource", 1]);
|
||||
|
||||
export const referenceQueryKeys = Object.freeze({
|
||||
all: () => REFERENCE_NAMESPACE,
|
||||
list: (filters = {}) =>
|
||||
Object.freeze([...REFERENCE_NAMESPACE, "list", canonicalize(filters)]),
|
||||
});
|
||||
|
||||
export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
|
||||
featureId: REFERENCE_FEATURE_ID,
|
||||
routes: Object.freeze({
|
||||
REFERENCE_RESOURCE_LIST: Object.freeze({
|
||||
routeId: "REFERENCE_RESOURCE_LIST",
|
||||
path: "/examples/reference-resources",
|
||||
paramsSchema: null,
|
||||
searchSchema: "ReferenceResourceListQuery",
|
||||
access: "integration-defined",
|
||||
loadingSurface: "reference-resource-list",
|
||||
errorSurface: "feature-boundary",
|
||||
chunkId: "route-reference-resources",
|
||||
title: "Reference feature",
|
||||
navigationLabel: "Reference feature",
|
||||
navigationOrder: 50,
|
||||
}),
|
||||
}),
|
||||
routeRuntimeContracts: Object.freeze({
|
||||
REFERENCE_RESOURCE_LIST: Object.freeze({
|
||||
routeId: "REFERENCE_RESOURCE_LIST",
|
||||
moduleId: "reference-resource-page",
|
||||
paramsCodec: "none",
|
||||
searchCodec: "ReferenceResourceListQuery",
|
||||
}),
|
||||
}),
|
||||
apiOperations: Object.freeze({
|
||||
LIST_REFERENCE_RESOURCES: Object.freeze({
|
||||
method: "GET",
|
||||
path: "/api/reference-resources",
|
||||
operationId: "LIST_REFERENCE_RESOURCES",
|
||||
auth: "external-session",
|
||||
timeoutMs: null,
|
||||
idempotency: "safe",
|
||||
retry: "runtime",
|
||||
requestSource: "search",
|
||||
requestSchema: "ReferenceResourceListQuery",
|
||||
responseSchema: "ReferenceResourceListPayload",
|
||||
owner: "feature-frontend-reference-feature-vertical-slice",
|
||||
}),
|
||||
CREATE_REFERENCE_RESOURCE: Object.freeze({
|
||||
method: "POST",
|
||||
path: "/api/reference-resources",
|
||||
operationId: "CREATE_REFERENCE_RESOURCE",
|
||||
auth: "external-session",
|
||||
timeoutMs: null,
|
||||
idempotency: "keyed",
|
||||
retry: "runtime",
|
||||
requestSource: "body",
|
||||
requestSchema: "CreateReferenceResourceCommand",
|
||||
responseSchema: "ReferenceResourcePayload",
|
||||
owner: "feature-frontend-reference-feature-vertical-slice",
|
||||
}),
|
||||
}),
|
||||
queryRegistry: Object.freeze({
|
||||
REFERENCE_RESOURCE: Object.freeze({
|
||||
namespace: REFERENCE_NAMESPACE,
|
||||
serialization: "canonical-object-order",
|
||||
identity: "no-pii-token-or-raw-url",
|
||||
invalidation: "reference resource namespace after successful mutation",
|
||||
version: 1,
|
||||
persistence: "disabled",
|
||||
}),
|
||||
}),
|
||||
});
|
||||
@@ -0,0 +1,54 @@
|
||||
import {
|
||||
createReferenceResource,
|
||||
type ReferenceResource,
|
||||
} from "../domain/reference-resource.js";
|
||||
|
||||
export type ReferenceResourceView = Readonly<{
|
||||
resourceId: string;
|
||||
title: string;
|
||||
createdAtLabel: string | null;
|
||||
optimistic?: boolean;
|
||||
}>;
|
||||
|
||||
function mapReferenceDto(value: unknown): ReferenceResource {
|
||||
if (!value || typeof value !== "object") {
|
||||
throw new TypeError("Validated reference DTO is required");
|
||||
}
|
||||
const dto = value as Record<string, unknown>;
|
||||
if (typeof dto.id !== "string" || typeof dto.name !== "string") {
|
||||
throw new TypeError("Validated reference DTO invariants were breached");
|
||||
}
|
||||
return createReferenceResource({
|
||||
id: dto.id,
|
||||
displayName: dto.name,
|
||||
createdAt: typeof dto.createdAt === "string" ? dto.createdAt : null,
|
||||
});
|
||||
}
|
||||
|
||||
export function mapReferenceOperation(
|
||||
operationId: string,
|
||||
payload: unknown,
|
||||
): ReferenceResource | readonly ReferenceResource[] {
|
||||
if (operationId === "LIST_REFERENCE_RESOURCES") {
|
||||
if (!Array.isArray(payload)) throw new TypeError("Expected a reference list");
|
||||
return payload.map(mapReferenceDto);
|
||||
}
|
||||
if (operationId === "CREATE_REFERENCE_RESOURCE") {
|
||||
return mapReferenceDto(payload);
|
||||
}
|
||||
throw new TypeError(`No reference mapper registered for ${operationId}`);
|
||||
}
|
||||
|
||||
export function toReferenceView(
|
||||
resource: ReferenceResource,
|
||||
formatDate: (value: Date) => string = (value) =>
|
||||
new Intl.DateTimeFormat("ko-KR").format(value),
|
||||
): ReferenceResourceView {
|
||||
return Object.freeze({
|
||||
resourceId: resource.id,
|
||||
title: resource.displayName,
|
||||
createdAtLabel: resource.createdAt
|
||||
? formatDate(new Date(resource.createdAt))
|
||||
: null,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
import { z } from "zod";
|
||||
|
||||
export const referenceResourceListQuerySchema = z
|
||||
.object({
|
||||
cursor: z.string().min(1).optional(),
|
||||
limit: z.coerce.number().int().min(1).max(100).default(20),
|
||||
tags: z
|
||||
.preprocess(
|
||||
(value) =>
|
||||
value === undefined
|
||||
? undefined
|
||||
: Array.isArray(value)
|
||||
? value
|
||||
: [value],
|
||||
z.array(z.string().trim().min(1)),
|
||||
)
|
||||
.optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const referenceResourceDtoSchema = z
|
||||
.object({
|
||||
id: z.string().min(1),
|
||||
name: z.string().min(1),
|
||||
createdAt: z.string().datetime().optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const payloadSchemas = {
|
||||
ReferenceResourceListPayload: z.array(referenceResourceDtoSchema),
|
||||
ReferenceResourcePayload: referenceResourceDtoSchema,
|
||||
} satisfies Record<string, z.ZodType>;
|
||||
|
||||
const requestSchemas = {
|
||||
ReferenceResourceListQuery: referenceResourceListQuerySchema,
|
||||
CreateReferenceResourceCommand: z
|
||||
.object({
|
||||
name: z.string().trim().min(1).max(120),
|
||||
})
|
||||
.strict(),
|
||||
} satisfies Record<string, z.ZodType>;
|
||||
|
||||
function project(result: z.ZodSafeParseResult<unknown>) {
|
||||
return result.success
|
||||
? ({ success: true as const, data: structuredClone(result.data) })
|
||||
: ({
|
||||
success: false as const,
|
||||
issues: result.error.issues.map((issue) => ({
|
||||
path: issue.path.join("."),
|
||||
code: issue.code,
|
||||
})),
|
||||
});
|
||||
}
|
||||
|
||||
export function validateReferencePayload(schemaId: string, value: unknown) {
|
||||
const schema = payloadSchemas[schemaId as keyof typeof payloadSchemas];
|
||||
return schema
|
||||
? project(schema.safeParse(value))
|
||||
: { success: false as const, issues: [{ path: "", code: "SCHEMA_NOT_REGISTERED" }] };
|
||||
}
|
||||
|
||||
export function validateReferenceRequest(schemaId: string, value: unknown) {
|
||||
const schema = requestSchemas[schemaId as keyof typeof requestSchemas];
|
||||
return schema
|
||||
? project(schema.safeParse(value))
|
||||
: { success: false as const, issues: [{ path: "", code: "SCHEMA_NOT_REGISTERED" }] };
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
export type ReferenceResource = Readonly<{
|
||||
id: string;
|
||||
displayName: string;
|
||||
createdAt: string | null;
|
||||
}>;
|
||||
|
||||
export function createReferenceResource(
|
||||
values: ReferenceResource,
|
||||
): ReferenceResource {
|
||||
if (!values.id || !values.displayName) {
|
||||
throw new TypeError("Reference resource invariants require id and displayName");
|
||||
}
|
||||
return Object.freeze({ ...values });
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
import { lazy } from "react";
|
||||
|
||||
import { referenceResourceListQuerySchema } from "../contracts/reference-schemas.js";
|
||||
|
||||
export const REFERENCE_FEATURE_ROUTE_CODECS = {
|
||||
ReferenceResourceListQuery: referenceResourceListQuerySchema,
|
||||
} as const;
|
||||
|
||||
export const REFERENCE_FEATURE_ROUTE_RUNTIME = {
|
||||
REFERENCE_RESOURCE_LIST: Object.freeze({
|
||||
moduleId: "reference-resource-page",
|
||||
Component: lazy(() => import("./reference-resource-page.js")),
|
||||
}),
|
||||
} as const;
|
||||
@@ -0,0 +1,60 @@
|
||||
import { useState, type FormEvent } from "react";
|
||||
|
||||
import { AsyncSurface } from "../../../presentation/components/async-surface.jsx";
|
||||
import { Button } from "../../../presentation/components/ui/button.jsx";
|
||||
import { PageHeader } from "../../../presentation/components/page-header.jsx";
|
||||
import { useReferenceFeature } from "./use-reference-feature.js";
|
||||
|
||||
export default function ReferenceResourcePage() {
|
||||
const { filters, query, mutation } = useReferenceFeature();
|
||||
const [name, setName] = useState("");
|
||||
|
||||
async function submit(event: FormEvent<HTMLFormElement>) {
|
||||
event.preventDefault();
|
||||
const result = await mutation.submit({ name });
|
||||
if (result.ok) setName("");
|
||||
}
|
||||
|
||||
return (
|
||||
<section className="ui-page">
|
||||
<PageHeader
|
||||
eyebrow="제거 가능한 수직 슬라이스"
|
||||
title="Reference feature"
|
||||
description="URL codec, application input, HTTP/schema/mapper와 query/mutation 상태를 한 경로로 검증합니다."
|
||||
/>
|
||||
<p data-testid="reference-filter">
|
||||
limit {filters.limit}
|
||||
{filters.tags?.length ? ` · tags ${filters.tags.join(", ")}` : ""}
|
||||
</p>
|
||||
<AsyncSurface state={query.state} onRetry={query.retry}>
|
||||
<ul aria-label="Reference resources">
|
||||
{(query.data ?? []).map((resource) => (
|
||||
<li
|
||||
key={resource.resourceId}
|
||||
data-optimistic={resource.optimistic || undefined}
|
||||
>
|
||||
{resource.title}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
</AsyncSurface>
|
||||
<AsyncSurface
|
||||
state={mutation.state}
|
||||
onResolveConflict={mutation.resolveConflict}
|
||||
>
|
||||
<form onSubmit={(event) => void submit(event)}>
|
||||
<label htmlFor="reference-resource-name">새 항목 이름</label>
|
||||
<input
|
||||
id="reference-resource-name"
|
||||
value={name}
|
||||
onChange={(event) => setName(event.currentTarget.value)}
|
||||
required
|
||||
/>
|
||||
<Button type="submit" disabled={mutation.state.overlay.mutationPending}>
|
||||
추가
|
||||
</Button>
|
||||
</form>
|
||||
</AsyncSurface>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
import { useApplication } from "../../../presentation/providers/application-provider.js";
|
||||
import {
|
||||
useApplicationMutation,
|
||||
useApplicationQuery,
|
||||
} from "../../../presentation/adapters/query/application-query.js";
|
||||
import { useRouteInput } from "../../../presentation/routes/app-router.js";
|
||||
import type { ReferenceResourceView } from "../contracts/reference-mapper.js";
|
||||
import {
|
||||
REFERENCE_FEATURE_ID,
|
||||
referenceQueryKeys,
|
||||
} from "../contracts/reference-feature-contract.js";
|
||||
import type {
|
||||
ReferenceFeatureInput,
|
||||
ReferenceListFilters,
|
||||
} from "../application/reference-feature-api.js";
|
||||
|
||||
function useReferenceFeatureInput(): ReferenceFeatureInput {
|
||||
const candidate = useApplication().features.get(REFERENCE_FEATURE_ID);
|
||||
if (
|
||||
!candidate ||
|
||||
typeof candidate !== "object" ||
|
||||
typeof (candidate as ReferenceFeatureInput).listResources !== "function" ||
|
||||
typeof (candidate as ReferenceFeatureInput).createResource !== "function"
|
||||
) {
|
||||
throw new Error("Reference feature application input is invalid");
|
||||
}
|
||||
return candidate as ReferenceFeatureInput;
|
||||
}
|
||||
|
||||
export function useReferenceFeature() {
|
||||
const input = useReferenceFeatureInput();
|
||||
const routeInput = useRouteInput();
|
||||
const filters = routeInput.search as ReferenceListFilters;
|
||||
const queryKey = referenceQueryKeys.list(filters);
|
||||
const query = useApplicationQuery({
|
||||
queryKey,
|
||||
execute: ({ signal }) => input.listResources(filters, { signal }),
|
||||
});
|
||||
const mutation = useApplicationMutation({
|
||||
execute: input.createResource,
|
||||
invalidate: [referenceQueryKeys.all()],
|
||||
currentData: true,
|
||||
optimistic: {
|
||||
queryKey,
|
||||
update(previous, command: Readonly<{ name: string }>) {
|
||||
const current = Array.isArray(previous)
|
||||
? (previous as readonly ReferenceResourceView[])
|
||||
: [];
|
||||
return [
|
||||
...current,
|
||||
{
|
||||
resourceId: `optimistic:${command.name}`,
|
||||
title: command.name,
|
||||
createdAtLabel: null,
|
||||
optimistic: true,
|
||||
},
|
||||
];
|
||||
},
|
||||
},
|
||||
});
|
||||
return Object.freeze({ filters, query, mutation });
|
||||
}
|
||||
Reference in New Issue
Block a user