@forinda/kickjs 5.16.0 → 5.18.0-alpha.0

package/dist/adapter-CkpcZwzZ.d.mts

@@ -1,407 +0,0 @@
-
-import { i as Constructor, o as MaybePromise } from "./interfaces-DbTyKGdS.mjs";
-import { t as Container } from "./container-TWOUyR_0.mjs";
-import { s as ContributorRegistrations } from "./context-decorator-DDZ30BIW.mjs";
-import http from "node:http";
-import { ErrorRequestHandler, Express, RequestHandler } from "express";
-
-//#region src/core/introspect.d.ts
-/**
- * Per-primitive introspection snapshot — the JSON shape an adapter or
- * plugin's optional `introspect()` hook returns for DevTools.
- *
- * Lives in `@forinda/kickjs` (not `@forinda/kickjs-devtools-kit`) so
- * adopters can type their `introspect()` return without taking on a
- * dep on the kit just to satisfy the contract. The kit's own
- * `IntrospectionSnapshot` type is structurally identical and continues
- * to be the canonical doc location for DevTools-side consumers; the
- * two stay in lockstep — if a field is added on one side it MUST be
- * added on the other (covered by the type-equivalence test in the
- * devtools-kit package).
- *
- * Cheap-by-default principle: `state` and `metrics` should be O(1) to
- * compute (counters, flags, recent samples). Anything that requires a
- * DB round trip or a full DI graph walk belongs behind a separate
- * explicit RPC — DevTools polls topology aggressively.
- */
-interface IntrospectionSnapshot {
-  /**
-   * Wire-protocol version this snapshot conforms to. The kit ships a
-   * `PROTOCOL_VERSION` constant typed as the literal `1`; we mirror
-   * that literal here so structural parity is enforced both ways —
-   * an adopter who writes `protocolVersion: 1` satisfies both this
-   * type and the kit's `IntrospectionSnapshot`. Bumping is a
-   * coordinated kit + framework release; widen this literal in
-   * lockstep.
-   */
-  protocolVersion: 1;
-  /** Stable identity matching the `name` from `definePlugin` / `defineAdapter`. */
-  name: string;
-  /** Discriminator for what kind of primitive this is. */
-  kind: IntrospectionKind;
-  /** Optional version string from the plugin / adapter metadata. */
-  version?: string;
-  /**
-   * Reactive state surface — JSON-serialisable snapshot. Keep small
-   * (under a few KB) so polling stays cheap.
-   */
-  state?: Record<string, unknown>;
-  /** DI tokens this primitive registers (`provides`) or consumes (`requires`). */
-  tokens?: {
-    provides: readonly string[];
-    requires: readonly string[];
-  };
-  /**
-   * Per-instance counters — active connections, in-flight jobs, cached
-   * items, etc. Numbers only so the DevTools panel can chart trends.
-   */
-  metrics?: Record<string, number>;
-  /** Self-reported memory footprint estimate, in bytes. Optional. */
-  memoryBytes?: number;
-}
-/**
- * What kind of primitive an introspection snapshot describes. Matches
- * the kit's `IntrospectionKind` and the routing the topology aggregator
- * does when bucketing adapters vs plugins vs middleware vs contributor
- * primitives.
- */
-type IntrospectionKind = 'plugin' | 'adapter' | 'middleware' | 'contributor';
-/**
- * Convenience function signature for adopter-side helpers that return
- * a complete snapshot. Used by the optional `introspect?()` hook on
- * `AppAdapter` and `KickPlugin`.
- */
-type IntrospectFn = () => IntrospectionSnapshot | Promise<IntrospectionSnapshot>;
-//#endregion
-//#region src/core/augmentation.d.ts
-/**
- * Augmentation registry — runtime no-op + the canonical
- * `KickJsPluginRegistry` interface that `kick typegen` augments.
- *
- * See `architecture.md` §21.2.1 (typegen for `dependsOn`) and §21.3.3
- * (standardized augmentation registry) for the design rationale.
- *
- * @module @forinda/kickjs/core/augmentation
- */
-/**
- * Marker interface that lists every plugin/adapter in the project. The
- * keys are the literal `name` field passed to `defineAdapter` /
- * `definePlugin` (or declared on a `class implements AppAdapter`); the
- * values are the kind tag (`'plugin' | 'adapter'`).
- *
- * The framework ships this empty. `kick typegen` augments it from
- * source so `keyof KickJsPluginRegistry` resolves to a string-literal
- * union of every name in scope — and therefore so do `dependsOn`
- * declarations on plugins/adapters.
- */
-interface KickJsPluginRegistry {}
-/**
- * Resolves to a string-literal union of every registered plugin/adapter
- * name when the project's typegen has populated `KickJsPluginRegistry`,
- * or to `string` when the registry is empty (no typegen pass yet).
- *
- * Falling back to `string` keeps fresh projects compiling — the typegen
- * narrowing is a progressive enhancement, not a hard prerequisite.
- */
-type KickJsPluginName = keyof KickJsPluginRegistry extends never ? string : keyof KickJsPluginRegistry & string;
-/**
- * Metadata attached to a `defineAugmentation` call. The fields are
- * documentation-only — `kick typegen` surfaces them in the generated
- * `.kickjs/types/augmentations.d.ts` so adopters can browse every
- * augmentable interface from one place.
- *
- * `description` and `example` may both be multi-line — typegen preserves
- * line breaks when rendering them as JSDoc. There is no upper limit on
- * the example size; entire shape definitions or worked snippets are fine.
- */
-interface AugmentationMeta {
-  /**
-   * Free-form description of what the augmentation customises. May be
-   * multi-line — newlines are preserved in the generated JSDoc.
-   */
-  description?: string;
-  /**
-   * TS snippet showing a typical shape. May be multi-line; rendered
-   * inside a fenced code block in the generated catalogue. Use this
-   * for anything from `'{ foo: string }'` up to a full interface body
-   * — typegen no longer flattens newlines.
-   */
-  example?: string;
-}
-/**
- * Advertise an augmentable interface so `kick typegen` can list it in
- * `.kickjs/types/augmentations.d.ts` for project-wide discovery.
- *
- * **This function is a runtime AND type-level no-op.** It does NOT
- * augment the interface for TypeScript. The actual augmentation is
- * the `declare module` block — `defineAugmentation` only adds an
- * entry to the typegen catalogue so other contributors / adopters
- * can find the interface and know its expected shape.
- *
- * Both calls are needed:
- *
- * ```ts
- * import { defineAugmentation } from '@forinda/kickjs'
- *
- * // (1) The actual TS augmentation — what `ctx.get('tenant')` reads.
- * declare module '@forinda/kickjs' {
- *   interface ContextMeta {
- *     tenant: { id: string; name: string }
- *   }
- * }
- *
- * // (2) Catalogue entry — what `kick typegen` lists in
- * //     `.kickjs/types/augmentations.d.ts` for browseability.
- * defineAugmentation('ContextMeta', {
- *   description: 'Tenant resolved from x-tenant-id by TenantAdapter',
- *   example: `{
- *     tenant: {
- *       id: string
- *       name: string
- *       plan: 'free' | 'pro' | 'enterprise'
- *       featureFlags: Record<string, boolean>
- *     }
- *   }`,
- * })
- * ```
- *
- * Skip `defineAugmentation` if you don't care about the catalogue — the
- * `declare module` block alone is enough for runtime + type behaviour.
- *
- * @deprecated Low value in practice: it does nothing at runtime or at
- * the type level — the `declare module` block alone gives you the
- * augmentation, and the generated `.kickjs/types/kick__augmentations.d.ts`
- * catalogue it feeds is documentation-only. Prefer a plain
- * `declare module '@forinda/kickjs' { ... }` block and (optionally) a
- * JSDoc comment on your own interface. `defineAugmentation` and the
- * `kick/augmentations` typegen plugin will be removed in a future major.
- */
-declare function defineAugmentation(name: string, meta?: AugmentationMeta): void;
-//#endregion
-//#region src/core/adapter.d.ts
-/**
- * Where in the middleware pipeline an adapter's middleware should be inserted.
- *
- * - `beforeGlobal` — runs **before** any user-defined global middleware.
- *   Suitable for transport-level concerns (request tagging, low-level
- *   request rewriting). Fires on every request.
- * - `afterGlobal` — runs **after** global middleware, **before** module
- *   routes are matched. Default for most adapter middleware (auth pre-checks,
- *   tenant resolution, body shaping). Fires on every request.
- * - `beforeRoutes` — runs just before module routes are mounted. Functionally
- *   equivalent to `afterGlobal` for most cases; the explicit phase exists so
- *   adapters that *must* sit at the very end of the pre-route stack can
- *   declare intent. Fires on every request.
- * - `afterRoutes` — sits **after** module routes but **before** error
- *   handlers. **Fires only on fall-through** — when no route matched (404
- *   path) or a route handler called `next()` without ending the response.
- *   Controllers that respond with `ctx.json(...)` end the chain and skip
- *   this phase, so it is *not* a "post-response" hook. For per-response
- *   work (logging, metrics) use `res.on('finish', ...)` from inside an
- *   earlier-phase middleware instead.
- */
-type MiddlewarePhase = 'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes';
-/**
- * Path scope for an {@link AdapterMiddleware} entry. Mirrors what
- * Express's `app.use(path, handler)` accepts so adapters get the full
- * range without learning a new mini-language:
- *
- * - A `string` prefix — `'/api'` matches `/api`, `/api/v1`, `/api/v1/x`.
- * - A `RegExp` — `/^\/api\/v\d+/` matches `/api/v1`, `/api/v42`.
- * - An array of either — `['/api', '/admin']` matches either prefix;
- *   `['/api', /^\/internal\//]` mixes shapes.
- *
- * Omit to apply the middleware unconditionally (Express `app.use(handler)`).
- */
-type MiddlewarePath = string | RegExp | ReadonlyArray<string | RegExp>;
-/** A middleware entry contributed by an adapter */
-interface AdapterMiddleware {
-  /**
-   * Express handler: either a `RequestHandler` (`(req, res, next) => …`)
-   * or an `ErrorRequestHandler` (`(err, req, res, next) => …`).
-   * Express dispatches based on arity, so the same field accepts both
-   * without a discriminant.
-   */
-  handler: RequestHandler | ErrorRequestHandler;
-  /** Which phase to insert into (default: 'afterGlobal') */
-  phase?: MiddlewarePhase;
-  /**
-   * Optional path scope. See {@link MiddlewarePath} for the accepted
-   * shapes (string prefix, RegExp, or an array mixing both). Omit to
-   * apply the middleware to every request that reaches this phase.
-   */
-  path?: MiddlewarePath;
-}
-/**
- * Context passed to adapter lifecycle hooks.
- * Populated by the Application — provides access to the Express app,
- * DI container, http.Server, and environment info without requiring
- * external type imports. Cast `app` or `server` if you need specific types.
- *
- * @example
- * ```ts
- * beforeMount({ app, container }: AdapterContext) {
- *   app.use(myMiddleware())
- * }
- * ```
- */
-interface AdapterContext {
-  /** Express application instance — fully typed */
-  app: Express;
-  /** DI container */
-  container: Container;
-  /** Node.js http.Server — only available in afterStart */
-  server?: http.Server;
-  /** Current NODE_ENV value (default: 'development') */
-  env: string;
-  /** true when NODE_ENV === 'production' */
-  isProduction: boolean;
-}
-/**
- * Adapters plug into the Application lifecycle.
- * Implement this to add WebSocket, database, rate limiting, docs, etc.
- *
- * All hooks receive an `AdapterContext` populated by the framework.
- * No external type imports needed — the context is fully typed from KickJS internals.
- *
- * @example
- * ```ts
- * import type { AppAdapter, AdapterContext } from '@forinda/kickjs/adapter'
- *
- * class SentryAdapter implements AppAdapter {
- *   name = 'SentryAdapter'
- *
- *   beforeMount({ app, container }: AdapterContext) {
- *     app.use(Sentry.expressRequestHandler())
- *   }
- *
- *   afterStart({ server }: AdapterContext) {
- *     // server is the http.Server — available after listen()
- *   }
- *
- *   async shutdown() {
- *     await Sentry.close(2000)
- *   }
- * }
- * ```
- */
-interface AppAdapter {
-  /**
-   * Human-readable name for logging and `dependsOn` resolution.
-   * Required when the adapter (or any other in the same set) declares
-   * `dependsOn` — sort errors will reference adapters by name.
-   */
-  name?: string;
-  /**
-   * Other adapter names that must mount before this one. The framework
-   * topologically sorts adapters at boot — cycles or unknown names throw
-   * via `MountCycleError` / `MissingMountDepError` so bad configurations
-   * fail boot rather than corrupt live traffic.
-   *
-   * Common pattern: `TenantAdapter` populates `req.tenant` and
-   * `AuthAdapter` reads it for tenant-scoped RBAC, so AuthAdapter
-   * declares `dependsOn = ['TenantAdapter']`. Adapters without
-   * `dependsOn` retain their declaration order.
-   *
-   * @example
-   * ```ts
-   * class AuthAdapter implements AppAdapter {
-   *   name = 'AuthAdapter'
-   *   dependsOn = ['TenantAdapter']
-   * }
-   * ```
-   */
-  dependsOn?: readonly KickJsPluginName[];
-  /**
-   * Return middleware entries to be inserted into the pipeline.
-   * The `phase` controls ordering relative to global middleware and routes.
-   */
-  middleware?(): AdapterMiddleware[];
-  /**
-   * Return Context Contributors (#107) that apply to every route in the
-   * application. Adapter-level contributors merge into the per-route
-   * pipeline at the `'adapter'` precedence level — they win over global
-   * contributors but lose to module, class, and method decorators.
-   *
-   * Useful for cross-cutting concerns: an auth adapter contributing
-   * `user`, a multi-tenant adapter contributing `tenant`, etc. Optional.
-   */
-  contributors?(): ContributorRegistrations;
-  /**
-   * Called before global middleware — register early routes (docs UI, health).
-   * May return a Promise — async rejections are caught and logged.
-   */
-  beforeMount?(ctx: AdapterContext): void | Promise<void>;
-  /**
-   * Called for each module route that gets mounted.
-   * Use this to collect route metadata (e.g. for OpenAPI spec generation).
-   */
-  onRouteMount?(controllerClass: Constructor, mountPath: string): void;
-  /**
-   * Called after modules are registered and the DI container is bootstrapped,
-   * before the HTTP server starts listening. **This is the correct hook for
-   * adapters that register DI bindings, resolve services, or otherwise prepare
-   * container-side state** (e.g. `container.registerInstance(MAILER, ...)`).
-   *
-   * `beforeStart` runs inside `app.setup()`, which means it also fires under
-   * `createTestApp` — adapters using this hook work in unit tests without
-   * needing a live HTTP server. See {@link afterStart} for the contrast.
-   *
-   * May return a Promise — async rejections are caught and logged.
-   */
-  beforeStart?(ctx: AdapterContext): void | Promise<void>;
-  /**
-   * Called after the HTTP server is listening — `ctx.server` is the live
-   * `http.Server`. **Use this hook only for work that genuinely needs a
-   * listening server**: attaching Socket.IO / WS upgrades, reading the bound
-   * port via `server.address()`, dispatching to the local server over HTTP,
-   * etc.
-   *
-   * `afterStart` does NOT fire under `createTestApp`, since tests call
-   * `app.setup()` and never `app.start()`. If your adapter only registers DI
-   * bindings or resolves services, use {@link beforeStart} — that hook runs
-   * in both production (`start()`) and tests (`setup()`).
-   *
-   * May return a Promise — async rejections are caught and logged.
-   */
-  afterStart?(ctx: AdapterContext): void | Promise<void>;
-  /**
-   * Called by the /health/ready endpoint. Return the health status of your adapter's
-   * backing service (database, Redis, queue, etc.).
-   */
-  onHealthCheck?(): Promise<{
-    name: string;
-    status: 'up' | 'down';
-  }>;
-  /** Called on shutdown — clean up connections */
-  shutdown?(): MaybePromise;
-  /**
-   * Optional DevTools introspection hook (architecture.md §23). Returns
-   * a snapshot describing this adapter's current state, metrics, and DI
-   * tokens. DevTools awaits the result, so async work is fine — but keep
-   * the implementation cheap (counters + flags, no DB round trips) since
-   * the topology endpoint polls on a short interval.
-   *
-   * The return type lives in `@forinda/kickjs` itself ({@link IntrospectionSnapshot})
-   * so adopters can author `introspect()` without importing the kit just
-   * to satisfy the contract. The kit's own `IntrospectionSnapshot` type
-   * stays structurally identical; either import works.
-   */
-  introspect?(): IntrospectionSnapshot | Promise<IntrospectionSnapshot>;
-  /**
-   * Optional DevTools tabs this adapter contributes (architecture.md §23).
-   * Returns an array of `DevtoolsTabDescriptor` shapes — typically one
-   * entry per adapter-owned panel (iframe / launch / html view).
-   *
-   * Same untyped-at-this-layer convention as {@link introspect}: adapter
-   * authors import `defineDevtoolsTab` (or the bare type) from
-   * `@forinda/kickjs-devtools-kit` so `@forinda/kickjs` doesn't take on
-   * a runtime dep on the kit.
-   */
-  devtoolsTabs?(): readonly unknown[];
-}
-/** Constructor type for AppAdapter classes */
-type AppAdapterClass = new () => AppAdapter;
-//#endregion
-export { MiddlewarePath as a, KickJsPluginName as c, IntrospectFn as d, IntrospectionKind as f, AppAdapterClass as i, KickJsPluginRegistry as l, AdapterMiddleware as n, MiddlewarePhase as o, IntrospectionSnapshot as p, AppAdapter as r, AugmentationMeta as s, AdapterContext as t, defineAugmentation as u };
-//# sourceMappingURL=adapter-CkpcZwzZ.d.mts.map

