export type FeatureContractIdentity = Readonly<{ featureId: string }>; type EmptyRecord = Readonly>; /** * 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 (API contracts with their runtime schemas and mappers, * the application input factory, the HTTP contract contributions) 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>> >; type EmptyFeatureMessageCatalogs = Readonly< Record>> >; /** * 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; /** * 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> = 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; }>; /** Structural supertype used when accepting any concrete feature descriptor. */ export type AnyFeatureModule = FeatureModule< FeatureContractIdentity, Readonly>, FeatureMessageCatalogs, AnyFeatureRuntime >; /** The runtime half a module's `loadRuntime` resolves to. */ export type FeatureModuleRuntime = Awaited< ReturnType >; export function defineFeatureModule( module: Module, ): Readonly { 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; } export function defineFeatureRuntime( runtime: Runtime, ): Readonly { return Object.freeze({ ...runtime, adapters: Object.freeze([...runtime.adapters]), contractContributions: Object.freeze([...runtime.contractContributions]), }) as unknown as Readonly; } /** * 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( module: Module, ): Promise> { const runtime = (await module.loadRuntime()) as FeatureModuleRuntime; 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; }