@classytic/arc 2.19.0 → 2.21.0

package/dist/{types-9_wtNPsI.d.mts → types-DpxoNX5v.d.mts}

@@ -1,208 +1,15 @@
-import { Ut as Authenticator } from "./index-CUTG2Cuo.mjs";
+import { Ut as Authenticator } from "./index-Dtrj6XZk.mjs";
 import { r as CacheStore } from "./interface-C1_WLTMK.mjs";
-import { n as ElevationOptions } from "./elevation-xGUBq6p_.mjs";
-import { a as EventTransport } from "./EventTransport-IEn7Tn-Q.mjs";
+import { n as ElevationOptions } from "./elevation-C9s5hFP_.mjs";
+import { a as EventTransport } from "./EventTransport-QmY7A258.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-BE6wFpYv.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-xzFyKAjT.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-DbBFd3x_.mjs";
-import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-D_eBCfNr.mjs";
-import { t as ErrorHandlerOptions } from "./errorHandler-BtUUDPEa.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-CfYWq-Ak.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-B0e-bq-O.mjs";
+import { l as ResourceLike, n as ArcModuleInput } from "./module-WeuU5jfd.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-A6EbthXR.mjs";
+import { _ as HealthOptions, f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-DQ4mCvg0.mjs";
 import { r as IdempotencyStore } from "./interface-Uk8ONJv7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
-
-//#region src/factory/loadResources.d.ts
-/**
- * loadResources — Auto-discover resource files from a directory.
- *
- * Scans for `*.resource.{ts,js,mts,mjs}` files, imports each,
- * and collects their default exports. No barrel file needed.
- *
- * @example
- * ```ts
- * import { createApp, loadResources } from '@classytic/arc/factory';
- *
- * // Recommended: import.meta.url — works in both src/ (dev) and dist/ (prod)
- * const app = await createApp({
- *   resources: await loadResources(import.meta.url),
- *   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
- * });
- *
- * // Or explicit path (must match runtime layout)
- * const app2 = await createApp({
- *   resources: await loadResources('./src/resources'),
- * });
- * ```
- *
- * File convention:
- * ```
- * src/resources/
- *   product/product.resource.ts    → export default defineResource({ name: 'product', ... })
- *   order/order.resource.ts        → export default defineResource({ name: 'order', ... })
- * ```
- */
-/**
- * Resource interface — the contract between `loadResources`/`createApp` and resource definitions.
- *
- * Matches the shape of `ResourceDefinition` from `defineResource()` without requiring
- * the import. All properties except `toPlugin` are optional so plain objects work too:
- *
- * ```typescript
- * // Full resource (from defineResource)
- * const product = defineResource({ name: 'product', ... }); // satisfies ResourceLike
- *
- * // Minimal resource (plain object)
- * const simple: ResourceLike = { name: 'ping', toPlugin: () => () => {} };
- * ```
- *
- * **DO NOT add an index signature** (`[key: string]: unknown`) to this interface.
- * Class instances (like `ResourceDefinition`) don't implicitly carry index signatures,
- * so adding one here makes `ResourceDefinition` *unassignable* to `ResourceLike` —
- * the exact opposite of the intent. TypeScript's structural typing already allows
- * classes with extra properties to satisfy this interface without an index signature.
- */
-interface ResourceLike {
-  /** Plugin factory — called by createApp to register routes */
-  toPlugin: () => unknown;
-  /** Resource name (used for route generation, logging, duplicate detection) */
-  name?: string;
-  /** Route prefix (default: `/${name}s`) */
-  prefix?: string;
-  /** Skip the global `resourcePrefix` from createApp — register at root */
-  skipGlobalPrefix?: boolean;
-  /** Display name for docs/OpenAPI */
-  displayName?: string;
-  /** Applied preset names */
-  _appliedPresets?: string[];
-}
-/**
- * Resource module — what a `.resource.ts` file's default (or named) export
- * may resolve to.
- *
- * Two shapes accepted:
- *   1. **Plain `ResourceLike`** — the result of `defineResource({...})`.
- *      Used as-is; no engine wiring needed.
- *   2. **Factory `(ctx: TContext) => ResourceLike | Promise<ResourceLike>`**
- *      — a function arc calls with the `context` from `LoadResourcesOptions`.
- *      Eliminates the parallel `createXResource(engine)` factory files +
- *      `exclude: [...]` bookkeeping that engine-bound resources used to need.
- *
- * Detection is by `typeof === 'function'`: `ResourceDefinition` instances
- * (returned by `defineResource()`) are class instances (`typeof === 'object'`),
- * so the two shapes are unambiguous in practice.
- */
-type ResourceModule<TContext = unknown> = ResourceLike | ((ctx: TContext) => ResourceLike | Promise<ResourceLike>);
-interface LoadResourcesOptions<TContext = unknown> {
-  /** File pattern suffix (default: '.resource'). Matches `*.resource.{ts,js,mts,mjs}`. */
-  suffix?: string;
-  /** Recurse into subdirectories (default: true) */
-  recursive?: boolean;
-  /**
-   * Context passed to factory-style default exports. Resources whose default
-   * export is a function `(ctx) => ResourceLike` are called with this value;
-   * plain `ResourceLike` exports are returned unchanged.
-   *
-   * Use this to thread engine handles into engine-bound resources without
-   * creating parallel factory files outside `loadResources`'s sweep:
-   *
-   * ```ts
-   * // category.resource.ts
-   * import type { AppContext } from '#core/app/context.js';
-   * export default (ctx: AppContext) =>
-   *   defineResource({
-   *     name: 'category',
-   *     adapter: createMongooseAdapter(
-   *       ctx.catalog.models.Category,
-   *       ctx.catalog.repositories.category,
-   *     ),
-   *   });
-   *
-   * // create-arc-app-options.ts
-   * resources: async () => {
-   *   const [catalog, flow] = await Promise.all([
-   *     ensureCatalogEngine(),
-   *     ensureFlowEngine(),
-   *   ]);
-   *   return loadResources(import.meta.url, { context: { catalog, flow } });
-   * }
-   * ```
-   *
-   * Backwards compatible — pre-2.11.1 callers omit `context`, plain exports
-   * keep working unchanged. Factories that need a context but receive
-   * `undefined` should narrow defensively.
-   */
-  context?: TContext;
-  /**
-   * Resource names to exclude. Matched against the resource's `.name` property
-   * after import, so you use the resource name (not the filename).
-   *
-   * @example
-   * ```ts
-   * await loadResources('./src/resources', { exclude: ['debug', 'legacy-report'] })
-   * ```
-   */
-  exclude?: string[];
-  /**
-   * Resource names to include. When set, only matching resources are returned.
-   * Takes priority over `exclude`.
-   *
-   * @example
-   * ```ts
-   * // Only load these two resources (useful for testing or microservice splits)
-   * await loadResources('./src/resources', { include: ['product', 'order'] })
-   * ```
-   */
-  include?: string[];
-  /**
-   * Optional logger override for diagnostics. When omitted, warnings flow
-   * through arc's standard logger (`arcLog('loadResources')`) — same path
-   * as every other arc-internal warning, controlled by `ARC_SUPPRESS_WARNINGS=1`
-   * and routable via `configureArcLogger({ writer })`.
-   *
-   * Pass any object with `warn(msg)` to override (e.g. `fastify.log` —
-   * which is what `registerResources` passes automatically when arc's
-   * factory triggers auto-discovery via `resourceDir`).
-   *
-   * Pre-2.11.1 had a `silent: boolean` flag and "silent by default" semantics;
-   * both removed. Migration:
-   *
-   * ```ts
-   * // Pre-2.11.1                                // 2.11.1+
-   * loadResources(url, { silent: true });            // ARC_SUPPRESS_WARNINGS=1 (env)
-   *                                                  //   OR configureArcLogger({ writer })
-   * loadResources(url, { silent: !isDev });          // ARC_SUPPRESS_WARNINGS=1 in prod
-   * loadResources(url, { logger: pinoAdapter });     // unchanged — still works
-   * ```
-   */
-  logger?: {
-    warn: (msg: string) => void;
-  };
-}
-/**
- * Scan a directory for resource files and import their default exports.
- *
- * Accepts a directory path OR `import.meta.url` (file:// URL).
- * When given a URL, resolves to the directory containing that file —
- * so `loadResources(import.meta.url)` works in both dev (`src/`) and
- * production (`dist/`) without path gymnastics.
- *
- * @param dir - Directory path, or `import.meta.url` (file:// URL resolved to its dirname)
- * @param options - Pattern and recursion options
- * @returns Array of resource definitions (anything with `.toPlugin()`)
- *
- * @example
- * ```ts
- * // Works from both src/ and dist/ — resolves relative to the calling file
- * await loadResources(import.meta.url);
- *
- * // Subdirectory relative to the calling file
- * await loadResources(import.meta.url, { suffix: '.resource' });
- *
- * // Explicit path (must match runtime layout)
- * await loadResources('./src/resources');
- * ```
- */
-declare function loadResources<TContext = unknown>(dir: string, options?: LoadResourcesOptions<TContext>): Promise<ResourceLike[]>;
-//#endregion
 //#region src/testing/preloadResources.d.ts
 /** Eager glob result: `{ '/path/to/file.ts': resourceModule }` */
 type EagerGlobResult = Record<string, unknown>;
@@ -287,11 +94,17 @@ interface JwtAuthOption {
    * If provided, jwt utilities are available in authenticator context
    */
   jwt?: {
-    /** JWT secret (required for JWT features) */secret: string; /** Access token expiry (default: '15m') */
-    expiresIn?: string; /** Refresh token secret (defaults to main secret) */
-    refreshSecret?: string; /** Refresh token expiry (default: '7d') */
-    refreshExpiresIn?: string; /** Additional @fastify/jwt sign options */
-    sign?: Record<string, unknown>; /** Additional @fastify/jwt verify options */
+    /** JWT secret (required for JWT features) */
+    secret: string;
+    /** Access token expiry (default: '15m') */
+    expiresIn?: string;
+    /** Refresh token secret (defaults to main secret) */
+    refreshSecret?: string;
+    /** Refresh token expiry (default: '7d') */
+    refreshExpiresIn?: string;
+    /** Additional @fastify/jwt sign options */
+    sign?: Record<string, unknown>;
+    /** Additional @fastify/jwt verify options */
     verify?: Record<string, unknown>;
   };
   /**
@@ -481,9 +294,13 @@ interface CreateAppOptions {
    * not memory-backed. Provide Redis or other durable adapters.
    */
   stores?: {
-    /** Event transport (e.g., RedisEventTransport) */events?: EventTransport; /** Cache store (e.g., RedisCacheStore) */
-    cache?: CacheStore; /** Idempotency store (e.g., RedisIdempotencyStore) */
-    idempotency?: IdempotencyStore; /** QueryCache store (e.g., RedisCacheStore). Default: MemoryCacheStore. */
+    /** Event transport (e.g., RedisEventTransport) */
+    events?: EventTransport;
+    /** Cache store (e.g., RedisCacheStore) */
+    cache?: CacheStore;
+    /** Idempotency store (e.g., RedisIdempotencyStore) */
+    idempotency?: IdempotencyStore;
+    /** QueryCache store (e.g., RedisCacheStore). Default: MemoryCacheStore. */
     queryCache?: CacheStore;
   };
   /** Fastify logger configuration */
@@ -634,7 +451,8 @@ interface CreateAppOptions {
   rawBody?: RawBodyOptions | false;
   /** Enable Arc plugins (requestId, health, gracefulShutdown, events, caching, sse) */
   arcPlugins?: {
-    /** Request ID tracking (default: true) */requestId?: boolean;
+    /** Request ID tracking (default: true) */
+    requestId?: boolean;
     /**
      * Health endpoints (default: true).
      *
@@ -661,8 +479,10 @@ interface CreateAppOptions {
      * }
      * ```
      */
-    health?: boolean | HealthOptions; /** Graceful shutdown handling (default: true) */
-    gracefulShutdown?: boolean; /** Emit events for CRUD operations (default: true) */
+    health?: boolean | HealthOptions;
+    /** Graceful shutdown handling (default: true) */
+    gracefulShutdown?: boolean;
+    /** Emit events for CRUD operations (default: true) */
     emitEvents?: boolean;
     /**
      * Event plugin configuration. Default: true (enabled with MemoryEventTransport).
@@ -843,6 +663,56 @@ interface CreateAppOptions {
    * ```
    */
   serializeBigInt?: boolean | "number" | "string";
+  /**
+   * Domain modules — compose whole domains into the app, one entry each.
+   *
+   * Where a `resources` entry is a single route group, a module is a self-
+   * contained domain package's full contribution (engine init + resources +
+   * post-wiring) bundled as one `ArcModule`. A package exports
+   * `createXModule(deps): ArcModule`; the host lists it here instead of hand-
+   * threading the package's pieces across `bootstrap` / `resources` /
+   * `afterResources`.
+   *
+   * Modules are pure sugar over the existing lifecycle — each expands into the
+   * SAME phases, in `dependsOn` order, running BEFORE the app-level entry in
+   * every phase:
+   * ```
+   * app plugins()  → modules[].plugins         (infra registration)
+   * modules[].bootstrap      → options.bootstrap
+   * modules[].resources      → options.resources / resourceDir  (see note ↓)
+   * modules[].afterResources → options.afterResources
+   * modules[].onClose (REVERSE order) → options.onClose   (one hook; see below)
+   * ```
+   * RESOURCES — two orderings, both intentional: app `resources`/`resourceDir`
+   * RESOLVE first (semantics untouched), but module resources REGISTER first
+   * (prepended, so their routes mount ahead of app resources). Teardown runs
+   * module `onClose` (reverse composition order) then app `onClose` in a single
+   * close hook, so module teardown (flush outboxes, drain queues, close a
+   * module-owned connection) sees live shared infra — the app/plugin
+   * connections close last. Module resources flow through arc's normal
+   * registration (prefix, dedup, docs, audit) — they are not special-cased.
+   *
+   * Entries may be eager modules, promises, or **thunks of dynamic imports**
+   * (the `next/dynamic` idea, backend-shaped) — thunks resolve once at boot,
+   * so region/tier-gated packs are only imported when selected:
+   *
+   * @example
+   * ```ts
+   * const taxPack = region === 'BD'
+   *   ? () => import('@classytic/bd-tax/module').then((m) => m.createBdTaxModule(deps))
+   *   : () => import('@classytic/us-tax/module').then((m) => m.createUsTaxModule(deps));
+   *
+   * const app = await createApp({
+   *   resourcePrefix: '/api/v1',
+   *   modules: [accountingModule({ permissions }), taxPack],
+   *   resources: [healthResource], // app-local resources still compose alongside
+   * });
+   * ```
+   *
+   * See `wiki/modules.md` for the full design (authoring convention, events/
+   * outbox integration, microservices path).
+   */
+  modules?: ReadonlyArray<ArcModuleInput>;
   /**
    * Resources to register automatically. Accepts two shapes:
    *
@@ -993,6 +863,32 @@ interface CreateAppOptions {
    * @default false
    */
   strictResources?: boolean;
+  /**
+   * Pre-boot hook — awaited BEFORE arc does anything else: before the
+   * Fastify instance exists, before module thunks resolve, before resource
+   * discovery imports a single host file.
+   *
+   * The canonical slot for the DB connection and anything that
+   * module-EVAL-time code depends on. Engines that register Mongoose models
+   * at import time (top-level `createXEngine(...)`) trigger eager
+   * `createIndex()` calls from schema plugins — if the connection isn't
+   * open yet those buffer and die with `buffering timed out`. Hosts used to
+   * hand-orchestrate this with `await connectDatabase()` + dynamic
+   * `await import(...)` tricks before calling `createApp`; with `beforeBoot`
+   * the ordering is arc's contract instead:
+   *
+   * ```ts
+   * const app = await createApp({
+   *   beforeBoot: async () => { await connectDatabase(); },
+   *   modules: [() => import('#modules/accounting.js')], // thunks resolve AFTER beforeBoot
+   *   resources: async () => [...],
+   * });
+   * ```
+   *
+   * Runs after option validation (config bugs fail fast without touching
+   * the DB). Cleanup stays host-owned — pair with `onClose`.
+   */
+  beforeBoot?: () => void | Promise<void>;
   /**
    * Custom plugin registration — runs after Arc core (security, auth, events)
    * but before `bootstrap` and `resources`.
@@ -1049,7 +945,9 @@ interface UnderPressureOptions {
 }
 interface MultipartOptions {
   limits?: {
-    /** Max file size in bytes (default: Fastify default ~1MB) */fileSize?: number; /** Max number of files per request */
+    /** Max file size in bytes (default: Fastify default ~1MB) */
+    fileSize?: number;
+    /** Max number of files per request */
     files?: number;
   };
 }
@@ -1064,4 +962,4 @@ interface RawBodyOptions {
   runFirst?: boolean;
 }
 //#endregion
-export { CustomPluginAuthOption as a, RawBodyOptions as c, preloadResourcesAsync as d, LoadResourcesOptions as f, loadResources as h, CustomAuthenticatorOption as i, UnderPressureOptions as l, ResourceModule as m, BetterAuthOption as n, JwtAuthOption as o, ResourceLike as p, CreateAppOptions as r, MultipartOptions as s, AuthOption as t, preloadResources as u };
+export { CustomPluginAuthOption as a, RawBodyOptions as c, preloadResourcesAsync as d, CustomAuthenticatorOption as i, UnderPressureOptions as l, BetterAuthOption as n, JwtAuthOption as o, CreateAppOptions as r, MultipartOptions as s, AuthOption as t, preloadResources as u };