package/dist/adapter-CkpcZwzZ.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter-CkpcZwzZ.d.mts","names":[],"sources":["../src/core/introspect.ts","../src/core/augmentation.ts","../src/core/adapter.ts"],"mappings":";;;;;;;;;;;;;;;AAkBA;;;;;;;;;;;UAAiB,qBAAA;EAgBf;;;;;;;;;EANA,eAAA;EAoBW;EAlBX,IAAA;EA2B2B;EAzB3B,IAAA,EAAM,iBAAA;EAyBqB;EAvB3B,OAAA;EA8BU;;;;EAzBV,KAAA,GAAQ,MAAA;EAyB+C;EAvBvD,MAAA;IAAW,QAAA;IAA6B,QAAA;EAAA;EAuBuB;;AAAqB;;EAlBpF,OAAA,GAAU,MAAA;;EAEV,WAAA;AAAA;;;AC3BmC;AAUrC;;;KD0BY,iBAAA;ACxBkB;AAY9B;;;;AAZ8B,KD+BlB,YAAA,SAAqB,qBAAA,GAAwB,OAAA,CAAQ,qBAAA;;;;;;;;;;AA9CjE;;;;;;;;;;;;;UCGiB,oBAAA;;;;;;;;AD2BJ;KCjBD,gBAAA,SAAyB,oBAAA,gCAE3B,oBAAoB;;;;ADwBD;AAO7B;;;;;;UCnBiB,gBAAA;EDmB+C;;;;ECd9D,WAAA;EDcoF;;;;AC3CtF;;EAoCE,OAAO;AAAA;AApC4B;AAUrC;;;;AAE8B;AAY9B;;;;AAYS;AAmDT;;;;;;;;AAAwE;;;;AC/ExE;;;;AAA2B;AAc3B;;;;;;;;;;;;AAA4E;AAG5E;;;;;;;ADzBqC,iBAuFrB,kBAAA,CAAmB,IAAA,UAAc,IAAA,GAAO,gBAAgB;;;AD1FxE;;;;;;;;;;;;;;;;;;;;;AAAA,KEWY,eAAA;AFmBC;AASb;;;;AAA6B;AAO7B;;;;;;AAhBa,KELD,cAAA,YAA0B,MAAA,GAAS,aAAA,UAAuB,MAAA;;UAGrD,iBAAA;EFkBwC;;;AAA6B;;;EEXpF,OAAA,EAAS,cAAA,GAAiB,mBAAA;EDhCX;ECkCf,KAAA,GAAQ,eAAA;;;ADlC2B;AAUrC;;EC8BE,IAAA,GAAO,cAAA;AAAA;AD5BqB;AAY9B;;;;AAYS;AAmDT;;;;;;;AA3E8B,UC4Cb,cAAA;ED+BuD;EC7BtE,GAAA,EAAK,OAAA;;EAEL,SAAA,EAAW,SAAA;EApDD;EAsDV,MAAA,GAAS,IAAA,CAAK,MAAA;;EAEd,GAAA;EAxDyB;EA0DzB,YAAA;AAAA;;;;;;;;;;;AA5C0E;AAG5E;;;;;;;;;;;;;;;;;UAwEiB,UAAA;EAzCA;;;;;EA+Cf,IAAA;EAzCoB;;;;;;;;;;;;AAIR;AA+Bd;;;;;;EA2BE,SAAA,YAAqB,gBAAA;EAuBqB;;;;EAjB1C,UAAA,KAAe,iBAAA;EAqD0B;;;;;;;;;EA1CzC,YAAA,KAAiB,wBAAA;EAjBI;;;;EAuBrB,WAAA,EAAa,GAAA,EAAK,cAAA,UAAwB,OAAA;EAA1C;;;;EAMA,YAAA,EAAc,eAAA,EAAiB,WAAA,EAAa,SAAA;EAAb;;;;;;;;;;;;EAc/B,WAAA,EAAa,GAAA,EAAK,cAAA,UAAwB,OAAA;EAsBd;;;;;;;;;;AA6BhB;AAId;;;EAvCE,UAAA,EAAY,GAAA,EAAK,cAAA,UAAwB,OAAA;EAuCO;;;;EAjChD,aAAA,KAAkB,OAAA;IAAU,IAAA;IAAc,MAAA;EAAA;;EAG1C,QAAA,KAAa,YAAA;;;;;;;;;;;;;EAcb,UAAA,KAAe,qBAAA,GAAwB,OAAA,CAAQ,qBAAA;;;;;;;;;;;EAY/C,YAAA;AAAA;;KAIU,eAAA,aAA4B,UAAU"}

