@classytic/arc 2.28.0 → 2.31.0

package/dist/index-CFThn1K9.d.mts

@@ -0,0 +1,224 @@
+
+import { a as ModuleContribution, h as HealthCheck, n as ArcModuleInput, r as ArcModuleRegistry, t as ArcModule, u as ScheduleDefinition } from "./types-CBgvkp8O.mjs";
+import { FastifyInstance } from "fastify";
+//#region src/factory/module/contributions.d.ts
+/**
+ * Collect every module's `healthChecks` in the caller's order. Fails at boot
+ * on a duplicate check `name` across modules, naming BOTH owning modules.
+ * The host's app-level checks are appended AFTER this (modules-first,
+ * host-last) by the caller.
+ */
+declare function collectModuleHealthChecks(modules: readonly ArcModule[]): HealthCheck[];
+/**
+ * Collect every module's `workflows`. Resolves factory contributions (so a
+ * factory can close over a container the caller has already decorated on
+ * `fastify`) and flattens to a single opaque array. Arc core deliberately
+ * does NOT validate or interpret the values — the streamline integration
+ * owns name/shape checks and registration. Called by the integration at init
+ * time, not by arc's boot pipeline (workflows depend on the integration's
+ * container).
+ */
+declare function collectModuleWorkflows(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<unknown[]>;
+/**
+ * Collect every module's `scheduledJobs`. Resolves factory contributions
+ * (after bootstraps) and fails at boot on a duplicate job `name` across
+ * modules. The caller passes the returned definitions to the canonical
+ * schedules plugin; factories must therefore be resolved only once.
+ */
+declare function collectModuleScheduledJobs(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<ScheduleDefinition[]>;
+//#endregion
+//#region src/factory/module/lifecycle.d.ts
+/**
+ * Subscribe every module's `eventHandlers` in dependency order (pass the
+ * `orderModules`-sorted list). Returns the ordered list of unsubscribe
+ * functions so the caller can tear them down at shutdown BEFORE module
+ * `onClose` (while module deps are still alive). Fails at boot on:
+ *   - a duplicate NAMED handler across modules (attributing both owners);
+ *   - a module declaring handlers while the event subsystem is unavailable.
+ * Resolves factory contributions (after bootstraps) so a handler can close over
+ * booted engines rather than a global getter.
+ */
+declare function subscribeModuleEventHandlers(fastify: FastifyInstance, modules: readonly ArcModule[]): Promise<Array<() => void | Promise<void>>>;
+//#endregion
+//#region src/factory/module/order.d.ts
+/**
+ * Order modules for composition by their `dependsOn` edges — a STABLE
+ * topological sort. Called once at the start of the bootstrap phase; every
+ * subsequent phase (bootstrap, resources, afterResources, and reverse-order
+ * onClose) iterates the returned list, so a module's declared dependencies are
+ * always composed before it.
+ *
+ * "Stable" = modules with no edge between them keep their original list order,
+ * so declaring `dependsOn` on one module never silently reorders an unrelated
+ * one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
+ * returned unchanged.
+ *
+ * Fail-fast — throws (never reorders past a broken contract) on:
+ *   - duplicate module names (the name is the graph key)
+ *   - a `dependsOn` name not present in the composed set
+ *   - a self-reference (`dependsOn` includes the module's own name)
+ *   - a dependency cycle (reports the concrete `a → b → … → a` path)
+ */
+declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
+//#endregion
+//#region src/factory/module/resolve.d.ts
+/**
+ * Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
+ * (this is where a dynamic `import()` fires); a promise (or plain module) is
+ * awaited. Called once per module at the start of the bootstrap phase.
+ */
+declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
+/** Resolve a `ModuleContribution` to a concrete array (array passthrough or factory call). */
+declare function resolveContribution<T>(contribution: ModuleContribution<T> | undefined, fastify: FastifyInstance): Promise<readonly T[]>;
+//#endregion
+//#region src/factory/module/state.d.ts
+type ModuleState = "resolved" | "bootstrapping" | "ready" | "closing" | "closed" | "failed";
+/**
+ * Is `name` in the composed module graph? TRUE for resource-only modules and
+ * modules that exported nothing — the question `hasModuleExports()` cannot
+ * answer. FALSE before registerResources runs (no graph yet) and for
+ * uncomposed names.
+ */
+declare function hasModule(fastify: FastifyInstance, name: string): boolean;
+/**
+ * The module's current lifecycle state, or `undefined` when the module is not
+ * composed (or no graph has been composed on this instance). See the state
+ * machine in the file header.
+ */
+declare function getModuleState(fastify: FastifyInstance, name: string): ModuleState | undefined;
+//#endregion
+//#region src/factory/module/index.d.ts
+/**
+ * Identity helper for authoring a typed module — mirrors `defineResource`.
+ * Gives inference + a single obvious construction site; does no work.
+ *
+ * `TExports` is inferred from the `bootstrap` return value, so a module
+ * author gets a typed public export for free:
+ *
+ * ```ts
+ * export const accountingModule = (deps: Deps) =>
+ *   defineModule({
+ *     name: "accounting",
+ *     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
+ *   });
+ * ```
+ */
+declare function defineModule<TExports = unknown>(module: ArcModule<TExports>): ArcModule<TExports>;
+/**
+ * Typed accessor for a module's public export (its `bootstrap` return value),
+ * recorded at `fastify.arc.modules[name]`.
+ *
+ * Throwing, in line with the fail-fast contract (and `requireOrgId`-style
+ * accessors): a missing entry means the module either isn't composed, is
+ * composed AFTER the caller (list order = init order), or returned nothing —
+ * all wiring bugs that must surface at boot, not as `undefined` downstream.
+ *
+ * The type parameter is an assertion, not a proof. Two ways to type it:
+ *   - augment `ArcModuleRegistry` once — then the name alone infers the type:
+ *     `getModuleExports(f, "accounting")` → `AccountingEngine`.
+ *   - or pass it inline: `getModuleExports<AccountingEngine>(f, "accounting")`.
+ *
+ * Siblings, for the two shapes this one is wrong for:
+ *   - `getOptionalModuleExports` — the module is genuinely OPTIONAL.
+ *   - `lazyModuleExports` / `lazyRequiredModuleExports` — the read happens at
+ *     composition time, where boot order decides the answer.
+ */
+declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
+declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
+/**
+ * Non-throwing sibling of `getModuleExports`: `undefined` when the module is
+ * not composed (or has not bootstrapped yet).
+ *
+ * Exists because OPTIONAL sibling modules are a first-class composition shape —
+ * a deployment that turns `inventory` off still sells services, so its POS
+ * module must ask "is inventory here?" rather than fail-fast. Hosts were
+ * spelling that question as
+ *
+ * ```ts
+ * (fastify as unknown as { arc?: { modules?: Record<string, unknown> } })
+ *   .arc?.modules?.inventory;
+ * ```
+ *
+ * — a double cast that (a) defeats `ArcModuleRegistry` inference, (b) silently
+ * survives a typo in the module name, and (c) is impossible to grep for. Use
+ * `getModuleExports` when the dependency is REQUIRED (boot must fail), this
+ * when it is genuinely optional.
+ *
+ * Prefer `lazyModuleExports` whenever the read happens at COMPOSITION time —
+ * see its doc for why a value read once can latch `undefined` forever.
+ */
+declare function getOptionalModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K] | undefined;
+declare function getOptionalModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports | undefined;
+/**
+ * Is a module's public export recorded yet? The predicate form of
+ * `getOptionalModuleExports`, for readiness gates (`ready: () => ...`) that
+ * should not have to reason about falsy-but-present exports.
+ */
+declare function hasModuleExports(fastify: FastifyInstance, name: string): boolean;
+/**
+ * A DEFERRED reader of a sibling module's export: returns a getter that reads
+ * the registry at CALL time, not now.
+ *
+ * ── Why this exists (the bug it removes) ─────────────────────────────────────
+ *
+ * Module composition runs bootstraps in dependency/list order, but a lot of
+ * wiring is *registered* earlier than it *runs*: an `eventHandlers` factory, a
+ * bridge accessor handed to another module, a hook added during bootstrap and
+ * fired per request. Such a factory can execute BEFORE the sibling it needs has
+ * bootstrapped — so a sibling engine captured into a local at that moment is
+ * `undefined`, and stays `undefined` for the life of the process even though the
+ * sibling came up milliseconds later.
+ *
+ * That failure is SILENT by construction: the consumer sees a null bridge and
+ * treats it as "this deployment has no inventory / no revenue engine", which is
+ * a legitimate configuration. Real cost in this codebase: orders were created
+ * and never payment-confirmed (no entitlement, no card, no door) and nothing
+ * errored anywhere.
+ *
+ * The getter therefore:
+ *   - re-reads while the module is ABSENT, so boot order cannot matter;
+ *   - memoizes the FIRST resolved value, so the steady-state read is a closure
+ *     variable rather than a registry lookup per request;
+ *   - never memoizes absence — that is precisely the latch this replaces.
+ *
+ * ```ts
+ * const inventory = lazyModuleExports<FlowEngine>(fastify, "inventory");
+ * return {
+ *   flowBridge: () => (inventory() ? createFlowEngineBridge({ getFlowEngine: () => inventory()! }) : null),
+ *   ready: () => inventory() !== undefined,
+ * };
+ * ```
+ */
+declare function lazyModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): () => ArcModuleRegistry[K] | undefined;
+declare function lazyModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): () => TExports | undefined;
+/**
+ * Required counterpart of `lazyModuleExports`: defers the read, then throws
+ * `getModuleExports`' error if the module is still absent at first use.
+ *
+ * The pair matters because "required" and "readable now" are different
+ * questions. A hook registered at bootstrap that needs the `order` engine at
+ * REQUEST time is a hard dependency, but reading it eagerly turns a correct
+ * composition into a boot crash purely because of list order. Deferring keeps
+ * the fail-fast guarantee and moves it to the first moment the answer is
+ * actually needed.
+ *
+ * Deferred does NOT mean unvalidated: a lazily-required module is still a
+ * HARD dependency, so PRESENCE is checked eagerly. When the composed module
+ * graph is known (any `createApp`/`registerResources` boot — the normal
+ * case), a name that is not in the graph throws HERE, at composition time,
+ * instead of surviving startup and failing on the first request or event.
+ * Only the EXPORT read (does bootstrap's return value exist yet?) is
+ * deferred to first call.
+ *
+ * Convention for hard sibling access: also declare the target in the
+ * consumer's `dependsOn`. That orders composition (the sibling's bootstrap
+ * runs first), while this accessor merely defers the read — the two are
+ * complementary, not alternatives:
+ *   - hard dependency, read during bootstrap → `dependsOn` + `getModuleExports`
+ *   - hard dependency, read at request/event time → `dependsOn` + this
+ *   - optional integration → `lazyModuleExports` (no `dependsOn` needed)
+ */
+declare function lazyRequiredModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): () => ArcModuleRegistry[K];
+declare function lazyRequiredModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): () => TExports;
+//#endregion
+export { lazyModuleExports as a, getModuleState as c, resolveModule as d, orderModules as f, collectModuleWorkflows as g, collectModuleScheduledJobs as h, hasModuleExports as i, hasModule as l, collectModuleHealthChecks as m, getModuleExports as n, lazyRequiredModuleExports as o, subscribeModuleEventHandlers as p, getOptionalModuleExports as r, ModuleState as s, defineModule as t, resolveContribution as u };