Files
clean-architecture-frontend…/src/features/feature-module.ts
T
DongHyeonka bf9df9a5c2 docs(features): 기능 실행부 설명 네 곳을 V2 삭제 뒤 모양으로 고친다 (1103/09-10)
문제
FeatureRuntime은 featureId·schemas·adapters·contractContributions인데, 네 곳이
지워진 V2 모양을 적었다. feature-module.ts 머리 주석("API contracts with their
runtime schemas and mappers"), installed-feature-contracts.ts("The V2 API
registries"), frontend-application-foundation.md("composes the V2 API
registries"), starter-experience.md 기능 추가 2단계("the API contract
(operations, schema metadata, runtime schemas, mappers)"). 기능 작성자가 없는
칸을 찾게 된다. 07-05(starter-experience 같은 문장)를 함께 닫는다.

고른 방법
네 문장을 지금 모양으로 고친다: schemas는 FE-REG-SCHEMA 행, 어댑터 기여는
application input, 계약 기여는 HTTP operation이고 FE-REG-API 행은 거기서
투영한다(installed-feature-runtime-registries.ts와 같다).

위험·한계
verify:documentation은 문장 내용을 보지 않으므로 다시 낡아도 게이트가 모른다.

검증
- git grep "V2 API registr|runtime schemas, mappers|runtime schemas and
  mappers" -- src docs/architecture → 0건.
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-10
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-05
2026-11-04 20:19:59 +09:00

143 lines
4.9 KiB
TypeScript

export type FeatureContractIdentity = Readonly<{ featureId: string }>;
type EmptyRecord = Readonly<Record<never, never>>;
/**
* 15-01. A feature has two halves. The declaration (`FeatureModule`) is what
* the shell needs before any of the feature's routes is entered: its route
* table, its messages, its cache invalidation identities and the external
* contract packages the release manifest is checked against at boot. It is
* imported statically and lands in the initial chunk, so it stays data.
*
* Everything executable (the FE-REG-SCHEMA schema definitions, the adapter
* contributions that build the application input, and the HTTP contract
* contributions whose descriptors FE-REG-API rows are projected from) is the
* runtime half (`FeatureRuntime`). `loadRuntime` imports it dynamically when
* one of the feature's routes is entered. Before 15-01 both halves loaded at
* boot and each feature added about 3.9 KB gzip to the initial chunk.
*/
/**
* Zero-feature products are a supported topology. The fallback contract keeps
* every composer's property access valid without pretending that any feature
* route, invalidation edge or contract package exists.
*/
export type EmptyFeatureContract = FeatureContractIdentity &
Readonly<{
routes: EmptyRecord;
routeRuntimeContracts: EmptyRecord;
invalidation: Readonly<{
topics: readonly [];
namespaces: readonly [];
edges: readonly [];
}>;
topicVersions: readonly [];
contractPackages: readonly [];
}>;
export type FeatureMessageCatalogs = Readonly<
Record<string, Readonly<Record<string, string>>>
>;
type EmptyFeatureMessageCatalogs = Readonly<
Record<string, Readonly<Record<never, never>>>
>;
/**
* The executable half. `featureId` must equal the declaring module's id; the
* loader checks it, and checks that every adapter and contract contribution in
* it belongs to that feature.
*/
export type FeatureRuntime<
Schemas = EmptyRecord,
Adapter = never,
ContractContribution = never,
> = Readonly<{
featureId: string;
/**
* FE-REG-SCHEMA rows (`SchemaDefinition`) for the feature's route and API
* schemas. The HTTP operations themselves are the V3 descriptors in
* `contractContributions`; FE-REG-API rows are projected from them.
*/
schemas: Schemas;
adapters: readonly Adapter[];
contractContributions: readonly ContractContribution[];
}>;
export type AnyFeatureRuntime = FeatureRuntime<unknown, unknown, unknown>;
/**
* The default parameters deliberately describe the empty-product fallback.
* Concrete generated modules retain their literal types; only an empty
* generated tuple resolves to this default shape.
*/
export type FeatureModule<
Contract extends FeatureContractIdentity = EmptyFeatureContract,
Routes extends Readonly<Record<string, unknown>> = EmptyRecord,
Messages extends FeatureMessageCatalogs = EmptyFeatureMessageCatalogs,
Runtime extends AnyFeatureRuntime = FeatureRuntime,
> = Readonly<{
id: string;
contracts: Contract;
routes: Routes;
messages: Messages;
/**
* Must dynamically import the feature's `feature-runtime.ts`: a static
* import here would put the runtime half back into the initial chunk
* (tests/unit/feature-shape-growth.test.ts measures it).
*/
loadRuntime(): Promise<Runtime>;
}>;
/** Structural supertype used when accepting any concrete feature descriptor. */
export type AnyFeatureModule = FeatureModule<
FeatureContractIdentity,
Readonly<Record<string, unknown>>,
FeatureMessageCatalogs,
AnyFeatureRuntime
>;
/** The runtime half a module's `loadRuntime` resolves to. */
export type FeatureModuleRuntime<Module extends AnyFeatureModule> = Awaited<
ReturnType<Module["loadRuntime"]>
>;
export function defineFeatureModule<const Module extends AnyFeatureModule>(
module: Module,
): Readonly<Module> {
if (module.id !== module.contracts.featureId) {
throw new TypeError(
`Feature module id ${module.id} does not match contract featureId ${module.contracts.featureId}`,
);
}
return Object.freeze({ ...module }) as unknown as Readonly<Module>;
}
export function defineFeatureRuntime<const Runtime extends AnyFeatureRuntime>(
runtime: Runtime,
): Readonly<Runtime> {
return Object.freeze({
...runtime,
adapters: Object.freeze([...runtime.adapters]),
contractContributions: Object.freeze([...runtime.contractContributions]),
}) as unknown as Readonly<Runtime>;
}
/**
* Loads a module's runtime half and refuses one that belongs to another
* feature. Composers call this instead of `module.loadRuntime()` directly.
*/
export async function loadFeatureRuntime<const Module extends AnyFeatureModule>(
module: Module,
): Promise<FeatureModuleRuntime<Module>> {
const runtime = (await module.loadRuntime()) as FeatureModuleRuntime<Module>;
const owner = (runtime as AnyFeatureRuntime).featureId;
if (owner !== module.id) {
throw new TypeError(
`Feature module ${module.id} loaded the runtime of ${String(owner)}`,
);
}
return runtime;
}