package/dist/app-module-BTzb-Vd6.d.mts

@@ -1,92 +0,0 @@
-
-import { t as Container } from "./container-TWOUyR_0.mjs";
-import { s as ContributorRegistrations } from "./context-decorator-DDZ30BIW.mjs";
-
-//#region src/core/app-module.d.ts
-/**
- * Route set returned by a module's routes() method.
- * Combined with versioning: /{apiPrefix}/v{version}{path}
- *
- * **Either** `controller` or `router` is required. Pass `controller`
- * for the common case — the framework calls `buildRoutes(controller)`
- * internally to derive the Express Router. Pass `router` directly
- * only when you need to compose multiple controllers under one path
- * or hand-build the router yourself.
- */
-interface ModuleRoutes {
-  /** URL prefix (e.g. '/users') */
-  path: string;
-  /**
-   * Express Router instance. Optional — when omitted, the framework
-   * builds one from `controller` via `buildRoutes(controller)`. Pass
-   * an explicit router only when you need to compose multiple
-   * controllers or hand-roll the router shape.
-   */
-  router?: any;
-  /** Optional API version override (defaults to Application.defaultVersion) */
-  version?: number;
-  /**
-   * Controller class. Required unless `router` is provided. Used both
-   * for the auto-derived router (via `buildRoutes(controller)`) and
-   * for OpenAPI spec generation via `SwaggerAdapter`.
-   */
-  controller?: any;
-}
-/**
- * Interface that every feature module must implement.
- * Modules register their DI bindings and declare their routes.
- *
- * `register` is **optional**. Modules that only contain decorated classes
- * (`@Service`, `@Controller`, `@Repository`, `@Component`) don't need it
- * because the decorators handle DI registration automatically. Implement
- * `register(container)` only when you need to bind a token (typically a
- * repository interface symbol) to a concrete implementation via
- * `container.registerFactory()` / `container.registerInstance()`.
- */
-interface AppModule {
-  /** Optional — bind interfaces to implementations in the container */
-  register?(container: Container): void;
-  /**
-   * Return Context Contributors (#107) that apply to every route this
-   * module mounts. Module-level contributors are merged into the per-route
-   * pipeline at the `'module'` precedence level — they win over adapter
-   * and global contributors but lose to method and class decorators.
-   *
-   * Optional — modules without per-module contributors omit this hook.
-   */
-  contributors?(): ContributorRegistrations;
-  /** Return route definitions for this module, or null for non-HTTP modules */
-  routes(): ModuleRoutes | ModuleRoutes[] | null;
-}
-/**
- * Constructor type for the legacy `class FooModule implements AppModule`
- * pattern. The framework still accepts these — bootstrap discriminates
- * class vs instance at boot — but new code should prefer
- * {@link defineModule} for parity with {@link defineAdapter} and
- * {@link definePlugin}, plus typed config + `.scoped()` / `.definition`.
- *
- * @deprecated Use `defineModule({ ... })` and `AppModuleEntry` for the
- *   `bootstrap({ modules })` array. The class form continues to work
- *   through v5 and is not slated for removal in any specific release —
- *   this annotation is a soft "prefer the factory form" hint, not an
- *   imminent deprecation.
- */
-type AppModuleClass = new () => AppModule;
-/**
- * Either form accepted by `bootstrap({ modules })` and
- * `KickPlugin.modules?()`:
- *
- *   - **Class** — the legacy form. Bootstrap calls `new ModuleClass()`.
- *   - **Instance** — produced by {@link defineModule}'s factory call
- *     (e.g. `TasksModule({ scope: 'admin' })`). Bootstrap uses it
- *     directly without `new`.
- *
- * Both shapes route through the same lifecycle (`register`,
- * `contributors`, `routes`) — the only difference is who owns
- * instantiation. defineModule callers use this union so adopters can
- * mix-and-match in the same `modules` array.
- */
-type AppModuleEntry = AppModuleClass | AppModule;
-//#endregion
-export { ModuleRoutes as i, AppModuleClass as n, AppModuleEntry as r, AppModule as t };
-//# sourceMappingURL=app-module-BTzb-Vd6.d.mts.map

package/dist/app-module-BTzb-Vd6.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"app-module-BTzb-Vd6.d.mts","names":[],"sources":["../src/core/app-module.ts"],"mappings":";;;;;;;AAaA;;;;;;;;UAAiB,YAAA;EAiBL;EAfV,IAAA;EA6BwB;;;;;;EAtBxB,MAAA;EAmCqC;EAjCrC,OAAA;EAsBqB;;;;;EAhBrB,UAAA;AAAA;;AA2BqC;AAgBvC;;;;AAAgD;AAgBhD;;;;UA7CiB,SAAA;;EAEf,QAAA,EAAU,SAAA,EAAW,SAAA;;;;;;;;;EASrB,YAAA,KAAiB,wBAAA;;EAEjB,MAAA,IAAU,YAAA,GAAe,YAAA;AAAA;;;;;;;;;;;;;;KAgBf,cAAA,aAA2B,SAAS;;;;;;;;;;;;;;;KAgBpC,cAAA,GAAiB,cAAA,GAAiB,SAAS"}

package/dist/application-CAnpDQ8d.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"application-CAnpDQ8d.d.mts","names":[],"sources":["../src/http/application.ts"],"mappings":";;;;;;;;;;;;;;KAqCY,eAAA,GAAkB,cAAA;EAAmB,IAAA;EAAc,OAAA,EAAS,cAAc;AAAA;AAAA,UAErE,kBAAA;;;;;;;;AAFqE;AAEtF;;EAWE,OAAA,EAAS,cAAA;EAAA;;;;;;;;;;;;;;;;;EAmBT,KAAA,EAAO,QAAA,EAAU,cAAA;EAQjB;EANA,QAAA,GAAW,UAAA;EA6BG;EA3Bd,IAAA;EAiCa;EA/Bb,SAAA;EAkCU;EAhCV,cAAA;EAsDe;;;;;;;;;;;;;;;;;;;;;EA/Bf,WAAA,GAAc,eAAA;EAiLZ;;AAAM;AAQV;;EAnLE,UAAA,GAAa,eAAA;EAqNyB;EAlNtC,OAAA,GAAU,UAAA;EAmRE;;;;;;;;;;;;;;;;;;;;EA7PZ,YAAA,GAAe,wBAAA;EAoLP;;;;;;;;;;;;;;;;;;EAhKR,YAAA;EAyO4D;;;;;;;;;;;;;;;;;;;;;;;;;EA9M5D,YAAA;EAy0BiB;EAt0BjB,UAAA,iCAA2C,EAAA,UAAY,QAAA;EAy1B/C;EAv1BR,SAAA;EAq3BQ;;;;;AA+CoB;;EA55B5B,aAAA;;;;;EAKA,cAAA;;;;;EAKA,eAAA;;;;;;;;;;;;;;;;;;;EAoBA,OAAA;IAAsB,OAAA;EAAA;;;;;;;;;;;;;;;;EAiBtB,UAAA,IAAc,GAAA,OAAU,GAAA,OAAU,IAAA;;;;;;;;;;;;;;;;;EAkBlC,OAAA,IAAW,GAAA,OAAU,GAAA,OAAU,GAAA,OAAU,IAAA;;;;;;;;;;;;;;;;;;EAmBzC,QAAA;6DAEE,MAAA;EAAA;AAAA;;;;;cAQS,WAAA;EAAA,iBAkCkB,OAAA;EAAA,QAjCrB,GAAA;EAAA,QACA,SAAA;EAAA,QACA,UAAA;EAAA,iBACS,QAAA;EAAA,iBAEA,OAAA;;;;;;;;;;;;;UAcT,mBAAA;;UAMA,iBAAA;;UAEA,SAAA;;UAEA,kBAAA;;UAEA,eAAA;EAER,WAAA,CAA6B,OAAA,EAAS,kBAAA;;MAqClC,UAAA;;MAKA,gBAAA;;EAKJ,YAAA,IAAgB,SAAA;;;;;;;;;;;;;;;EAkBhB,MAAA,CAAO,GAAA,EAAK,IAAA,CAAK,eAAA,EAAiB,GAAA,EAAK,IAAA,CAAK,cAAA,EAAgB,IAAA,IAAQ,GAAA;;;;;;;;;;;;;;;UAsB5D,UAAA;;UAYM,QAAA;EAeR,KAAA,IAAS,OAAA;;EA0TT,YAAA,IAAgB,OAAA;;;;;;;;;;EAahB,KAAA,IAAS,OAAA;;EA0ET,OAAA,IAAW,OAAA;;;;;;;;;;;EAoCX,QAAA,IAAY,OAAA;EAgElB,aAAA,IAAiB,OAAA;;EAKjB,WAAA,IAAe,UAAA;;;;;;EASf,UAAA,aAAuB,UAAA;;;;;;;;;;;;;;;;;;;EAsBvB,eAAA,IAAmB,aAAA;IACjB,GAAA;IACA,MAAA;IACA,KAAA;IACA,SAAA;EAAA;EA6CF,aAAA,IAAiB,IAAA,CAAK,MAAA;;;;;;;;;;;;;;UAmBd,2BAAA;EAAA,QAWA,wBAAA;EAAA,QAmBA,mBAAA;EAAA,QAgBA,oBAAA;;UASA,yBAAA;;UAsBA,oBAAA;AAAA"}

package/dist/application-DnnqoDWx.mjs

@@ -1,12 +0,0 @@
-/**
- * @forinda/kickjs v5.16.0
- *
- * Copyright (c) Felix Orinda
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- * @license MIT
- */
-import{n as tokenName,r as moduleRouteMissingControllerError,t as Container}from"./container-D1gfs6__.mjs";import{METADATA}from"./core/interfaces.mjs";import{Logger,createLogger}from"./core/logger.mjs";import{t as getClassMeta}from"./metadata-Cll3P0N0.mjs";import{g as MutableModuleRegistry,s as mountSort}from"./core-Db2uyqtM.mjs";import{normalizePath}from"./core/path.mjs";import{requestId}from"./http/middleware/request-id.mjs";import{errorHandler,notFoundHandler}from"./http/middleware/error-handler.mjs";import{i as requestStore}from"./context-MD7Mc_o_.mjs";import{_setExternalContributorSources,buildRoutes}from"./http/router-builder.mjs";import http from"node:http";import express from"express";import crypto from"node:crypto";const REQUEST_SCOPE_MIDDLEWARE_MARKER=Symbol.for(`@kickjs/requestScopeMiddleware`);function requestScopeMiddleware(){let mw=(req,_res,next)=>{let requestIdHeader=req.headers[`x-request-id`],requestId=(Array.isArray(requestIdHeader)?requestIdHeader[0]:requestIdHeader)||crypto.randomUUID(),store={requestId,instances:new Map,values:new Map};req.requestId=requestId,requestStore.run(store,()=>next())};return mw[REQUEST_SCOPE_MIDDLEWARE_MARKER]=!0,mw}function isRequestScopeMiddleware(value){return typeof value==`function`?value[REQUEST_SCOPE_MIDDLEWARE_MARKER]===!0:!1}const log=createLogger(`Application`);var Application=class{options;app;container;httpServer=null;adapters;plugins;_moduleContributors=[];_inFlightRequests=0;_draining=!1;_shutdownInitiated=!1;_drainResolvers=[];constructor(options){this.options=options,this.app=express(),this.container=Container.getInstance(),this.plugins=mountSort(options.plugins??[],`plugin`);let allAdapters=[...this.plugins.flatMap(p=>p.adapters?.()??[]),...options.adapters??[]],anonAdapterCount=0,namedAdapters=allAdapters.map(adapter=>{if(!adapter.name){let ctorName=adapter.constructor?.name,fallback=ctorName&&ctorName!==`Object`?ctorName:`AnonymousAdapter#${anonAdapterCount++}`;return Object.assign(adapter,{name:fallback})}return adapter});this.adapters=mountSort(namedAdapters,`adapter`),Container._requestStoreProvider=()=>requestStore.getStore()??null}get isDraining(){return this._draining}get inFlightRequests(){return this._inFlightRequests}getContainer(){return this.container}handle(req,res,next){next?this.app(req,res,next):this.app(req,res)}adapterCtx(server){let env=process.env.NODE_ENV??`development`;return{app:this.app,container:this.container,server,env,isProduction:env===`production`}}async callHook(hook,ctx){if(hook)try{let result=hook(ctx);result&&typeof result.then==`function`&&await result}catch(err){log.error(err,`Adapter hook failed`)}}async setup(){log.debug(`Bootstrapping application...`),this._moduleContributors=[];let adapterMw=this.collectAdapterMiddleware();this.app.__kickApp=this;let ctx=this.adapterCtx();for(let adapter of this.adapters)await this.callHook(adapter.beforeMount?.bind(adapter),ctx);this.app.disable(`x-powered-by`),this.app.set(`trust proxy`,this.options.trustProxy??!1),this.app.use(this.requestTrackingMiddleware()),this.mountHealthEndpoints(),this.shouldAutoMountRequestScope()&&this.app.use(requestScopeMiddleware()),this.mountMiddlewareList(adapterMw.beforeGlobal);for(let plugin of this.plugins)plugin.register?.(this.container);for(let plugin of this.plugins)try{let mw=plugin.middleware?.()??[];for(let handler of mw)this.app.use(handler)}catch(err){log.error(err,`Plugin middleware failed: ${plugin.name??`unknown`}`)}if(this.options.security?.helmet!==!1)try{let{helmet:helmetFn}=await import(`./http/middleware/helmet.mjs`);this.app.use(helmetFn())}catch{}let userMiddlewares=this.options.middlewares??this.options.middleware;if(userMiddlewares)for(let entry of userMiddlewares)this.mountMiddlewareEntry(entry);else this.app.use(requestId()),this.app.use(express.json({limit:this.options.jsonLimit??`1mb`}));this.mountMiddlewareList(adapterMw.afterGlobal);let moduleRegistry=new MutableModuleRegistry;for(let plugin of this.plugins){for(let m of plugin.modules?.()??[])moduleRegistry.mount(m);plugin.setup?.(moduleRegistry)}for(let m of this.options.modules)moduleRegistry.mount(m);this.options.setup?.(moduleRegistry);let modules=moduleRegistry.entries.map(entry=>{let mod=typeof entry==`function`?new entry:entry;return mod.register?.(this.container),mod});this.container.bootstrap(),this.container.has(Logger)||this.container.registerInstance(Logger,new Logger),this.mountMiddlewareList(adapterMw.beforeRoutes);let apiPrefix=this.options.apiPrefix??`/api`,defaultVersion=this.options.defaultVersion??1,shouldLogRoutes=this.options.logRouteTable??this.options.logRoutesTable??!1,mountedRoutes=[],adapterSources=[];for(let adapter of this.adapters){let adapterContribs=adapter.contributors?.()??[],adapterLabel=adapter.name??adapter.constructor.name??`adapter`;for(let registration of adapterContribs)adapterSources.push({source:`adapter`,registration,label:adapterLabel})}for(let plugin of this.plugins){let pluginContribs=plugin.contributors?.()??[],pluginLabel=plugin.name??plugin.constructor?.name??`plugin`;for(let registration of pluginContribs)adapterSources.push({source:`adapter`,registration,label:pluginLabel})}let globalSources=(this.options.contributors??[]).map(registration=>({source:`global`,registration,label:`bootstrap`}));this._moduleContributors=[];for(let mod of modules){let declaredName=mod.name,ctorName=mod.constructor?.name,moduleLabel=typeof declaredName==`string`&&declaredName.length>0?declaredName:ctorName&&ctorName!==`Object`?ctorName:`module`,moduleSources=(mod.contributors?.()??[]).map(registration=>({source:`module`,registration,label:moduleLabel}));for(let src of moduleSources)this._moduleContributors.push({registration:src.registration,label:moduleLabel});_setExternalContributorSources([...moduleSources,...adapterSources,...globalSources]);try{let result=mod.routes();if(!result)continue;let routeSets=Array.isArray(result)?result:[result];for(let route of routeSets){let mountPath=`${apiPrefix}/v${route.version??defaultVersion}${normalizePath(route.path)}`,router=route.router??buildRoutes(route.controller);if(!router)throw moduleRouteMissingControllerError(mountPath);if(this.app.use(mountPath,router),route.controller){for(let adapter of this.adapters)try{adapter.onRouteMount?.(route.controller,mountPath)}catch(err){log.error(err,`adapter.onRouteMount() failed for ${mountPath}`)}shouldLogRoutes&&mountedRoutes.push({controller:route.controller,mountPath})}}}finally{_setExternalContributorSources([])}}if(shouldLogRoutes&&mountedRoutes.length>0){let methodOrder=[`GET`,`POST`,`PUT`,`PATCH`,`DELETE`,`HEAD`,`OPTIONS`],methodRank=m=>{let i=methodOrder.indexOf(m);return i===-1?99:i},totalRoutes=0;log.info(`Routes:`);for(let{controller,mountPath}of mountedRoutes){let defs=getClassMeta(METADATA.ROUTES,controller,[]);if(defs.length===0)continue;let counts={};for(let def of defs){let m=def.method.toUpperCase();counts[m]=(counts[m]||0)+1}totalRoutes+=defs.length;let methods=Object.entries(counts).toSorted(([a],[b])=>methodRank(a)-methodRank(b)).map(([m,n])=>`${n} ${m}`).join(`, `),name=controller.name||`Controller`;log.info(`  ${name.padEnd(30)} ${mountPath.padEnd(25)} ${defs.length} routes (${methods})`)}log.info(`  Total: ${totalRoutes} routes`)}this.mountMiddlewareList(adapterMw.afterRoutes);for(let adapter of this.adapters)await this.callHook(adapter.beforeStart?.bind(adapter),ctx);this.app.use(this.options.onNotFound??notFoundHandler()),this.app.use(this.options.onError??errorHandler())}async registerOnly(){await this.setup()}async start(){await this.setup();let g=globalThis;if(g.__kickjs_httpServer){this.httpServer=g.__kickjs_httpServer,log.debug(`Attached to Vite dev server`),g.__kickjs_app_shutdown=()=>this.shutdown();for(let adapter of this.adapters){let ctx=this.adapterCtx(this.httpServer);await this.callHook(adapter.afterStart?.bind(adapter),ctx)}for(let plugin of this.plugins)await plugin.onReady?.(this.container);return}let port=this.options.port??parseInt(process.env.PORT||`3000`,10);this.httpServer=http.createServer(this.app),this.httpServer.on(`error`,err=>{throw err.code===`EADDRINUSE`&&(log.error(`Port ${port} is already in use. Kill the existing process or use a different port:\n  PORT=${port+1} kick dev\n  lsof -i :${port}   # find what's using it\n  kill <PID>          # stop it`),process.exit(1)),err}),await new Promise((resolve,reject)=>{this.httpServer.listen(port,async()=>{try{log.info(`Server running on http://localhost:${port}`);for(let adapter of this.adapters){let afterCtx=this.adapterCtx(this.httpServer);await this.callHook(adapter.afterStart?.bind(adapter),afterCtx)}for(let plugin of this.plugins)await plugin.onReady?.(this.container);resolve()}catch(err){reject(err)}})})}async rebuild(){let prevApp=this.app,prevContainer=this.container;try{Container.reset(),this.container=Container.getInstance(),this.app=express(),await this.setup()}catch(err){log.error(err,`HMR rebuild failed, keeping previous app`),this.app=prevApp,this.container=prevContainer;return}this.httpServer&&(this.httpServer.removeAllListeners(`request`),this.httpServer.on(`request`,this.app),log.debug(`HMR: Express app rebuilt and swapped`))}async shutdown(){if(this._shutdownInitiated){log.debug(`Shutdown already in progress, skipping duplicate call`);return}this._shutdownInitiated=!0,this._draining=!0,log.debug(`Shutting down — draining in-flight requests...`);let timeoutMs=this.options.shutdownTimeout??3e4,timer,forceExitPromise=timeoutMs>0?new Promise(resolve=>{timer=setTimeout(()=>resolve(`timeout`),timeoutMs),timer.unref()}):new Promise(()=>{});try{if(this.httpServer&&this.httpServer.close(()=>{}),this._inFlightRequests>0){log.debug(`Waiting for ${this._inFlightRequests} in-flight request(s) to complete...`);let drainPromise=new Promise(resolve=>{this._drainResolvers.push(()=>resolve(`drained`))});await Promise.race([drainPromise,forceExitPromise])===`timeout`?log.warn(`Shutdown timeout (${timeoutMs}ms) reached with ${this._inFlightRequests} request(s) still in-flight, forcing shutdown`):log.debug(`All in-flight requests completed`)}let results=await Promise.allSettled([...this.plugins.map(plugin=>Promise.resolve(plugin.shutdown?.())),...this.adapters.map(adapter=>Promise.resolve(adapter.shutdown?.()))]);for(let result of results)result.status===`rejected`&&log.error({err:result.reason},`Adapter shutdown failed`)}finally{timer&&clearTimeout(timer)}}getExpressApp(){return this.app}getAdapters(){return this.adapters}getPlugins(){return this.plugins}getContributors(){let out=[],ingest=(list,source,label)=>{if(list)for(let reg of list){let r=reg;if(r.key===void 0||r.key===null)continue;let key=typeof r.key==`string`?r.key:tokenName(r.key);out.push({key,source,label,dependsOn:Array.isArray(r.dependsOn)?r.dependsOn:[]})}};for(let adapter of this.adapters)ingest(adapter.contributors?.(),`adapter`,adapter.name??`adapter`);for(let plugin of this.plugins)ingest(plugin.contributors?.(),`plugin`,plugin.name??`plugin`);for(let{registration,label}of this._moduleContributors)ingest([registration],`module`,label);return ingest(this.options.contributors,`global`,`bootstrap`),out}getHttpServer(){return this.httpServer}shouldAutoMountRequestScope(){if(this.options.contextStore===`manual`)return!1;let userEntries=this.options.middlewares??this.options.middleware??[];for(let entry of userEntries)if(isRequestScopeMiddleware(typeof entry==`function`?entry:entry.handler))return!1;return!0}collectAdapterMiddleware(){let result={beforeGlobal:[],afterGlobal:[],beforeRoutes:[],afterRoutes:[]};for(let adapter of this.adapters){let entries=adapter.middleware?.()??[];for(let entry of entries)result[entry.phase??`afterGlobal`].push(entry)}return result}mountMiddlewareList(entries){for(let entry of entries){if(entry.path===void 0){this.app.use(entry.handler);continue}let path=Array.isArray(entry.path)?[...entry.path]:entry.path;this.app.use(path,entry.handler)}}mountMiddlewareEntry(entry){typeof entry==`function`?this.app.use(entry):this.app.use(entry.path,entry.handler)}requestTrackingMiddleware(){return(_req,res,next)=>{this._inFlightRequests++;let onFinish=()=>{if(res.removeListener(`finish`,onFinish),res.removeListener(`close`,onFinish),this._inFlightRequests--,this._draining&&this._inFlightRequests===0){for(let resolve of this._drainResolvers)resolve();this._drainResolvers=[]}};res.on(`finish`,onFinish),res.on(`close`,onFinish),next()}}mountHealthEndpoints(){this.app.get(`/health/live`,(_req,res)=>{this._draining?res.status(503).json({status:`draining`,uptime:process.uptime()}):res.json({status:`ok`,uptime:process.uptime()})}),this.app.get(`/health/ready`,async(_req,res)=>{if(this._draining){res.status(503).json({status:`draining`,checks:[]});return}let adaptersWithHealth=this.adapters.filter(a=>a.onHealthCheck),results=(await Promise.allSettled(adaptersWithHealth.map(a=>a.onHealthCheck()))).map((c,i)=>c.status===`fulfilled`?c.value:{name:adaptersWithHealth[i].name??`unknown`,status:`down`}),healthy=results.every(r=>r.status===`up`);res.status(healthy?200:503).json({status:healthy?`ready`:`degraded`,checks:results})})}};export{requestScopeMiddleware as n,Application as t};
-//# sourceMappingURL=application-DnnqoDWx.mjs.map