@forinda/kickjs 5.6.0 → 5.7.0

package/dist/{context-CbX_T0XC.mjs.map → context-CvJQzbBF.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"context-CbX_T0XC.mjs","names":[],"sources":["../src/http/request-store.ts","../src/http/context.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\nimport type { MetaValue } from '../core/execution-context'\n\n/** Per-request storage for REQUEST-scoped DI and request context propagation */\nexport interface RequestStore {\n  /** Unique request identifier */\n  requestId: string\n  /**\n   * Per-request singleton cache for REQUEST-scoped services. Keys are\n   * heterogeneous (class constructors, `InjectionToken` objects, raw\n   * strings), so the map type stays `Map<any, any>`.\n   */\n  instances: Map<any, any>\n  /**\n   * Per-request key/value bag. Canonical backing store for\n   * `RequestContext.set/get` and the Context Contributor pipeline (#107)\n   * since Phase 3. Anything written here is visible to every concrete\n   * execution context constructed for the same request, regardless of\n   * which middleware/contributor wrote it.\n   *\n   * Keys are constrained to `string` per the locked decision in\n   * `architecture.md` §20.12 (#4); the value type is `unknown` because\n   * the concrete shape at each key is determined by the consumer's\n   * `ContextMeta` augmentation, not by the store itself.\n   *\n   * Prefer the {@link getRequestValue} helper over reaching into this\n   * map directly — it threads the augmented `ContextMeta` shape through\n   * `MetaValue<K>` so consumers get typed reads without an `as` cast.\n   * Writes should flow through `ctx.set(key, value)` or a Context\n   * Contributor's return value — see the `setRequestValue` note below\n   * for why this package intentionally does NOT ship a service-level\n   * write helper.\n   */\n  values: Map<string, unknown>\n}\n\n/** AsyncLocalStorage instance shared across the framework */\nexport const requestStore = new AsyncLocalStorage<RequestStore>()\n\n/**\n * Get the current request store. Throws if called outside a request context.\n * Used by the Container to resolve REQUEST-scoped dependencies.\n */\nexport function getRequestStore(): RequestStore {\n  const store = requestStore.getStore()\n  if (!store) {\n    throw new Error(\n      'No active request context. REQUEST-scoped services can only be resolved during an HTTP request.',\n    )\n  }\n  return store\n}\n\n/**\n * Read a per-request `ContextMeta`-keyed value from outside a controller\n * (services, repositories, anywhere with no `ctx` reference). Returns\n * the augmented type for the key — `MetaValue<K>` — so consumers get the\n * same static safety as `ctx.get(key)` without holding the context.\n *\n * Returns `undefined` outside an active request frame (background jobs,\n * startup code, tests without `requestScopeMiddleware()`) — the helper\n * is intentionally null-tolerant so calling it from a service that\n * runs in both request and non-request paths doesn't throw.\n *\n * @example\n * ```ts\n * declare module '@forinda/kickjs' {\n *   interface ContextMeta { tenant: { id: string; name: string } }\n * }\n *\n * @Service()\n * class AuditService {\n *   log(action: string) {\n *     const tenant = getRequestValue('tenant')  // typed: { id; name } | undefined\n *     db.audit.insert({ action, tenantId: tenant?.id })\n *   }\n * }\n * ```\n */\nexport function getRequestValue<K extends string>(key: K): MetaValue<K> | undefined {\n  return requestStore.getStore()?.values.get(key) as MetaValue<K> | undefined\n}\n\n// Intentionally NO `setRequestValue` export.\n//\n// Writes are deliberately context-scoped — only the controlled write\n// surfaces should mutate the per-request Map:\n//\n//   1. A Context Contributor's `resolve()` / `onError()` return value\n//      (the runner does `ctx.set(reg.key, value)` on the contributor's\n//      behalf). This is the canonical way to populate a key.\n//   2. A controller / middleware / contributor that holds a\n//      `RequestContext` instance can call `ctx.set(key, value)`\n//      directly. The write is auditable inline at the call site.\n//\n// Letting arbitrary services reach in and mutate the store from\n// anywhere produces \"spooky action at a distance\" — keys appear in\n// the request bag without an obvious source, and tracing which\n// service polluted what becomes a grep exercise. Services that need\n// to publish per-request state should return the value to the caller\n// (controller or contributor) and let *that* layer write it via\n// `ctx.set`. If a future need genuinely requires a service-level\n// write surface, expose a narrow function (`recordTrace`,\n// `markStartTime`) on a service that captures the side effect, not a\n// generic `setRequestValue`.\n","/// <reference types=\"multer\" />\nimport type { Request, Response, NextFunction } from 'express'\nimport { type ContextMeta, type ExecutionContext, type MetaValue } from '../core/execution-context'\nimport { requestStore } from './request-store'\nimport {\n  parseQuery,\n  type QueryFieldConfig,\n  type PaginatedResponse,\n  type TypedParsedQuery,\n} from './query'\n\n/**\n * Recursively marks every property of `T` as `readonly`. Preserves\n * `Function`, `Date`, and `RegExp` unchanged, and converts `Map` / `Set`\n * to `ReadonlyMap` / `ReadonlySet` so their mutating methods (`set`,\n * `delete`, `add`, `clear`) are removed from the public surface.\n * Tuples keep their positional element types — only their per-element\n * mutability is locked.\n *\n * Used to seal typed request data (`body`, `params`, `query`) so\n * adopters can't mutate Zod-validated payloads in place — the contract\n * is \"compute new values, stash via `ctx.set`\", not \"edit the request\n * bag\".\n *\n * Type-only. No runtime cost. `DeepReadonly<any>` is `any` (TS\n * distributes conditional types over `any`), so adopters who haven't\n * typed their `Ctx` get no protection but no breakage either.\n */\nexport type DeepReadonly<T> = T extends (...args: never[]) => unknown\n  ? T\n  : T extends Date | RegExp\n    ? T\n    : T extends Map<infer K, infer V>\n      ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>\n      : T extends Set<infer V>\n        ? ReadonlySet<DeepReadonly<V>>\n        : T extends readonly (infer U)[]\n          ? // Distinguish a regular array from a tuple. A regular `T[]` widens\n            // its `length` to `number`; a tuple's `length` is a literal\n            // (e.g. `2`). The literal branch maps over `keyof T` so each\n            // positional slot keeps its own type — `DeepReadonly<[1, 2]>` →\n            // `readonly [1, 2]`, not `readonly (1 | 2)[]`.\n            number extends T['length']\n            ? ReadonlyArray<DeepReadonly<U>>\n            : { readonly [K in keyof T]: DeepReadonly<T[K]> }\n          : T extends object\n            ? { readonly [K in keyof T]: DeepReadonly<T[K]> }\n            : T\n\n/**\n * Re-export the augmentable {@link ContextMeta} registry from core/.\n * Declared in `core/execution-context.ts` so non-HTTP transports\n * (WS/queue/cron, V2) share one declaration site. Apps still augment\n * via the canonical `declare module '@forinda/kickjs'` form.\n */\nexport type { ContextMeta } from '../core/execution-context'\n\n/**\n * Symbol key under which the per-request `AbortController` backing\n * `RequestContext.signal` is cached on the Express `req` object.\n * Shared across every `RequestContext` instance built for the same\n * request (router-builder constructs separate wrappers for\n * middleware, the contributor pipeline, and the main handler — they\n * all need the same signal).\n */\nconst signalControllerKey = Symbol.for('kickjs.requestContext.signalController')\n\n/**\n * The shape of a single route entry in `KickRoutes`. Generated by\n * `kick typegen` and consumed via the `Ctx<T>` helper. Each field is\n * `unknown` by default and is filled in as the typegen learns more\n * about the route (URL params from the path, body/query from validation\n * schemas, etc.).\n */\nexport interface RouteShape {\n  params?: unknown\n  body?: unknown\n  query?: unknown\n  response?: unknown\n}\n\n/**\n * Unified request/response abstraction passed to every controller method.\n * Shields handlers from raw Express objects and provides convenience methods.\n *\n * Implements {@link ExecutionContext} so the transport-agnostic Context\n * Contributor pipeline (#107) can run against this concrete HTTP context\n * the same way it will run against future WS / queue / cron contexts.\n */\nexport class RequestContext<TBody = any, TParams = any, TQuery = any> implements ExecutionContext {\n  constructor(\n    public readonly req: Request,\n    public readonly res: Response,\n    public readonly next: NextFunction,\n  ) {}\n\n  /**\n   * Read-side accessor for the per-request metadata map.\n   *\n   * Returns the AsyncLocalStorage map (`requestStore.getStore().values`)\n   * shared with the Context Contributor pipeline when an ALS frame is\n   * active. Returns `null` outside any frame — read-side callers\n   * (`ctx.get`, `ctx.user`, `ctx.tenantId`, `ctx.roles`) treat that as\n   * \"no metadata\" and fall through to their `req.*` defaults. Reads\n   * never throw because outside an ALS frame nobody could have written\n   * via `ctx.set` anyway, so an empty answer is the truthful one.\n   */\n  private metadataReadOnly(): Map<string, any> | null {\n    return (requestStore.getStore()?.values as Map<string, any> | undefined) ?? null\n  }\n\n  /**\n   * Write-side accessor for the per-request metadata map.\n   *\n   * Returns the same map as {@link metadataReadOnly} when an ALS frame\n   * is active. Throws otherwise — writing to a fallback map outside\n   * the ALS frame would silently lose data because other call sites\n   * (downstream contributors, request-logger, etc.) read from the\n   * canonical store and would never see it. Mount\n   * `requestScopeMiddleware()` (Application does this for you in\n   * `'auto'` mode) or wrap your test setup in\n   * `requestStore.run({...}, () => …)` to fix.\n   */\n  private metadataForWrite(): Map<string, any> {\n    const store = requestStore.getStore()\n    if (store) return store.values as Map<string, any>\n    throw new Error(\n      'RequestContext.set called outside an AsyncLocalStorage frame. ' +\n        'Mount requestScopeMiddleware() before constructing RequestContext, ' +\n        'or wrap test setup in requestStore.run({ requestId, instances: new Map(), values: new Map() }, () => ...).',\n    )\n  }\n\n  // ── Request Data ────────────────────────────────────────────────────\n\n  /**\n   * Parsed request body. Returned as `DeepReadonly<TBody>` so adopters\n   * can't mutate Zod-validated payloads in place — compute new values\n   * and stash them via `ctx.set('key', value)` or a Context Contributor\n   * instead. Reach for `ctx.req.body` if you genuinely need the raw,\n   * mutable Express handle (rare).\n   */\n  get body(): DeepReadonly<TBody> {\n    return this.req.body as DeepReadonly<TBody>\n  }\n\n  /** Path parameters parsed from the route — read-only, see {@link body}. */\n  get params(): DeepReadonly<TParams> {\n    return this.req.params as DeepReadonly<TParams>\n  }\n\n  /** Parsed query string — read-only, see {@link body}. */\n  get query(): DeepReadonly<TQuery> {\n    return this.req.query as DeepReadonly<TQuery>\n  }\n\n  /** Inbound HTTP headers — read-only, see {@link body}. */\n  get headers(): Readonly<Request['headers']> {\n    return this.req.headers\n  }\n\n  get requestId(): string | undefined {\n    return (this.req as any).requestId ?? (this.req.headers['x-request-id'] as string | undefined)\n  }\n\n  /**\n   * `AbortSignal` that fires when the underlying HTTP request is\n   * closed — either because the client disconnected before the\n   * response was sent, or because Node's socket-close event ran\n   * after a normal response. Multiple `RequestContext` wrappers for\n   * the same request (router-builder constructs one per\n   * middleware/contributor pipeline / main handler) share a single\n   * `AbortController` cached on the underlying `req` object, so the\n   * signal is stable across the request lifecycle.\n   *\n   * Thread it through anything that takes an `AbortSignal` so the\n   * work cancels as soon as the client gives up — e.g. a kickjs-db\n   * relational query:\n   *\n   * ```ts\n   * @Get('/:id/full')\n   * async show(ctx: RequestContext) {\n   *   const row = await this.repo.findFullById(ctx.params.id, ctx.signal)\n   *   if (!row) return ctx.notFound()\n   *   ctx.json(row)\n   * }\n   * ```\n   *\n   * The repo passes `signal` to `db.query.<table>.findUnique({ signal })`;\n   * if the client disconnects mid-flight, the in-flight query rejects\n   * with `RelationalQueryCancelledError` instead of consuming the\n   * connection until completion.\n   *\n   * Implementation note — both `req.on('close')` and `res.on('close')`\n   * are wired so the signal aborts regardless of whether the close\n   * event lands on the request stream or the response stream first.\n   * Subsequent fires are no-ops (`AbortController.abort()` is\n   * idempotent).\n   */\n  get signal(): AbortSignal {\n    const req = this.req as Request & { [signalControllerKey]?: AbortController }\n    const cached = req[signalControllerKey]\n    if (cached) return cached.signal\n\n    const ctrl = new AbortController()\n    req[signalControllerKey] = ctrl\n    const abort = () => ctrl.abort('request closed')\n    this.req.once('close', abort)\n    this.res.once('close', abort)\n    return ctrl.signal\n  }\n\n  /** Session data (requires session middleware) */\n  get session(): any {\n    return (this.req as any).session\n  }\n\n  /**\n   * The authenticated user set by AuthAdapter.\n   * Reads from the per-request metadata store first (`ctx.set('user', ...)`),\n   * then falls back to `req.user` (set directly by AuthAdapter middleware).\n   *\n   * Extend the `AuthUser` interface via module augmentation in `@forinda/kickjs-auth`\n   * to get full typing.\n   *\n   * @example\n   * ```ts\n   * @Get('/me')\n   * @Authenticated()\n   * getProfile(ctx: RequestContext) {\n   *   const user = ctx.user\n   *   if (!user) return ctx.notFound()\n   *   return ctx.json({ user })\n   * }\n   * ```\n   */\n  get user(): MetaValue<'user', Record<string, any>> | undefined {\n    return this.metadataReadOnly()?.get('user') ?? (this.req as any).user\n  }\n\n  /**\n   * Tenant identifier for multi-tenant apps. Reads `user.tenantId` —\n   * populated either by `AuthAdapter.testMode({ tenantId })`, a tenant\n   * resolver middleware, or manually on the strategy's `mapPayload`.\n   *\n   * Augment `AuthUser` (or `ContextMeta['user']`) to widen the return\n   * type if your user shape guarantees a non-`string | undefined` id.\n   */\n  get tenantId(): string | undefined {\n    const u = this.user as Record<string, any> | undefined\n    return u?.tenantId\n  }\n\n  /**\n   * Effective role list for the current user. Prefers `user.tenantRoles`\n   * (populated by `AuthAdapterOptions.roleResolver` under a tenant) and\n   * falls back to `user.roles`. Returns an empty array when the user is\n   * absent or the shape has neither field.\n   */\n  get roles(): string[] {\n    const u = this.user as Record<string, any> | undefined\n    return u?.tenantRoles ?? u?.roles ?? []\n  }\n\n  // ── Query String Parsing ───────────────────────────────────────────\n\n  /**\n   * Parse the request query string into structured filters, sort, pagination, and search.\n   * Pass the result to an ORM query builder adapter (Drizzle, Prisma, Sequelize, etc.).\n   *\n   * Generic over the field config: when passed an inline literal (or\n   * `as const`), `filters[].field` and `sort[].field` are narrowed to\n   * the exact whitelisted field names. Pass nothing or a non-literal\n   * config and you get the loose `string` fallback.\n   *\n   * @param fieldConfig - Optional whitelist for filterable, sortable, and searchable fields\n   *\n   * @example\n   * ```ts\n   * @Get('/')\n   * async list(ctx: RequestContext) {\n   *   const parsed = ctx.qs({\n   *     filterable: ['status', 'priority'],\n   *     sortable: ['createdAt', 'title'],\n   *   } as const)\n   *   parsed.filters[0].field // typed as 'status' | 'priority'\n   *   parsed.sort[0].field    // typed as 'createdAt' | 'title'\n   * }\n   * ```\n   */\n  qs<TConfig extends QueryFieldConfig | undefined = undefined>(\n    fieldConfig?: TConfig,\n  ): TypedParsedQuery<TConfig> {\n    return parseQuery<TConfig>(this.req.query as Record<string, any>, fieldConfig)\n  }\n\n  // ── File Uploads ────────────────────────────────────────────────────\n\n  /**\n   * Single uploaded file (requires `@FileUpload({ mode: 'single' })`).\n   * Returned as `DeepReadonly<Express.Multer.File>` — file metadata is\n   * set by the upload middleware and shouldn't be mutated downstream.\n   */\n  get file(): DeepReadonly<Express.Multer.File> | undefined {\n    return this.req.file\n  }\n\n  /**\n   * Array of uploaded files (requires `@FileUpload({ mode: 'array' })`).\n   * Returns a `ReadonlyArray<DeepReadonly<Express.Multer.File>>` — both\n   * the list (`push`/`pop`) and each file's fields (`size`, `originalname`,\n   * etc.) are locked. Use `ctx.req.files` if you genuinely need the\n   * mutable Express handle.\n   */\n  get files(): ReadonlyArray<DeepReadonly<Express.Multer.File>> | undefined {\n    // multer's `Request['files']` is a union — array (mode: 'array' /\n    // 'any') or `{ [fieldname]: File[] }` (mode: 'fields'). The\n    // `@FileUpload({ mode: 'array' })` decorator only sets the array\n    // shape, but `Request['files']` is the broad union. Narrow back to\n    // `File[]` here for the common-case getter; adopters using\n    // `mode: 'fields'` can read `ctx.req.files` directly for the\n    // dictionary shape.\n    const f = this.req.files\n    return Array.isArray(f) ? f : undefined\n  }\n\n  // ── Metadata Store ──────────────────────────────────────────────────\n\n  /**\n   * Read a value from the per-request metadata store.\n   *\n   * When `ContextMeta` has been augmented with a matching key, the return\n   * type is inferred automatically. For ad-hoc keys, pass a generic:\n   * `ctx.get<MyType>('custom')`.\n   */\n  get<K extends string>(key: K): MetaValue<K> | undefined {\n    return this.metadataReadOnly()?.get(key) as MetaValue<K> | undefined\n  }\n\n  /**\n   * Write a value to the per-request metadata store. Throws when no\n   * AsyncLocalStorage frame is active — see {@link metadataForWrite}\n   * for why a silent fallback is the wrong default.\n   */\n  set<K extends string>(key: K, value: MetaValue<K>): void {\n    this.metadataForWrite().set(key, value)\n  }\n\n  // ── Response Helpers ────────────────────────────────────────────────\n\n  json(data: any, status = 200) {\n    return this.res.status(status).json(data)\n  }\n\n  created(data: any) {\n    return this.res.status(201).json(data)\n  }\n\n  noContent() {\n    return this.res.status(204).end()\n  }\n\n  notFound(message = 'Not Found') {\n    return this.res.status(404).json({ message })\n  }\n\n  badRequest(message: string) {\n    return this.res.status(400).json({ message })\n  }\n\n  html(content: string, status = 200) {\n    return this.res.status(status).type('html').send(content)\n  }\n\n  download(buffer: Buffer, filename: string, contentType = 'application/octet-stream') {\n    this.res.setHeader('Content-Disposition', `attachment; filename=\"${filename}\"`)\n    this.res.setHeader('Content-Type', contentType)\n    return this.res.send(buffer)\n  }\n\n  /**\n   * Render a template using the registered view engine (EJS, Pug, Handlebars, etc.).\n   * Requires a ViewAdapter to be configured in bootstrap().\n   *\n   * @param template - Template name (without extension, relative to viewsDir)\n   * @param data - Data to pass to the template\n   *\n   * @example\n   * ```ts\n   * ctx.render('dashboard', { user, title: 'Dashboard' })\n   * ctx.render('emails/welcome', { name: 'Alice' })\n   * ```\n   */\n  render(template: string, data: Record<string, any> = {}) {\n    return this.res.render(template, data)\n  }\n\n  /**\n   * Parse query params and return a standardized paginated response.\n   * Calls `ctx.qs()` internally, then wraps your data with pagination meta.\n   *\n   * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`\n   * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields\n   *\n   * @example\n   * ```ts\n   * @Get('/')\n   * async list(ctx: RequestContext) {\n   *   return ctx.paginate(\n   *     async (parsed) => {\n   *       const data = await db.select().from(users)\n   *         .where(query.where).limit(parsed.pagination.limit)\n   *         .offset(parsed.pagination.offset).all()\n   *       const total = await db.select({ count: count() }).from(users).get()\n   *       return { data, total: total?.count ?? 0 }\n   *     },\n   *     { filterable: ['name', 'role'], sortable: ['createdAt'] },\n   *   )\n   * }\n   * ```\n   */\n  async paginate<T, TConfig extends QueryFieldConfig | undefined = undefined>(\n    fetcher: (parsed: TypedParsedQuery<TConfig>) => Promise<{ data: T[]; total: number }>,\n    fieldConfig?: TConfig,\n  ) {\n    const parsed = this.qs<TConfig>(fieldConfig)\n    const { data, total } = await fetcher(parsed)\n    const { page, limit } = parsed.pagination\n    const totalPages = Math.ceil(total / limit) || 1\n\n    const response: PaginatedResponse<T> = {\n      data,\n      meta: {\n        page,\n        limit,\n        total,\n        totalPages,\n        hasNext: page < totalPages,\n        hasPrev: page > 1,\n      },\n    }\n\n    return this.json(response)\n  }\n\n  // ── Server-Sent Events ──────────────────────────────────────────────\n\n  /**\n   * Start an SSE (Server-Sent Events) stream.\n   * Sets the correct headers and returns helpers to send events.\n   *\n   * @example\n   * ```ts\n   * @Get('/events')\n   * async stream(ctx: RequestContext) {\n   *   const sse = ctx.sse()\n   *\n   *   const interval = setInterval(() => {\n   *     sse.send({ time: new Date().toISOString() }, 'tick')\n   *   }, 1000)\n   *\n   *   sse.onClose(() => clearInterval(interval))\n   * }\n   * ```\n   */\n  sse() {\n    this.res.writeHead(200, {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n      'X-Accel-Buffering': 'no',\n    })\n    this.res.flushHeaders()\n\n    const closeCallbacks: Array<() => void> = []\n\n    this.req.on('close', () => {\n      for (const cb of closeCallbacks) cb()\n    })\n\n    return {\n      /** Send an SSE event with optional event name and id */\n      send: (data: any, event?: string, id?: string) => {\n        if (id) this.res.write(`id: ${id}\\n`)\n        if (event) this.res.write(`event: ${event}\\n`)\n        this.res.write(`data: ${JSON.stringify(data)}\\n\\n`)\n      },\n      /** Send a comment (keeps connection alive) */\n      comment: (text: string) => {\n        this.res.write(`: ${text}\\n\\n`)\n      },\n      /** Register a callback when the client disconnects */\n      onClose: (fn: () => void) => {\n        closeCallbacks.push(fn)\n      },\n      /** End the SSE stream */\n      close: () => {\n        this.res.end()\n      },\n    }\n  }\n}\n\n/**\n * Short alias for `RequestContext` parameterised by a route shape.\n *\n * Use with `kick typegen`'s generated `KickRoutes` namespace for\n * fully-typed `ctx.params`, `ctx.body`, and `ctx.query`. Metadata\n * typing (`ctx.get()`, `ctx.set()`, `ctx.user`) comes from\n * `ContextMeta` augmentation and works on all `RequestContext` instances.\n *\n * @example\n * ```ts\n * @Get('/:id')\n * getUser(ctx: Ctx<KickRoutes.UserController['getUser']>) {\n *   ctx.params.id      // typed from RouteShape\n *   ctx.body           // typed from RouteShape\n *   ctx.user           // typed from ContextMeta\n *   ctx.get('tenant')  // typed from ContextMeta\n * }\n * ```\n */\nexport type Ctx<TRoute extends RouteShape = RouteShape> = RequestContext<\n  TRoute extends { body: infer B } ? B : any,\n  TRoute extends { params: infer P } ? P : any,\n  TRoute extends { query: infer Q } ? Q : any\n>\n\n/**\n * Global ambient registry of typed routes, populated by `kick typegen`.\n *\n * Each interface inside `KickRoutes` corresponds to a controller class;\n * each property is one route method on that controller. The values\n * conform to `RouteShape`.\n *\n * Empty by default — declarations come from `.kickjs/types/routes.d.ts`\n * generated alongside the rest of the typegen output.\n */\ndeclare global {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace KickRoutes {}\n}\n"],"mappings":"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"}
+{"version":3,"file":"context-CvJQzbBF.mjs","names":[],"sources":["../src/http/request-store.ts","../src/http/context.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\nimport type { MetaValue } from '../core/execution-context'\n\n/** Per-request storage for REQUEST-scoped DI and request context propagation */\nexport interface RequestStore {\n  /** Unique request identifier */\n  requestId: string\n  /**\n   * Per-request singleton cache for REQUEST-scoped services. Keys are\n   * heterogeneous (class constructors, `InjectionToken` objects, raw\n   * strings), so the map type stays `Map<any, any>`.\n   */\n  instances: Map<any, any>\n  /**\n   * Per-request key/value bag. Canonical backing store for\n   * `RequestContext.set/get` and the Context Contributor pipeline (#107)\n   * since Phase 3. Anything written here is visible to every concrete\n   * execution context constructed for the same request, regardless of\n   * which middleware/contributor wrote it.\n   *\n   * Keys are constrained to `string` per the locked decision in\n   * `architecture.md` §20.12 (#4); the value type is `unknown` because\n   * the concrete shape at each key is determined by the consumer's\n   * `ContextMeta` augmentation, not by the store itself.\n   *\n   * Prefer the {@link getRequestValue} helper over reaching into this\n   * map directly — it threads the augmented `ContextMeta` shape through\n   * `MetaValue<K>` so consumers get typed reads without an `as` cast.\n   * Writes should flow through `ctx.set(key, value)` or a Context\n   * Contributor's return value — see the `setRequestValue` note below\n   * for why this package intentionally does NOT ship a service-level\n   * write helper.\n   */\n  values: Map<string, unknown>\n}\n\n/** AsyncLocalStorage instance shared across the framework */\nexport const requestStore = new AsyncLocalStorage<RequestStore>()\n\n/**\n * Get the current request store. Throws if called outside a request context.\n * Used by the Container to resolve REQUEST-scoped dependencies.\n */\nexport function getRequestStore(): RequestStore {\n  const store = requestStore.getStore()\n  if (!store) {\n    throw new Error(\n      'No active request context. REQUEST-scoped services can only be resolved during an HTTP request.',\n    )\n  }\n  return store\n}\n\n/**\n * Read a per-request `ContextMeta`-keyed value from outside a controller\n * (services, repositories, anywhere with no `ctx` reference). Returns\n * the augmented type for the key — `MetaValue<K>` — so consumers get the\n * same static safety as `ctx.get(key)` without holding the context.\n *\n * Returns `undefined` outside an active request frame (background jobs,\n * startup code, tests without `requestScopeMiddleware()`) — the helper\n * is intentionally null-tolerant so calling it from a service that\n * runs in both request and non-request paths doesn't throw.\n *\n * @example\n * ```ts\n * declare module '@forinda/kickjs' {\n *   interface ContextMeta { tenant: { id: string; name: string } }\n * }\n *\n * @Service()\n * class AuditService {\n *   log(action: string) {\n *     const tenant = getRequestValue('tenant')  // typed: { id; name } | undefined\n *     db.audit.insert({ action, tenantId: tenant?.id })\n *   }\n * }\n * ```\n */\nexport function getRequestValue<K extends string>(key: K): MetaValue<K> | undefined {\n  return requestStore.getStore()?.values.get(key) as MetaValue<K> | undefined\n}\n\n// Intentionally NO `setRequestValue` export.\n//\n// Writes are deliberately context-scoped — only the controlled write\n// surfaces should mutate the per-request Map:\n//\n//   1. A Context Contributor's `resolve()` / `onError()` return value\n//      (the runner does `ctx.set(reg.key, value)` on the contributor's\n//      behalf). This is the canonical way to populate a key.\n//   2. A controller / middleware / contributor that holds a\n//      `RequestContext` instance can call `ctx.set(key, value)`\n//      directly. The write is auditable inline at the call site.\n//\n// Letting arbitrary services reach in and mutate the store from\n// anywhere produces \"spooky action at a distance\" — keys appear in\n// the request bag without an obvious source, and tracing which\n// service polluted what becomes a grep exercise. Services that need\n// to publish per-request state should return the value to the caller\n// (controller or contributor) and let *that* layer write it via\n// `ctx.set`. If a future need genuinely requires a service-level\n// write surface, expose a narrow function (`recordTrace`,\n// `markStartTime`) on a service that captures the side effect, not a\n// generic `setRequestValue`.\n","/// <reference types=\"multer\" />\nimport type { Request, Response, NextFunction } from 'express'\nimport { type ContextMeta, type ExecutionContext, type MetaValue } from '../core/execution-context'\nimport { requestStore } from './request-store'\nimport {\n  parseQuery,\n  type QueryFieldConfig,\n  type PaginatedResponse,\n  type TypedParsedQuery,\n} from './query'\n\n/**\n * Recursively marks every property of `T` as `readonly`. Preserves\n * `Function`, `Date`, and `RegExp` unchanged, and converts `Map` / `Set`\n * to `ReadonlyMap` / `ReadonlySet` so their mutating methods (`set`,\n * `delete`, `add`, `clear`) are removed from the public surface.\n * Tuples keep their positional element types — only their per-element\n * mutability is locked.\n *\n * Used to seal typed request data (`body`, `params`, `query`) so\n * adopters can't mutate Zod-validated payloads in place — the contract\n * is \"compute new values, stash via `ctx.set`\", not \"edit the request\n * bag\".\n *\n * Type-only. No runtime cost. `DeepReadonly<any>` is `any` (TS\n * distributes conditional types over `any`), so adopters who haven't\n * typed their `Ctx` get no protection but no breakage either.\n */\nexport type DeepReadonly<T> = T extends (...args: never[]) => unknown\n  ? T\n  : T extends Date | RegExp\n    ? T\n    : T extends Map<infer K, infer V>\n      ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>\n      : T extends Set<infer V>\n        ? ReadonlySet<DeepReadonly<V>>\n        : T extends readonly (infer U)[]\n          ? // Distinguish a regular array from a tuple. A regular `T[]` widens\n            // its `length` to `number`; a tuple's `length` is a literal\n            // (e.g. `2`). The literal branch maps over `keyof T` so each\n            // positional slot keeps its own type — `DeepReadonly<[1, 2]>` →\n            // `readonly [1, 2]`, not `readonly (1 | 2)[]`.\n            number extends T['length']\n            ? ReadonlyArray<DeepReadonly<U>>\n            : { readonly [K in keyof T]: DeepReadonly<T[K]> }\n          : T extends object\n            ? { readonly [K in keyof T]: DeepReadonly<T[K]> }\n            : T\n\n/**\n * Re-export the augmentable {@link ContextMeta} registry from core/.\n * Declared in `core/execution-context.ts` so non-HTTP transports\n * (WS/queue/cron, V2) share one declaration site. Apps still augment\n * via the canonical `declare module '@forinda/kickjs'` form.\n */\nexport type { ContextMeta } from '../core/execution-context'\n\n/**\n * Symbol key under which the per-request `AbortController` backing\n * `RequestContext.signal` is cached on the Express `req` object.\n * Shared across every `RequestContext` instance built for the same\n * request (router-builder constructs separate wrappers for\n * middleware, the contributor pipeline, and the main handler — they\n * all need the same signal).\n */\nconst signalControllerKey = Symbol.for('kickjs.requestContext.signalController')\n\n/**\n * The shape of a single route entry in `KickRoutes`. Generated by\n * `kick typegen` and consumed via the `Ctx<T>` helper. Each field is\n * `unknown` by default and is filled in as the typegen learns more\n * about the route (URL params from the path, body/query from validation\n * schemas, etc.).\n */\nexport interface RouteShape {\n  params?: unknown\n  body?: unknown\n  query?: unknown\n  response?: unknown\n}\n\n/**\n * Unified request/response abstraction passed to every controller method.\n * Shields handlers from raw Express objects and provides convenience methods.\n *\n * Implements {@link ExecutionContext} so the transport-agnostic Context\n * Contributor pipeline (#107) can run against this concrete HTTP context\n * the same way it will run against future WS / queue / cron contexts.\n */\nexport class RequestContext<TBody = any, TParams = any, TQuery = any> implements ExecutionContext {\n  constructor(\n    public readonly req: Request,\n    public readonly res: Response,\n    public readonly next: NextFunction,\n  ) {}\n\n  /**\n   * Read-side accessor for the per-request metadata map.\n   *\n   * Returns the AsyncLocalStorage map (`requestStore.getStore().values`)\n   * shared with the Context Contributor pipeline when an ALS frame is\n   * active. Returns `null` outside any frame — read-side callers\n   * (`ctx.get`, `ctx.user`, `ctx.tenantId`, `ctx.roles`) treat that as\n   * \"no metadata\" and fall through to their `req.*` defaults. Reads\n   * never throw because outside an ALS frame nobody could have written\n   * via `ctx.set` anyway, so an empty answer is the truthful one.\n   */\n  private metadataReadOnly(): Map<string, any> | null {\n    return (requestStore.getStore()?.values as Map<string, any> | undefined) ?? null\n  }\n\n  /**\n   * Write-side accessor for the per-request metadata map.\n   *\n   * Returns the same map as {@link metadataReadOnly} when an ALS frame\n   * is active. Throws otherwise — writing to a fallback map outside\n   * the ALS frame would silently lose data because other call sites\n   * (downstream contributors, request-logger, etc.) read from the\n   * canonical store and would never see it. Mount\n   * `requestScopeMiddleware()` (Application does this for you in\n   * `'auto'` mode) or wrap your test setup in\n   * `requestStore.run({...}, () => …)` to fix.\n   */\n  private metadataForWrite(): Map<string, any> {\n    const store = requestStore.getStore()\n    if (store) return store.values as Map<string, any>\n    throw new Error(\n      'RequestContext.set called outside an AsyncLocalStorage frame. ' +\n        'Mount requestScopeMiddleware() before constructing RequestContext, ' +\n        'or wrap test setup in requestStore.run({ requestId, instances: new Map(), values: new Map() }, () => ...).',\n    )\n  }\n\n  // ── Request Data ────────────────────────────────────────────────────\n\n  /**\n   * Parsed request body. Returned as `DeepReadonly<TBody>` so adopters\n   * can't mutate Zod-validated payloads in place — compute new values\n   * and stash them via `ctx.set('key', value)` or a Context Contributor\n   * instead. Reach for `ctx.req.body` if you genuinely need the raw,\n   * mutable Express handle (rare).\n   */\n  get body(): DeepReadonly<TBody> {\n    return this.req.body as DeepReadonly<TBody>\n  }\n\n  /** Path parameters parsed from the route — read-only, see {@link body}. */\n  get params(): DeepReadonly<TParams> {\n    return this.req.params as DeepReadonly<TParams>\n  }\n\n  /** Parsed query string — read-only, see {@link body}. */\n  get query(): DeepReadonly<TQuery> {\n    return this.req.query as DeepReadonly<TQuery>\n  }\n\n  /** Inbound HTTP headers — read-only, see {@link body}. */\n  get headers(): Readonly<Request['headers']> {\n    return this.req.headers\n  }\n\n  get requestId(): string | undefined {\n    return (this.req as any).requestId ?? (this.req.headers['x-request-id'] as string | undefined)\n  }\n\n  /**\n   * `AbortSignal` that fires when the underlying HTTP request is\n   * closed — either because the client disconnected before the\n   * response was sent, or because Node's socket-close event ran\n   * after a normal response. Multiple `RequestContext` wrappers for\n   * the same request (router-builder constructs one per\n   * middleware/contributor pipeline / main handler) share a single\n   * `AbortController` cached on the underlying `req` object, so the\n   * signal is stable across the request lifecycle.\n   *\n   * Thread it through anything that takes an `AbortSignal` so the\n   * work cancels as soon as the client gives up — e.g. a kickjs-db\n   * relational query:\n   *\n   * ```ts\n   * @Get('/:id/full')\n   * async show(ctx: RequestContext) {\n   *   const row = await this.repo.findFullById(ctx.params.id, ctx.signal)\n   *   if (!row) return ctx.notFound()\n   *   ctx.json(row)\n   * }\n   * ```\n   *\n   * The repo passes `signal` to `db.query.<table>.findUnique({ signal })`;\n   * if the client disconnects mid-flight, the in-flight query rejects\n   * with `RelationalQueryCancelledError` instead of consuming the\n   * connection until completion.\n   *\n   * Implementation note — both `req.on('close')` and `res.on('close')`\n   * are wired so the signal aborts regardless of whether the close\n   * event lands on the request stream or the response stream first.\n   * Subsequent fires are no-ops (`AbortController.abort()` is\n   * idempotent).\n   */\n  get signal(): AbortSignal {\n    const req = this.req as Request & { [signalControllerKey]?: AbortController }\n    const cached = req[signalControllerKey]\n    if (cached) return cached.signal\n\n    const ctrl = new AbortController()\n    req[signalControllerKey] = ctrl\n    const abort = () => ctrl.abort('request closed')\n    this.req.once('close', abort)\n    this.res.once('close', abort)\n    return ctrl.signal\n  }\n\n  /** Session data (requires session middleware) */\n  get session(): any {\n    return (this.req as any).session\n  }\n\n  /**\n   * The authenticated user set by AuthAdapter.\n   * Reads from the per-request metadata store first (`ctx.set('user', ...)`),\n   * then falls back to `req.user` (set directly by AuthAdapter middleware).\n   *\n   * Extend the `AuthUser` interface via module augmentation in `@forinda/kickjs-auth`\n   * to get full typing.\n   *\n   * @example\n   * ```ts\n   * @Get('/me')\n   * @Authenticated()\n   * getProfile(ctx: RequestContext) {\n   *   const user = ctx.user\n   *   if (!user) return ctx.notFound()\n   *   return ctx.json({ user })\n   * }\n   * ```\n   */\n  get user(): MetaValue<'user', Record<string, any>> | undefined {\n    return this.metadataReadOnly()?.get('user') ?? (this.req as any).user\n  }\n\n  /**\n   * Tenant identifier for multi-tenant apps. Reads `user.tenantId` —\n   * populated either by `AuthAdapter.testMode({ tenantId })`, a tenant\n   * resolver middleware, or manually on the strategy's `mapPayload`.\n   *\n   * Augment `AuthUser` (or `ContextMeta['user']`) to widen the return\n   * type if your user shape guarantees a non-`string | undefined` id.\n   */\n  get tenantId(): string | undefined {\n    const u = this.user as Record<string, any> | undefined\n    return u?.tenantId\n  }\n\n  /**\n   * Effective role list for the current user. Prefers `user.tenantRoles`\n   * (populated by `AuthAdapterOptions.roleResolver` under a tenant) and\n   * falls back to `user.roles`. Returns an empty array when the user is\n   * absent or the shape has neither field.\n   */\n  get roles(): string[] {\n    const u = this.user as Record<string, any> | undefined\n    return u?.tenantRoles ?? u?.roles ?? []\n  }\n\n  // ── Query String Parsing ───────────────────────────────────────────\n\n  /**\n   * Parse the request query string into structured filters, sort, pagination, and search.\n   * Pass the result to an ORM query builder adapter (Drizzle, Prisma, Sequelize, etc.).\n   *\n   * Generic over the field config: when passed an inline literal (or\n   * `as const`), `filters[].field` and `sort[].field` are narrowed to\n   * the exact whitelisted field names. Pass nothing or a non-literal\n   * config and you get the loose `string` fallback.\n   *\n   * @param fieldConfig - Optional whitelist for filterable, sortable, and searchable fields\n   *\n   * @example\n   * ```ts\n   * @Get('/')\n   * async list(ctx: RequestContext) {\n   *   const parsed = ctx.qs({\n   *     filterable: ['status', 'priority'],\n   *     sortable: ['createdAt', 'title'],\n   *   } as const)\n   *   parsed.filters[0].field // typed as 'status' | 'priority'\n   *   parsed.sort[0].field    // typed as 'createdAt' | 'title'\n   * }\n   * ```\n   */\n  qs<TConfig extends QueryFieldConfig | undefined = undefined>(\n    fieldConfig?: TConfig,\n  ): TypedParsedQuery<TConfig> {\n    return parseQuery<TConfig>(this.req.query as Record<string, any>, fieldConfig)\n  }\n\n  // ── File Uploads ────────────────────────────────────────────────────\n\n  /**\n   * Single uploaded file (requires `@FileUpload({ mode: 'single' })`).\n   * Returned as `DeepReadonly<Express.Multer.File>` — file metadata is\n   * set by the upload middleware and shouldn't be mutated downstream.\n   */\n  get file(): DeepReadonly<Express.Multer.File> | undefined {\n    return this.req.file\n  }\n\n  /**\n   * Array of uploaded files (requires `@FileUpload({ mode: 'array' })`).\n   * Returns a `ReadonlyArray<DeepReadonly<Express.Multer.File>>` — both\n   * the list (`push`/`pop`) and each file's fields (`size`, `originalname`,\n   * etc.) are locked. Use `ctx.req.files` if you genuinely need the\n   * mutable Express handle.\n   */\n  get files(): ReadonlyArray<DeepReadonly<Express.Multer.File>> | undefined {\n    // multer's `Request['files']` is a union — array (mode: 'array' /\n    // 'any') or `{ [fieldname]: File[] }` (mode: 'fields'). The\n    // `@FileUpload({ mode: 'array' })` decorator only sets the array\n    // shape, but `Request['files']` is the broad union. Narrow back to\n    // `File[]` here for the common-case getter; adopters using\n    // `mode: 'fields'` can read `ctx.req.files` directly for the\n    // dictionary shape.\n    const f = this.req.files\n    return Array.isArray(f) ? f : undefined\n  }\n\n  // ── Metadata Store ──────────────────────────────────────────────────\n\n  /**\n   * Read a value from the per-request metadata store.\n   *\n   * When `ContextMeta` has been augmented with a matching key, the return\n   * type is inferred automatically. For ad-hoc keys, pass a generic:\n   * `ctx.get<MyType>('custom')`.\n   */\n  get<K extends string>(key: K): MetaValue<K> | undefined {\n    return this.metadataReadOnly()?.get(key) as MetaValue<K> | undefined\n  }\n\n  /**\n   * Write a value to the per-request metadata store. Throws when no\n   * AsyncLocalStorage frame is active — see {@link metadataForWrite}\n   * for why a silent fallback is the wrong default.\n   */\n  set<K extends string>(key: K, value: MetaValue<K>): void {\n    this.metadataForWrite().set(key, value)\n  }\n\n  // ── Response Helpers ────────────────────────────────────────────────\n\n  json(data: any, status = 200) {\n    return this.res.status(status).json(data)\n  }\n\n  created(data: any) {\n    return this.res.status(201).json(data)\n  }\n\n  noContent() {\n    return this.res.status(204).end()\n  }\n\n  notFound(message = 'Not Found') {\n    return this.res.status(404).json({ message })\n  }\n\n  badRequest(message: string) {\n    return this.res.status(400).json({ message })\n  }\n\n  html(content: string, status = 200) {\n    return this.res.status(status).type('html').send(content)\n  }\n\n  download(buffer: Buffer, filename: string, contentType = 'application/octet-stream') {\n    this.res.setHeader('Content-Disposition', `attachment; filename=\"${filename}\"`)\n    this.res.setHeader('Content-Type', contentType)\n    return this.res.send(buffer)\n  }\n\n  /**\n   * Render a template using the registered view engine (EJS, Pug, Handlebars, etc.).\n   * Requires a ViewAdapter to be configured in bootstrap().\n   *\n   * @param template - Template name (without extension, relative to viewsDir)\n   * @param data - Data to pass to the template\n   *\n   * @example\n   * ```ts\n   * ctx.render('dashboard', { user, title: 'Dashboard' })\n   * ctx.render('emails/welcome', { name: 'Alice' })\n   * ```\n   */\n  render(template: string, data: Record<string, any> = {}) {\n    return this.res.render(template, data)\n  }\n\n  /**\n   * Parse query params and return a standardized paginated response.\n   * Calls `ctx.qs()` internally, then wraps your data with pagination meta.\n   *\n   * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`\n   * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields\n   *\n   * @example\n   * ```ts\n   * @Get('/')\n   * async list(ctx: RequestContext) {\n   *   return ctx.paginate(\n   *     async (parsed) => {\n   *       const data = await db.select().from(users)\n   *         .where(query.where).limit(parsed.pagination.limit)\n   *         .offset(parsed.pagination.offset).all()\n   *       const total = await db.select({ count: count() }).from(users).get()\n   *       return { data, total: total?.count ?? 0 }\n   *     },\n   *     { filterable: ['name', 'role'], sortable: ['createdAt'] },\n   *   )\n   * }\n   * ```\n   */\n  async paginate<T, TConfig extends QueryFieldConfig | undefined = undefined>(\n    fetcher: (parsed: TypedParsedQuery<TConfig>) => Promise<{ data: T[]; total: number }>,\n    fieldConfig?: TConfig,\n  ) {\n    const parsed = this.qs<TConfig>(fieldConfig)\n    const { data, total } = await fetcher(parsed)\n    const { page, limit } = parsed.pagination\n    const totalPages = Math.ceil(total / limit) || 1\n\n    const response: PaginatedResponse<T> = {\n      data,\n      meta: {\n        page,\n        limit,\n        total,\n        totalPages,\n        hasNext: page < totalPages,\n        hasPrev: page > 1,\n      },\n    }\n\n    return this.json(response)\n  }\n\n  // ── Server-Sent Events ──────────────────────────────────────────────\n\n  /**\n   * Start an SSE (Server-Sent Events) stream.\n   * Sets the correct headers and returns helpers to send events.\n   *\n   * @example\n   * ```ts\n   * @Get('/events')\n   * async stream(ctx: RequestContext) {\n   *   const sse = ctx.sse()\n   *\n   *   const interval = setInterval(() => {\n   *     sse.send({ time: new Date().toISOString() }, 'tick')\n   *   }, 1000)\n   *\n   *   sse.onClose(() => clearInterval(interval))\n   * }\n   * ```\n   */\n  sse() {\n    this.res.writeHead(200, {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n      'X-Accel-Buffering': 'no',\n    })\n    this.res.flushHeaders()\n\n    const closeCallbacks: Array<() => void> = []\n\n    this.req.on('close', () => {\n      for (const cb of closeCallbacks) cb()\n    })\n\n    return {\n      /** Send an SSE event with optional event name and id */\n      send: (data: any, event?: string, id?: string) => {\n        if (id) this.res.write(`id: ${id}\\n`)\n        if (event) this.res.write(`event: ${event}\\n`)\n        this.res.write(`data: ${JSON.stringify(data)}\\n\\n`)\n      },\n      /** Send a comment (keeps connection alive) */\n      comment: (text: string) => {\n        this.res.write(`: ${text}\\n\\n`)\n      },\n      /** Register a callback when the client disconnects */\n      onClose: (fn: () => void) => {\n        closeCallbacks.push(fn)\n      },\n      /** End the SSE stream */\n      close: () => {\n        this.res.end()\n      },\n    }\n  }\n}\n\n/**\n * Short alias for `RequestContext` parameterised by a route shape.\n *\n * Use with `kick typegen`'s generated `KickRoutes` namespace for\n * fully-typed `ctx.params`, `ctx.body`, and `ctx.query`. Metadata\n * typing (`ctx.get()`, `ctx.set()`, `ctx.user`) comes from\n * `ContextMeta` augmentation and works on all `RequestContext` instances.\n *\n * @example\n * ```ts\n * @Get('/:id')\n * getUser(ctx: Ctx<KickRoutes.UserController['getUser']>) {\n *   ctx.params.id      // typed from RouteShape\n *   ctx.body           // typed from RouteShape\n *   ctx.user           // typed from ContextMeta\n *   ctx.get('tenant')  // typed from ContextMeta\n * }\n * ```\n */\nexport type Ctx<TRoute extends RouteShape = RouteShape> = RequestContext<\n  TRoute extends { body: infer B } ? B : any,\n  TRoute extends { params: infer P } ? P : any,\n  TRoute extends { query: infer Q } ? Q : any\n>\n\n/**\n * Global ambient registry of typed routes, populated by `kick typegen`.\n *\n * Each interface inside `KickRoutes` corresponds to a controller class;\n * each property is one route method on that controller. The values\n * conform to `RouteShape`.\n *\n * Empty by default — declarations come from `.kickjs/types/routes.d.ts`\n * generated alongside the rest of the typegen output.\n */\ndeclare global {\n  // eslint-disable-next-line @typescript-eslint/no-namespace\n  namespace KickRoutes {}\n}\n"],"mappings":"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"}

package/dist/{context-decorator-BgdDd-6X.d.mts → context-decorator-BYf8HdMl.d.mts}

@@ -297,5 +297,5 @@ interface ContextDecorator<K extends string = string, D extends Record<string, D
  */
 declare function defineContextDecorator<K extends string, D extends Record<string, DepValue> = Record<string, never>, P extends Record<string, unknown> = Record<string, never>, Ctx extends ExecutionContext = ExecutionContext>(spec: ContextDecoratorSpec<K, D, P, Ctx>): ContextDecorator<K, D, P, Ctx>;
 //#endregion
-export { ContributorRegistration as a, ResolvedDeps as c, ContextMetaKey as i, defineContextDecorator as l, ContextDecorator as n, ContributorRegistrations as o, ContextDecoratorSpec as r, DepValue as s, AnyContributorRegistration as t };
-//# sourceMappingURL=context-decorator-BgdDd-6X.d.mts.map
+export { ContextMetaKey as a, DepValue as c, ContextDecoratorTarget as i, ResolvedDeps as l, ContextDecorator as n, ContributorRegistration as o, ContextDecoratorSpec as r, ContributorRegistrations as s, AnyContributorRegistration as t, defineContextDecorator as u };
+//# sourceMappingURL=context-decorator-BYf8HdMl.d.mts.map

package/dist/{context-decorator-BgdDd-6X.d.mts.map → context-decorator-BYf8HdMl.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"context-decorator-BgdDd-6X.d.mts","names":[],"sources":["../src/core/context-decorator.ts"],"mappings":"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"}
+{"version":3,"file":"context-decorator-BYf8HdMl.d.mts","names":[],"sources":["../src/core/context-decorator.ts"],"mappings":"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"}

package/dist/core/adapter.d.mts

@@ -1,3 +1,3 @@
 
-import { a as MiddlewarePhase, i as AppAdapterClass, n as AdapterMiddleware, r as AppAdapter, t as AdapterContext } from "../adapter-0r2uRCD3.mjs";
+import { a as MiddlewarePhase, i as AppAdapterClass, n as AdapterMiddleware, r as AppAdapter, t as AdapterContext } from "../adapter-CoJp35rz.mjs";
 export { AdapterContext, AdapterMiddleware, AppAdapter, AppAdapterClass, MiddlewarePhase };

package/dist/core/adapter.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/app-module.d.mts

@@ -1,3 +1,3 @@
 
-import { i as ModuleRoutes, n as AppModuleClass, r as AppModuleEntry, t as AppModule } from "../app-module-CzlIIjO3.mjs";
+import { i as ModuleRoutes, n as AppModuleClass, r as AppModuleEntry, t as AppModule } from "../app-module-BE7hAASB.mjs";
 export { AppModule, AppModuleClass, AppModuleEntry, ModuleRoutes };

package/dist/core/app-module.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/cache.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/container.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,4 +8,4 @@
  *
  * @license MIT
  */
-import{n as tokenName,t as Container}from"../container-D0v17gF8.mjs";export{Container,tokenName};
+import{n as tokenName,t as Container}from"../container-COmj1vM3.mjs";export{Container,tokenName};

package/dist/core/cron.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,5 +8,5 @@
  *
  * @license MIT
  */
-import{c as pushClassMeta,t as getClassMeta}from"../metadata-IHiynOCv.mjs";const CRON_META=`kick/cron`;function Cron(expression,options){return(target,propertyKey)=>{pushClassMeta(CRON_META,target.constructor,{expression,handlerName:propertyKey,description:options?.description,timezone:options?.timezone,runOnInit:options?.runOnInit})}}function getCronJobs(target){return getClassMeta(CRON_META,target,[])}export{CRON_META,Cron,getCronJobs};
+import{c as pushClassMeta,t as getClassMeta}from"../metadata-D9F5Lm-z.mjs";const CRON_META=`kick/cron`;function Cron(expression,options){return(target,propertyKey)=>{pushClassMeta(CRON_META,target.constructor,{expression,handlerName:propertyKey,description:options?.description,timezone:options?.timezone,runOnInit:options?.runOnInit})}}function getCronJobs(target){return getClassMeta(CRON_META,target,[])}export{CRON_META,Cron,getCronJobs};
 //# sourceMappingURL=cron.mjs.map

package/dist/core/decorators.d.mts

@@ -1,3 +1,3 @@
 
-import { A as normalizeApiQueryParamsConfig, C as Post, D as RouteDefinition, E as Repository, O as Service, S as Patch, T as Put, _ as Get, a as Autowired, b as Middleware, c as ColumnApiQueryParamsConfig, d as Delete, f as Env, g as FileUploadConfig, h as FileUpload, i as AssetKey, j as withBuilder, k as Value, l as Component, m as FileTypeFilter, n as ApiQueryParamsConfig, o as BaseUploadOptions, p as EnvKey, r as Asset, s as Builder, t as ApiQueryParams, u as Controller, v as Inject, w as PostConstruct, x as MiddlewareHandler, y as Injectable } from "../decorators-J5mC7D-6.mjs";
-export { ApiQueryParams, ApiQueryParamsConfig, Asset, AssetKey, Autowired, BaseUploadOptions, Builder, ColumnApiQueryParamsConfig, Component, Controller, Delete, Env, EnvKey, FileTypeFilter, FileUpload, FileUploadConfig, Get, Inject, Injectable, Middleware, MiddlewareHandler, Patch, Post, PostConstruct, Put, Repository, RouteDefinition, Service, Value, normalizeApiQueryParamsConfig, withBuilder };
+import { A as Value, C as Post, D as Repository, E as Put, M as withBuilder, O as RouteDefinition, S as Patch, T as PropertyOrParameterDecorator, _ as Get, a as Autowired, b as Middleware, c as ColumnApiQueryParamsConfig, d as Delete, f as Env, g as FileUploadConfig, h as FileUpload, i as AssetKey, j as normalizeApiQueryParamsConfig, k as Service, l as Component, m as FileTypeFilter, n as ApiQueryParamsConfig, o as BaseUploadOptions, p as EnvKey, r as Asset, s as Builder, t as ApiQueryParams, u as Controller, v as Inject, w as PostConstruct, x as MiddlewareHandler, y as Injectable } from "../decorators-ZcjsV1O0.mjs";
+export { ApiQueryParams, ApiQueryParamsConfig, Asset, AssetKey, Autowired, BaseUploadOptions, Builder, ColumnApiQueryParamsConfig, Component, Controller, Delete, Env, EnvKey, FileTypeFilter, FileUpload, FileUploadConfig, Get, Inject, Injectable, Middleware, MiddlewareHandler, Patch, Post, PostConstruct, PropertyOrParameterDecorator, Put, Repository, RouteDefinition, Service, Value, normalizeApiQueryParamsConfig, withBuilder };

package/dist/core/decorators.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,5 +8,5 @@
  *
  * @license MIT
  */
-import{t as Container}from"../container-D0v17gF8.mjs";import{METADATA}from"./interfaces.mjs";import{c as pushClassMeta,d as setInMetaMap,f as setInMetaRecord,l as pushMethodMeta,p as setMethodMeta,u as setClassMeta}from"../metadata-IHiynOCv.mjs";import"reflect-metadata";const pendingRegistrations=[],allRegistrations=new Map;let containerRef=null;function flushPending(container){containerRef=container;for(let{target,scope}of pendingRegistrations)container.has(target)||container.register(target,target,scope);pendingRegistrations.length=0}Container._onReady=flushPending,Container._onReset=container=>{containerRef=container;for(let[,{target,scope}]of allRegistrations)container.has(target)||container.register(target,target,scope)};function registerInContainer(target,scope){setClassMeta(METADATA.INJECTABLE,!0,target),setClassMeta(METADATA.SCOPE,scope,target);let name=target.name||String(target);allRegistrations.set(name,{target,scope}),containerRef?containerRef.has(target)||containerRef.register(target,target,scope):pendingRegistrations.push({target,scope})}function Injectable(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`injectable`,target),registerInContainer(target,options?.scope??`singleton`)}}function Service(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`service`,target),registerInContainer(target,options?.scope??`singleton`)}}function Component(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`component`,target),registerInContainer(target,options?.scope??`singleton`)}}function Repository(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`repository`,target),registerInContainer(target,options?.scope??`singleton`)}}function Controller(){return target=>{setClassMeta(METADATA.CLASS_KIND,`controller`,target),registerInContainer(target,`singleton`)}}function PostConstruct(){return(target,propertyKey)=>{setClassMeta(METADATA.POST_CONSTRUCT,propertyKey,target)}}function Autowired(token){return(target,propertyKey)=>{setInMetaMap(METADATA.AUTOWIRED,target,propertyKey,token)}}function Inject(token){return(target,_propertyKey,parameterIndex)=>{setInMetaRecord(METADATA.INJECT,target,parameterIndex,token)}}function Value(envKey,defaultValue){return(target,propertyKey)=>{setInMetaMap(METADATA.VALUE,target,propertyKey,{envKey,defaultValue})}}function Asset(assetKey){return(target,propertyKey)=>{setInMetaMap(METADATA.ASSET,target,propertyKey,{assetKey})}}function createRouteDecorator(method){return(path,validation)=>(target,propertyKey)=>{pushClassMeta(METADATA.ROUTES,target.constructor,{method,path:path||`/`,handlerName:propertyKey,validation})}}const Get=createRouteDecorator(`GET`),Post=createRouteDecorator(`POST`),Put=createRouteDecorator(`PUT`),Delete=createRouteDecorator(`DELETE`),Patch=createRouteDecorator(`PATCH`);function normalizeApiQueryParamsConfig(config){return`columns`in config&&config.columns&&typeof config.columns==`object`?{filterable:Object.keys(config.columns),sortable:config.sortable?Object.keys(config.sortable):void 0,searchable:config.searchColumns?config.searchColumns.map(col=>col?.name??``).filter(Boolean):void 0}:config}function ApiQueryParams(config){return(target,propertyKey)=>{let normalized=normalizeApiQueryParamsConfig(config);setMethodMeta(METADATA.QUERY_PARAMS,normalized,target.constructor,propertyKey)}}function Middleware(...handlers){return(target,propertyKey)=>{propertyKey?pushMethodMeta(METADATA.METHOD_MIDDLEWARES,target.constructor,propertyKey,...handlers):pushClassMeta(METADATA.CLASS_MIDDLEWARES,target,...handlers)}}function FileUpload(config){return(target,propertyKey)=>{setMethodMeta(METADATA.FILE_UPLOAD,config,target.constructor,propertyKey)}}function attachBuilder(target){setClassMeta(METADATA.BUILDER,!0,target),target.builder=function(){let props={},proxy=new Proxy({},{get(_,key){return key===`build`?()=>Object.assign(new target,props):value=>(props[key]=value,proxy)}});return proxy}}function Builder(target){attachBuilder(target)}function withBuilder(ctor){return attachBuilder(ctor),ctor}export{ApiQueryParams,Asset,Autowired,Builder,Component,Controller,Delete,FileUpload,Get,Inject,Injectable,Middleware,Patch,Post,PostConstruct,Put,Repository,Service,Value,normalizeApiQueryParamsConfig,withBuilder};
+import{t as Container}from"../container-COmj1vM3.mjs";import{METADATA}from"./interfaces.mjs";import{c as pushClassMeta,d as setInMetaMap,f as setInMetaRecord,l as pushMethodMeta,p as setMethodMeta,u as setClassMeta}from"../metadata-D9F5Lm-z.mjs";import"reflect-metadata";const pendingRegistrations=[],allRegistrations=new Map;let containerRef=null;function flushPending(container){containerRef=container;for(let{target,scope}of pendingRegistrations)container.has(target)||container.register(target,target,scope);pendingRegistrations.length=0}Container._onReady=flushPending,Container._onReset=container=>{containerRef=container;for(let[,{target,scope}]of allRegistrations)container.has(target)||container.register(target,target,scope)};function registerInContainer(target,scope){setClassMeta(METADATA.INJECTABLE,!0,target),setClassMeta(METADATA.SCOPE,scope,target);let name=target.name||String(target);allRegistrations.set(name,{target,scope}),containerRef?containerRef.has(target)||containerRef.register(target,target,scope):pendingRegistrations.push({target,scope})}function Injectable(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`injectable`,target),registerInContainer(target,options?.scope??`singleton`)}}function Service(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`service`,target),registerInContainer(target,options?.scope??`singleton`)}}function Component(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`component`,target),registerInContainer(target,options?.scope??`singleton`)}}function Repository(options){return target=>{setClassMeta(METADATA.CLASS_KIND,`repository`,target),registerInContainer(target,options?.scope??`singleton`)}}function Controller(){return target=>{setClassMeta(METADATA.CLASS_KIND,`controller`,target),registerInContainer(target,`singleton`)}}function PostConstruct(){return(target,propertyKey)=>{setClassMeta(METADATA.POST_CONSTRUCT,propertyKey,target)}}function applyInjection(token,target,propertyKey,parameterIndex){if(typeof parameterIndex==`number`){setInMetaRecord(METADATA.INJECT,target,parameterIndex,token);return}propertyKey!=null&&setInMetaMap(METADATA.AUTOWIRED,target,propertyKey,token)}function Autowired(token){return((target,propertyKey,parameterIndex)=>{applyInjection(token,target,propertyKey,parameterIndex)})}function Inject(token){return((target,propertyKey,parameterIndex)=>{applyInjection(token,target,propertyKey,parameterIndex)})}function Value(envKey,defaultValue){return(target,propertyKey)=>{setInMetaMap(METADATA.VALUE,target,propertyKey,{envKey,defaultValue})}}function Asset(assetKey){return(target,propertyKey)=>{setInMetaMap(METADATA.ASSET,target,propertyKey,{assetKey})}}function createRouteDecorator(method){return(path,validation)=>(target,propertyKey)=>{pushClassMeta(METADATA.ROUTES,target.constructor,{method,path:path||`/`,handlerName:propertyKey,validation})}}const Get=createRouteDecorator(`GET`),Post=createRouteDecorator(`POST`),Put=createRouteDecorator(`PUT`),Delete=createRouteDecorator(`DELETE`),Patch=createRouteDecorator(`PATCH`);function normalizeApiQueryParamsConfig(config){return`columns`in config&&config.columns&&typeof config.columns==`object`?{filterable:Object.keys(config.columns),sortable:config.sortable?Object.keys(config.sortable):void 0,searchable:config.searchColumns?config.searchColumns.map(col=>col?.name??``).filter(Boolean):void 0}:config}function ApiQueryParams(config){return(target,propertyKey)=>{let normalized=normalizeApiQueryParamsConfig(config);setMethodMeta(METADATA.QUERY_PARAMS,normalized,target.constructor,propertyKey)}}function Middleware(...handlers){return(target,propertyKey)=>{propertyKey?pushMethodMeta(METADATA.METHOD_MIDDLEWARES,target.constructor,propertyKey,...handlers):pushClassMeta(METADATA.CLASS_MIDDLEWARES,target,...handlers)}}function FileUpload(config){return(target,propertyKey)=>{setMethodMeta(METADATA.FILE_UPLOAD,config,target.constructor,propertyKey)}}function attachBuilder(target){setClassMeta(METADATA.BUILDER,!0,target),target.builder=function(){let props={},proxy=new Proxy({},{get(_,key){return key===`build`?()=>Object.assign(new target,props):value=>(props[key]=value,proxy)}});return proxy}}function Builder(target){attachBuilder(target)}function withBuilder(ctor){return attachBuilder(ctor),ctor}export{ApiQueryParams,Asset,Autowired,Builder,Component,Controller,Delete,FileUpload,Get,Inject,Injectable,Middleware,Patch,Post,PostConstruct,Put,Repository,Service,Value,normalizeApiQueryParamsConfig,withBuilder};
 //# sourceMappingURL=decorators.mjs.map

package/dist/core/decorators.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.mjs","names":[],"sources":["../../src/core/decorators.ts"],"sourcesContent":["import 'reflect-metadata'\nimport { METADATA, Scope, type BuilderOf, type ServiceOptions } from './interfaces'\nimport { Container, type KickJsRegistry } from './container'\nimport {\n  setClassMeta,\n  setMethodMeta,\n  pushClassMeta,\n  pushMethodMeta,\n  setInMetaMap,\n  setInMetaRecord,\n} from './metadata'\n\n// ── Decorator Registration System ───────────────────────────────────────\n// Decorators execute at class-definition time (module load). The Container\n// may not exist yet when the first decorator fires. We queue registrations\n// and flush them on first Container.getInstance() call.\n//\n// `allRegistrations` is a persistent registry that survives Container.reset().\n// On reset (HMR), all previously decorated classes are re-registered on the\n// fresh container. This ensures @Service, @Controller, @Repository, etc.\n// all survive HMR without manual re-registration.\n\ntype PendingRegistration = { target: any; scope: Scope }\nconst pendingRegistrations: PendingRegistration[] = []\n// Keyed by class name to prevent memory leaks during HMR — new class with\n// the same name replaces the old entry instead of accumulating references.\nconst allRegistrations = new Map<string, { target: any; scope: Scope }>()\nlet containerRef: any = null\n\nfunction flushPending(container: any): void {\n  containerRef = container\n  for (const { target, scope } of pendingRegistrations) {\n    if (!container.has(target)) {\n      container.register(target, target, scope)\n    }\n  }\n  pendingRegistrations.length = 0\n}\n\n// Wire up synchronously — Container._onReady is called on first getInstance()\nContainer._onReady = flushPending\n\n// On Container.reset(), update containerRef and replay ALL decorator\n// registrations on the fresh container. This handles HMR where the container\n// is wiped but not all decorated modules are re-evaluated.\nContainer._onReset = (container: any) => {\n  containerRef = container\n  for (const [, { target, scope }] of allRegistrations) {\n    if (!container.has(target)) {\n      container.register(target, target, scope)\n    }\n  }\n}\n\n// ── Class Decorators ────────────────────────────────────────────────────\n\nfunction registerInContainer(target: any, scope: Scope): void {\n  setClassMeta(METADATA.INJECTABLE, true, target)\n  setClassMeta(METADATA.SCOPE, scope, target)\n\n  // Track in persistent registry — survives Container.reset() for HMR replay.\n  // Keyed by name so HMR class re-creation replaces the old entry.\n  const name = target.name || String(target)\n  allRegistrations.set(name, { target, scope })\n\n  if (containerRef) {\n    // Container already initialized — register immediately\n    if (!containerRef.has(target)) {\n      containerRef.register(target, target, scope)\n    }\n  } else {\n    // Container not ready yet — queue for later\n    pendingRegistrations.push({ target, scope })\n  }\n}\n\n/** Mark a class as injectable with lifecycle scope */\nexport function Injectable(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'injectable', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/** Mark a class as a service (semantic alias for Injectable) */\nexport function Service(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'service', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/** Mark a class as a generic managed component */\nexport function Component(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'component', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/** Mark a class as a repository */\nexport function Repository(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'repository', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/**\n * Mark a class as an HTTP controller and register it in the DI container.\n *\n * Route prefixes are defined by the module's `routes().path` — the single\n * source of truth for where routes mount. The legacy\n * `@Controller('/path')` parameter was removed in v4; if your code\n * still passes a string, see `docs/guide/migration-v3-to-v4.md` for\n * the rename map.\n */\nexport function Controller(): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'controller', target)\n    registerInContainer(target, Scope.SINGLETON)\n  }\n}\n\n// ── Method Decorators ───────────────────────────────────────────────────\n\n/** Mark a method as a lifecycle hook called after instantiation */\nexport function PostConstruct(): MethodDecorator {\n  return (target, propertyKey) => {\n    setClassMeta(METADATA.POST_CONSTRUCT, propertyKey, target)\n  }\n}\n\n// ── Property Decorators ─────────────────────────────────────────────────\n\n/** Property injection — resolved lazily from the container */\nexport function Autowired(token?: any): PropertyDecorator {\n  return (target, propertyKey) => {\n    setInMetaMap(METADATA.AUTOWIRED, target, propertyKey as string, token)\n  }\n}\n\n/**\n * Constructor parameter injection with an explicit token.\n *\n * **Constructor parameters only** — does not work as a property decorator.\n * For property injection with a token, use `@Autowired(token)` instead.\n *\n * ## Typed string-literal overload (architecture.md §22.4 #3)\n *\n * When called with a string literal that matches a key of the\n * augmented `KickJsRegistry`, TypeScript narrows the parameter type\n * to the registered type. Typo'd literals become compile errors\n * (the string isn't `keyof KickJsRegistry`). Class identities and\n * `InjectionToken<T>` keep working unchanged via the second overload.\n *\n * @example\n * ```ts\n * import { Service, Inject } from '@forinda/kickjs'\n * import type { PrismaClient } from '@prisma/client'\n *\n * `@Service()`\n * class UserRepo {\n *   constructor(@Inject('kick/prisma/Client') private db: PrismaClient) {}\n * }\n * ```\n *\n * After `kick typegen` populates `.kickjs/types/registry.d.ts` the\n * literal autocompletes from the registry, and a typo\n * (`@Inject('kick/prisma/Cleint')`) becomes a TS2345 error.\n */\nexport function Inject<K extends keyof KickJsRegistry & string>(token: K): ParameterDecorator\nexport function Inject(token: unknown): ParameterDecorator\nexport function Inject(token: unknown): ParameterDecorator {\n  return (target, _propertyKey, parameterIndex) => {\n    setInMetaRecord(METADATA.INJECT, target as object, parameterIndex, token)\n  }\n}\n\n/**\n * Global ambient registry of typed environment variables, populated by\n * `kick typegen` from the project's env schema (typically\n * `src/env.ts`'s `export default defineEnv(...)`).\n *\n * Empty by default — declarations come from `.kickjs/types/env.ts`\n * generated alongside the rest of the typegen output. Once populated,\n * `@Value('PORT')` autocompletes the key, type-checks the default\n * value, and `process.env.PORT` is also typed via the parallel\n * `NodeJS.ProcessEnv` augmentation in the same generated file.\n */\ndeclare global {\n  // eslint-disable-next-line @typescript-eslint/no-empty-object-type\n  interface KickEnv {}\n}\n\n/** A string key known to the typed env registry (`never` until typegen runs) */\nexport type EnvKey = keyof KickEnv & string\n\n/**\n * Look up the type of a typed env entry.\n *\n * Decorators can't propagate the property type from the key, so users\n * still need to write the property's type — but `Env<K>` lets them\n * derive it from `KickEnv` instead of duplicating the schema:\n *\n * ```ts\n * @Service()\n * class MyService {\n *   @Value('PORT')\n *   private port!: Env<'PORT'>  // → number, narrowed from KickEnv['PORT']\n * }\n * ```\n */\nexport type Env<K extends EnvKey = EnvKey> = KickEnv[K]\n\n/**\n * Constraint that allows any string when the typed env registry is\n * empty (no `kick typegen` has run yet, so existing code with raw\n * string keys keeps working) but locks the argument down to known\n * `EnvKey` literals once the registry is populated.\n *\n * Implementation: when `EnvKey` is `never`, the conditional resolves\n * to the user's `K`, accepting anything. Once typegen has populated\n * `KickEnv`, `EnvKey` becomes a real union and the conditional forces\n * `K` to be assignable to it.\n */\ntype ValueKey<K extends string> = [EnvKey] extends [never] ? K : K & EnvKey\n\n/**\n * Inject an environment variable value. Evaluated lazily so the env\n * is available at access time, not at decoration time.\n *\n * If no default is provided and the env var is missing, throws at access time\n * to catch misconfiguration early instead of returning undefined.\n *\n * Uses metadata + instance getter to work correctly with `useDefineForClassFields`.\n *\n * Type-safety:\n * - Without `kick typegen` run, any string key is accepted (back-compat).\n * - After typegen, `KickEnv` is populated and unknown keys become a tsc\n *   error. The optional `defaultValue` is type-checked against the\n *   schema's inferred type for that key.\n */\nexport function Value<K extends string>(\n  envKey: ValueKey<K>,\n  defaultValue?: K extends EnvKey ? KickEnv[K] : unknown,\n): PropertyDecorator {\n  return (target, propertyKey) => {\n    setInMetaMap(METADATA.VALUE, target, propertyKey as string, { envKey, defaultValue })\n  }\n}\n\n// ── @Asset — typed asset path injection (assets-plan.md PR 3+) ─────────\n\nimport type { KickAssets } from './assets'\n\n/**\n * Flatten the nested `KickAssets` augmentation (typegen-emitted in\n * PR 4) into a string-literal union of dot/slash-joined paths.\n *\n * `interface KickAssets { mails: { welcome: () => string; orders: {\n * confirmation: () => string } } }` becomes\n * `'mails/welcome' | 'mails/orders/confirmation'`.\n *\n * Returns `never` when `KickAssets` is empty (no typegen has run yet)\n * so `AssetKeyArg` falls through to accept any string.\n */\ntype FlattenAssets<T, Prefix extends string = ''> = {\n  [K in keyof T & string]: T[K] extends () => string\n    ? `${Prefix}${K}`\n    : T[K] extends Record<string, unknown>\n      ? FlattenAssets<T[K], `${Prefix}${K}/`>\n      : never\n}[keyof T & string]\n\n/** Flat union of every known `<namespace>/<key>` path. */\nexport type AssetKey = FlattenAssets<KickAssets>\n\n/**\n * Constraint mirroring `ValueKey<K>` — accepts any string when\n * `AssetKey` is `never` (back-compat for adopters who haven't run\n * `kick typegen` yet) but locks the argument to known literals once\n * the typegen-augmented `KickAssets` interface is populated.\n */\ntype AssetKeyArg<K extends string> = [AssetKey] extends [never] ? K : K & AssetKey\n\n/**\n * Inject the resolved file-system path for a typed asset. Mirrors\n * `@Value`'s lazy-getter pattern — the asset is resolved on every\n * property access, NOT at class instantiation, so:\n *\n * - Tests can swap fixtures + clear the cache without re-instantiating\n *   the consuming class.\n * - The first access cost is paid once per process (the manifest cache\n *   in `core/assets.ts` makes subsequent calls cheap).\n *\n * Type-safety:\n *\n * - Without typegen, any string key is accepted (back-compat — same\n *   trick as `@Value`).\n * - After typegen, `KickAssets` is populated and `AssetKey` is a\n *   union of every flattened `<namespace>/<key>` path. Unknown keys\n *   become a TS error.\n *\n * @example\n * ```ts\n * import { Service, Asset } from '@forinda/kickjs'\n *\n * `@Service()`\n * class MailService {\n *   `@Asset('mails/welcome')`\n *   private welcomeTemplate!: string\n *\n *   send(user: User) {\n *     return ejs.renderFile(this.welcomeTemplate, { user })\n *   }\n * }\n * ```\n */\nexport function Asset<K extends string>(assetKey: AssetKeyArg<K>): PropertyDecorator {\n  return (target, propertyKey) => {\n    setInMetaMap(METADATA.ASSET, target, propertyKey as string, { assetKey })\n  }\n}\n\n// ── HTTP Route Decorators ───────────────────────────────────────────────\n\nexport interface RouteDefinition {\n  method: string\n  path: string\n  handlerName: string\n  validation?: {\n    /** JSON Schema object for validating the request body */\n    body?: any\n    /** JSON Schema object for validating query parameters */\n    query?: any\n    /** JSON Schema object for validating URL params */\n    params?: any\n    /** Schema name in OpenAPI components/schemas for the request body. Auto-generated from handler name if omitted. */\n    name?: string\n  }\n}\n\nfunction createRouteDecorator(method: string) {\n  return (path?: string, validation?: RouteDefinition['validation']): MethodDecorator => {\n    return (target, propertyKey) => {\n      pushClassMeta<RouteDefinition>(METADATA.ROUTES, target.constructor, {\n        method,\n        path: path || '/',\n        handlerName: propertyKey as string,\n        validation,\n      })\n    }\n  }\n}\n\nexport const Get = createRouteDecorator('GET')\nexport const Post = createRouteDecorator('POST')\nexport const Put = createRouteDecorator('PUT')\nexport const Delete = createRouteDecorator('DELETE')\nexport const Patch = createRouteDecorator('PATCH')\n\n// ── Query Params Decorator ─────────────────────────────────────────────\n\nexport interface ApiQueryParamsConfig {\n  /** Fields that can be used in filter queries (e.g., `?filter=status:eq:active`) */\n  filterable?: string[]\n  /** Fields that can be used in sort queries (e.g., `?sort=createdAt:desc`) */\n  sortable?: string[]\n  /** Fields that are searched with the `?q=` parameter */\n  searchable?: string[]\n}\n\n/**\n * Column-object-based query params config (e.g., from DrizzleQueryParamsConfig).\n * `Object.keys()` is used to derive field names for OpenAPI docs.\n */\nexport interface ColumnApiQueryParamsConfig {\n  columns: Record<string, any>\n  sortable?: Record<string, any>\n  searchColumns?: any[]\n  [key: string]: any\n}\n\n/**\n * Normalize a query params config to the string-based ApiQueryParamsConfig.\n * Handles both string-based and column-object-based configs.\n */\nexport function normalizeApiQueryParamsConfig(\n  config: ApiQueryParamsConfig | ColumnApiQueryParamsConfig,\n): ApiQueryParamsConfig {\n  if ('columns' in config && config.columns && typeof config.columns === 'object') {\n    return {\n      filterable: Object.keys(config.columns),\n      sortable: config.sortable ? Object.keys(config.sortable) : undefined,\n      searchable: config.searchColumns\n        ? config.searchColumns.map((col: any) => col?.name ?? '').filter(Boolean)\n        : undefined,\n    }\n  }\n  return config as ApiQueryParamsConfig\n}\n\n/**\n * Document the query parameters accepted by a GET endpoint.\n * Used by SwaggerAdapter to generate `filter`, `sort`, `page`, `limit`, and `q` params\n * in the OpenAPI spec, with descriptions listing the allowed fields.\n *\n * Accepts both string-based configs and column-object configs (e.g., DrizzleQueryParamsConfig).\n *\n * @example\n * ```ts\n * // String-based\n * @ApiQueryParams({\n *   filterable: ['status', 'category', 'price'],\n *   sortable: ['name', 'createdAt', 'price'],\n *   searchable: ['name', 'description'],\n * })\n *\n * // Column-object-based (Drizzle)\n * @ApiQueryParams(TASK_QUERY_CONFIG)\n * ```\n */\nexport function ApiQueryParams(\n  config: ApiQueryParamsConfig | ColumnApiQueryParamsConfig,\n): MethodDecorator {\n  return (target, propertyKey) => {\n    const normalized = normalizeApiQueryParamsConfig(config)\n    setMethodMeta(METADATA.QUERY_PARAMS, normalized, target.constructor, propertyKey as string)\n  }\n}\n\n// ── Middleware Decorators ───────────────────────────────────────────────\n\n/**\n * Middleware handler function.\n * Generic `TCtx` defaults to `any` — import `RequestContext` from\n * `@forinda/kickjs` for full type safety:\n *\n * ```ts\n * import type { MiddlewareHandler } from '@forinda/kickjs'\n * import type { RequestContext } from '@forinda/kickjs'\n *\n * const auth: MiddlewareHandler<RequestContext> = (ctx, next) => {\n *   ctx.body  // fully typed\n *   next()\n * }\n * ```\n */\nexport type MiddlewareHandler<TCtx = any> = (ctx: TCtx, next: () => void) => void | Promise<void>\n\n/** Attach middleware handlers to a class or method */\nexport function Middleware(...handlers: MiddlewareHandler[]): ClassDecorator & MethodDecorator {\n  return (target: any, propertyKey?: string | symbol) => {\n    if (propertyKey) {\n      pushMethodMeta(\n        METADATA.METHOD_MIDDLEWARES,\n        target.constructor,\n        propertyKey as string,\n        ...handlers,\n      )\n    } else {\n      pushClassMeta(METADATA.CLASS_MIDDLEWARES, target, ...handlers)\n    }\n  }\n}\n\n// ── File Upload Decorator ───────────────────────────────────────────────\n\n/**\n * File filter — accepts short extensions ('jpg'), full MIME types ('image/jpeg'),\n * wildcards ('image/*'), or a function `(mimetype, filename) => boolean` for full control.\n */\nexport type FileTypeFilter = string[] | ((mimetype: string, filename: string) => boolean)\n\n/**\n * Shared upload options used by both the `@FileUpload` decorator and the\n * `upload.single()` / `upload.array()` / `upload.none()` middleware.\n */\nexport interface BaseUploadOptions {\n  /** Max file size in bytes (default: 5MB) */\n  maxSize?: number\n  /**\n   * Allowed file types:\n   * - **string[]** — short extensions ('jpg'), full MIME types ('image/jpeg'), or wildcards ('image/*')\n   * - **function** — `(mimetype, filename) => boolean` for full control\n   */\n  allowedTypes?: FileTypeFilter\n  /** Extend the built-in extension-to-MIME map */\n  customMimeMap?: Record<string, string>\n}\n\nexport interface FileUploadConfig extends BaseUploadOptions {\n  mode: 'single' | 'array' | 'none'\n  /** Form field name (default: 'file') */\n  fieldName?: string\n  /** Max files for array mode (default: 10) */\n  maxCount?: number\n}\n\n/** Configure file upload handling for a controller method */\nexport function FileUpload(config: FileUploadConfig): MethodDecorator {\n  return (target, propertyKey) => {\n    setMethodMeta(METADATA.FILE_UPLOAD, config, target.constructor, propertyKey as string)\n  }\n}\n\n// ── Builder Decorator ───────────────────────────────────────────────────\n\nfunction attachBuilder(target: any): void {\n  setClassMeta(METADATA.BUILDER, true, target)\n  target.builder = function () {\n    const props: Record<string, any> = {}\n    const proxy: any = new Proxy(\n      {},\n      {\n        get(_, key) {\n          if (key === 'build') {\n            return () => Object.assign(new target(), props)\n          }\n          return (value: any) => {\n            props[key as string] = value\n            return proxy\n          }\n        },\n      },\n    )\n    return proxy\n  }\n}\n\n/**\n * Add a static `builder()` method for fluent construction.\n *\n * Legacy decorators cannot widen the class type, so by default the\n * caller sees the unmodified shape. Opt into typing by adding a single\n * `declare static` line:\n *\n * ```ts\n * @Builder\n * class UserDto {\n *   name!: string\n *   email!: string\n *   declare static readonly builder: () => BuilderOf<UserDto>\n * }\n * ```\n *\n * `readonly` keeps SonarQube's `typescript:S1444` quiet — the runtime\n * assigns `target.builder` once at decoration time and never again.\n *\n * If you'd rather not write the `declare`, use `withBuilder()` instead —\n * same runtime, types inferred automatically.\n */\nexport function Builder(target: any): void {\n  attachBuilder(target)\n}\n\n/**\n * Factory variant of `@Builder`. Wraps the class with the same runtime\n * and returns it intersected with `{ builder(): BuilderOf<T> }` so the\n * static is fully typed without any `declare` boilerplate.\n *\n * ```ts\n * class UserDtoBase {\n *   name!: string\n *   email!: string\n * }\n * export const UserDto = withBuilder(UserDtoBase)\n * export type UserDto = InstanceType<typeof UserDto>\n *\n * UserDto.builder().name('Alice').email('a@b.com').build() // fully typed\n * ```\n */\nexport function withBuilder<C extends new (...args: any[]) => any>(\n  ctor: C,\n): C & { builder(): BuilderOf<InstanceType<C>> } {\n  attachBuilder(ctor)\n  return ctor as C & { builder(): BuilderOf<InstanceType<C>> }\n}\n"],"mappings":"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"}
+{"version":3,"file":"decorators.mjs","names":[],"sources":["../../src/core/decorators.ts"],"sourcesContent":["import 'reflect-metadata'\nimport { METADATA, Scope, type BuilderOf, type ServiceOptions } from './interfaces'\nimport { Container, type KickJsRegistry } from './container'\nimport {\n  setClassMeta,\n  setMethodMeta,\n  pushClassMeta,\n  pushMethodMeta,\n  setInMetaMap,\n  setInMetaRecord,\n} from './metadata'\n\n// ── Decorator Registration System ───────────────────────────────────────\n// Decorators execute at class-definition time (module load). The Container\n// may not exist yet when the first decorator fires. We queue registrations\n// and flush them on first Container.getInstance() call.\n//\n// `allRegistrations` is a persistent registry that survives Container.reset().\n// On reset (HMR), all previously decorated classes are re-registered on the\n// fresh container. This ensures @Service, @Controller, @Repository, etc.\n// all survive HMR without manual re-registration.\n\ntype PendingRegistration = { target: any; scope: Scope }\nconst pendingRegistrations: PendingRegistration[] = []\n// Keyed by class name to prevent memory leaks during HMR — new class with\n// the same name replaces the old entry instead of accumulating references.\nconst allRegistrations = new Map<string, { target: any; scope: Scope }>()\nlet containerRef: any = null\n\nfunction flushPending(container: any): void {\n  containerRef = container\n  for (const { target, scope } of pendingRegistrations) {\n    if (!container.has(target)) {\n      container.register(target, target, scope)\n    }\n  }\n  pendingRegistrations.length = 0\n}\n\n// Wire up synchronously — Container._onReady is called on first getInstance()\nContainer._onReady = flushPending\n\n// On Container.reset(), update containerRef and replay ALL decorator\n// registrations on the fresh container. This handles HMR where the container\n// is wiped but not all decorated modules are re-evaluated.\nContainer._onReset = (container: any) => {\n  containerRef = container\n  for (const [, { target, scope }] of allRegistrations) {\n    if (!container.has(target)) {\n      container.register(target, target, scope)\n    }\n  }\n}\n\n// ── Class Decorators ────────────────────────────────────────────────────\n\nfunction registerInContainer(target: any, scope: Scope): void {\n  setClassMeta(METADATA.INJECTABLE, true, target)\n  setClassMeta(METADATA.SCOPE, scope, target)\n\n  // Track in persistent registry — survives Container.reset() for HMR replay.\n  // Keyed by name so HMR class re-creation replaces the old entry.\n  const name = target.name || String(target)\n  allRegistrations.set(name, { target, scope })\n\n  if (containerRef) {\n    // Container already initialized — register immediately\n    if (!containerRef.has(target)) {\n      containerRef.register(target, target, scope)\n    }\n  } else {\n    // Container not ready yet — queue for later\n    pendingRegistrations.push({ target, scope })\n  }\n}\n\n/** Mark a class as injectable with lifecycle scope */\nexport function Injectable(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'injectable', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/** Mark a class as a service (semantic alias for Injectable) */\nexport function Service(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'service', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/** Mark a class as a generic managed component */\nexport function Component(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'component', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/** Mark a class as a repository */\nexport function Repository(options?: ServiceOptions): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'repository', target)\n    registerInContainer(target, options?.scope ?? Scope.SINGLETON)\n  }\n}\n\n/**\n * Mark a class as an HTTP controller and register it in the DI container.\n *\n * Route prefixes are defined by the module's `routes().path` — the single\n * source of truth for where routes mount. The legacy\n * `@Controller('/path')` parameter was removed in v4; if your code\n * still passes a string, see `docs/guide/migration-v3-to-v4.md` for\n * the rename map.\n */\nexport function Controller(): ClassDecorator {\n  return (target: any) => {\n    setClassMeta(METADATA.CLASS_KIND, 'controller', target)\n    registerInContainer(target, Scope.SINGLETON)\n  }\n}\n\n// ── Method Decorators ───────────────────────────────────────────────────\n\n/** Mark a method as a lifecycle hook called after instantiation */\nexport function PostConstruct(): MethodDecorator {\n  return (target, propertyKey) => {\n    setClassMeta(METADATA.POST_CONSTRUCT, propertyKey, target)\n  }\n}\n\n// ── Injection Decorators (property + constructor parameter) ─────────────\n\n/**\n * A decorator that's valid as either a property decorator OR a\n * constructor-parameter decorator. forinda/kick-js#235 §2 — `@Autowired`\n * and `@Inject` previously diverged at the type level (property-only\n * vs parameter-only) and adopters who picked the wrong name for the\n * position got a cryptic TS1240 error. Both names now accept either\n * position and route to the correct metadata bucket at runtime.\n */\nexport interface PropertyOrParameterDecorator {\n  /** Property decorator form — `@Autowired(TOKEN) private foo!: Foo`. */\n  (target: object, propertyKey: string | symbol): void\n  /** Constructor-parameter form — `constructor(@Inject(TOKEN) foo: Foo) {}`. */\n  (target: object, propertyKey: string | symbol | undefined, parameterIndex: number): void\n}\n\nfunction applyInjection(\n  token: unknown,\n  target: object,\n  propertyKey: string | symbol | undefined,\n  parameterIndex: number | undefined,\n): void {\n  // Legacy parameter decorators receive 3 args (target, propertyKey,\n  // parameterIndex); property decorators receive 2 (target, propertyKey).\n  // The 3rd-arg-number-vs-undefined check is the canonical position\n  // detection in TypeScript's legacy decorator runtime.\n  if (typeof parameterIndex === 'number') {\n    setInMetaRecord(METADATA.INJECT, target, parameterIndex, token)\n    return\n  }\n  if (propertyKey != null) {\n    // `target` for a property decorator on a non-static field is the\n    // class prototype; the AUTOWIRED bucket is keyed off the prototype\n    // identity at resolution time, so pass it through unchanged.\n    setInMetaMap(METADATA.AUTOWIRED, target, propertyKey as string, token)\n  }\n}\n\n/**\n * Inject a dependency. Works in two positions:\n *\n * - **Property decorator** — `@Autowired(TOKEN) private repo!: UserRepo`.\n *   Resolved lazily from the container the first time the property is\n *   read.\n * - **Constructor parameter decorator** — `constructor(@Autowired(TOKEN) repo: UserRepo) {}`.\n *   Resolved at instantiation; injected into the ctor call.\n *\n * `@Inject` is the same function under another name — they share\n * runtime + types so the two names are interchangeable. Pick whichever\n * reads better at the call site.\n */\nexport function Autowired(token?: unknown): PropertyOrParameterDecorator {\n  return ((\n    target: object,\n    propertyKey: string | symbol | undefined,\n    parameterIndex?: number,\n  ): void => {\n    applyInjection(token, target, propertyKey, parameterIndex)\n  }) as PropertyOrParameterDecorator\n}\n\n/**\n * Inject a dependency by token. Same shape as {@link Autowired} —\n * works as either a property decorator or a constructor-parameter\n * decorator. Pick whichever name reads better at the call site.\n *\n * ## Typed string-literal overload\n *\n * When called with a string literal that matches a key of the\n * augmented `KickJsRegistry`, TypeScript narrows the parameter type\n * to the registered type. Typo'd literals become compile errors\n * (the string isn't `keyof KickJsRegistry`). Class identities and\n * `InjectionToken<T>` keep working unchanged via the second overload.\n *\n * @example\n * ```ts\n * import { Service, Inject } from '@forinda/kickjs'\n * import type { PrismaClient } from '@prisma/client'\n *\n * `@Service()`\n * class UserRepo {\n *   constructor(@Inject('kick/prisma/Client') private db: PrismaClient) {}\n *   // OR property form, same decorator:\n *   @Inject('kick/prisma/Client') private db2!: PrismaClient\n * }\n * ```\n *\n * After `kick typegen` runs, the literal autocompletes from the\n * registry and a typo (`@Inject('kick/prisma/Cleint')`) becomes a\n * TS2345 error.\n */\nexport function Inject<K extends keyof KickJsRegistry & string>(\n  token: K,\n): PropertyOrParameterDecorator\nexport function Inject(token?: unknown): PropertyOrParameterDecorator\nexport function Inject(token?: unknown): PropertyOrParameterDecorator {\n  return ((\n    target: object,\n    propertyKey: string | symbol | undefined,\n    parameterIndex?: number,\n  ): void => {\n    applyInjection(token, target, propertyKey, parameterIndex)\n  }) as PropertyOrParameterDecorator\n}\n\n/**\n * Global ambient registry of typed environment variables, populated by\n * `kick typegen` from the project's env schema (typically\n * `src/env.ts`'s `export default defineEnv(...)`).\n *\n * Empty by default — declarations come from `.kickjs/types/env.ts`\n * generated alongside the rest of the typegen output. Once populated,\n * `@Value('PORT')` autocompletes the key, type-checks the default\n * value, and `process.env.PORT` is also typed via the parallel\n * `NodeJS.ProcessEnv` augmentation in the same generated file.\n */\ndeclare global {\n  // eslint-disable-next-line @typescript-eslint/no-empty-object-type\n  interface KickEnv {}\n}\n\n/** A string key known to the typed env registry (`never` until typegen runs) */\nexport type EnvKey = keyof KickEnv & string\n\n/**\n * Look up the type of a typed env entry.\n *\n * Decorators can't propagate the property type from the key, so users\n * still need to write the property's type — but `Env<K>` lets them\n * derive it from `KickEnv` instead of duplicating the schema:\n *\n * ```ts\n * @Service()\n * class MyService {\n *   @Value('PORT')\n *   private port!: Env<'PORT'>  // → number, narrowed from KickEnv['PORT']\n * }\n * ```\n */\nexport type Env<K extends EnvKey = EnvKey> = KickEnv[K]\n\n/**\n * Constraint that allows any string when the typed env registry is\n * empty (no `kick typegen` has run yet, so existing code with raw\n * string keys keeps working) but locks the argument down to known\n * `EnvKey` literals once the registry is populated.\n *\n * Implementation: when `EnvKey` is `never`, the conditional resolves\n * to the user's `K`, accepting anything. Once typegen has populated\n * `KickEnv`, `EnvKey` becomes a real union and the conditional forces\n * `K` to be assignable to it.\n */\ntype ValueKey<K extends string> = [EnvKey] extends [never] ? K : K & EnvKey\n\n/**\n * Inject an environment variable value. Evaluated lazily so the env\n * is available at access time, not at decoration time.\n *\n * If no default is provided and the env var is missing, throws at access time\n * to catch misconfiguration early instead of returning undefined.\n *\n * Uses metadata + instance getter to work correctly with `useDefineForClassFields`.\n *\n * Type-safety:\n * - Without `kick typegen` run, any string key is accepted (back-compat).\n * - After typegen, `KickEnv` is populated and unknown keys become a tsc\n *   error. The optional `defaultValue` is type-checked against the\n *   schema's inferred type for that key.\n */\nexport function Value<K extends string>(\n  envKey: ValueKey<K>,\n  defaultValue?: K extends EnvKey ? KickEnv[K] : unknown,\n): PropertyDecorator {\n  return (target, propertyKey) => {\n    setInMetaMap(METADATA.VALUE, target, propertyKey as string, { envKey, defaultValue })\n  }\n}\n\n// ── @Asset — typed asset path injection (assets-plan.md PR 3+) ─────────\n\nimport type { KickAssets } from './assets'\n\n/**\n * Flatten the nested `KickAssets` augmentation (typegen-emitted in\n * PR 4) into a string-literal union of dot/slash-joined paths.\n *\n * `interface KickAssets { mails: { welcome: () => string; orders: {\n * confirmation: () => string } } }` becomes\n * `'mails/welcome' | 'mails/orders/confirmation'`.\n *\n * Returns `never` when `KickAssets` is empty (no typegen has run yet)\n * so `AssetKeyArg` falls through to accept any string.\n */\ntype FlattenAssets<T, Prefix extends string = ''> = {\n  [K in keyof T & string]: T[K] extends () => string\n    ? `${Prefix}${K}`\n    : T[K] extends Record<string, unknown>\n      ? FlattenAssets<T[K], `${Prefix}${K}/`>\n      : never\n}[keyof T & string]\n\n/** Flat union of every known `<namespace>/<key>` path. */\nexport type AssetKey = FlattenAssets<KickAssets>\n\n/**\n * Constraint mirroring `ValueKey<K>` — accepts any string when\n * `AssetKey` is `never` (back-compat for adopters who haven't run\n * `kick typegen` yet) but locks the argument to known literals once\n * the typegen-augmented `KickAssets` interface is populated.\n */\ntype AssetKeyArg<K extends string> = [AssetKey] extends [never] ? K : K & AssetKey\n\n/**\n * Inject the resolved file-system path for a typed asset. Mirrors\n * `@Value`'s lazy-getter pattern — the asset is resolved on every\n * property access, NOT at class instantiation, so:\n *\n * - Tests can swap fixtures + clear the cache without re-instantiating\n *   the consuming class.\n * - The first access cost is paid once per process (the manifest cache\n *   in `core/assets.ts` makes subsequent calls cheap).\n *\n * Type-safety:\n *\n * - Without typegen, any string key is accepted (back-compat — same\n *   trick as `@Value`).\n * - After typegen, `KickAssets` is populated and `AssetKey` is a\n *   union of every flattened `<namespace>/<key>` path. Unknown keys\n *   become a TS error.\n *\n * @example\n * ```ts\n * import { Service, Asset } from '@forinda/kickjs'\n *\n * `@Service()`\n * class MailService {\n *   `@Asset('mails/welcome')`\n *   private welcomeTemplate!: string\n *\n *   send(user: User) {\n *     return ejs.renderFile(this.welcomeTemplate, { user })\n *   }\n * }\n * ```\n */\nexport function Asset<K extends string>(assetKey: AssetKeyArg<K>): PropertyDecorator {\n  return (target, propertyKey) => {\n    setInMetaMap(METADATA.ASSET, target, propertyKey as string, { assetKey })\n  }\n}\n\n// ── HTTP Route Decorators ───────────────────────────────────────────────\n\nexport interface RouteDefinition {\n  method: string\n  path: string\n  handlerName: string\n  validation?: {\n    /** JSON Schema object for validating the request body */\n    body?: any\n    /** JSON Schema object for validating query parameters */\n    query?: any\n    /** JSON Schema object for validating URL params */\n    params?: any\n    /** Schema name in OpenAPI components/schemas for the request body. Auto-generated from handler name if omitted. */\n    name?: string\n  }\n}\n\nfunction createRouteDecorator(method: string) {\n  return (path?: string, validation?: RouteDefinition['validation']): MethodDecorator => {\n    return (target, propertyKey) => {\n      pushClassMeta<RouteDefinition>(METADATA.ROUTES, target.constructor, {\n        method,\n        path: path || '/',\n        handlerName: propertyKey as string,\n        validation,\n      })\n    }\n  }\n}\n\nexport const Get = createRouteDecorator('GET')\nexport const Post = createRouteDecorator('POST')\nexport const Put = createRouteDecorator('PUT')\nexport const Delete = createRouteDecorator('DELETE')\nexport const Patch = createRouteDecorator('PATCH')\n\n// ── Query Params Decorator ─────────────────────────────────────────────\n\nexport interface ApiQueryParamsConfig {\n  /** Fields that can be used in filter queries (e.g., `?filter=status:eq:active`) */\n  filterable?: string[]\n  /** Fields that can be used in sort queries (e.g., `?sort=createdAt:desc`) */\n  sortable?: string[]\n  /** Fields that are searched with the `?q=` parameter */\n  searchable?: string[]\n}\n\n/**\n * Column-object-based query params config (e.g., from DrizzleQueryParamsConfig).\n * `Object.keys()` is used to derive field names for OpenAPI docs.\n */\nexport interface ColumnApiQueryParamsConfig {\n  columns: Record<string, any>\n  sortable?: Record<string, any>\n  searchColumns?: any[]\n  [key: string]: any\n}\n\n/**\n * Normalize a query params config to the string-based ApiQueryParamsConfig.\n * Handles both string-based and column-object-based configs.\n */\nexport function normalizeApiQueryParamsConfig(\n  config: ApiQueryParamsConfig | ColumnApiQueryParamsConfig,\n): ApiQueryParamsConfig {\n  if ('columns' in config && config.columns && typeof config.columns === 'object') {\n    return {\n      filterable: Object.keys(config.columns),\n      sortable: config.sortable ? Object.keys(config.sortable) : undefined,\n      searchable: config.searchColumns\n        ? config.searchColumns.map((col: any) => col?.name ?? '').filter(Boolean)\n        : undefined,\n    }\n  }\n  return config as ApiQueryParamsConfig\n}\n\n/**\n * Document the query parameters accepted by a GET endpoint.\n * Used by SwaggerAdapter to generate `filter`, `sort`, `page`, `limit`, and `q` params\n * in the OpenAPI spec, with descriptions listing the allowed fields.\n *\n * Accepts both string-based configs and column-object configs (e.g., DrizzleQueryParamsConfig).\n *\n * @example\n * ```ts\n * // String-based\n * @ApiQueryParams({\n *   filterable: ['status', 'category', 'price'],\n *   sortable: ['name', 'createdAt', 'price'],\n *   searchable: ['name', 'description'],\n * })\n *\n * // Column-object-based (Drizzle)\n * @ApiQueryParams(TASK_QUERY_CONFIG)\n * ```\n */\nexport function ApiQueryParams(\n  config: ApiQueryParamsConfig | ColumnApiQueryParamsConfig,\n): MethodDecorator {\n  return (target, propertyKey) => {\n    const normalized = normalizeApiQueryParamsConfig(config)\n    setMethodMeta(METADATA.QUERY_PARAMS, normalized, target.constructor, propertyKey as string)\n  }\n}\n\n// ── Middleware Decorators ───────────────────────────────────────────────\n\n/**\n * Middleware handler function.\n * Generic `TCtx` defaults to `any` — import `RequestContext` from\n * `@forinda/kickjs` for full type safety:\n *\n * ```ts\n * import type { MiddlewareHandler } from '@forinda/kickjs'\n * import type { RequestContext } from '@forinda/kickjs'\n *\n * const auth: MiddlewareHandler<RequestContext> = (ctx, next) => {\n *   ctx.body  // fully typed\n *   next()\n * }\n * ```\n */\nexport type MiddlewareHandler<TCtx = any> = (ctx: TCtx, next: () => void) => void | Promise<void>\n\n/** Attach middleware handlers to a class or method */\nexport function Middleware(...handlers: MiddlewareHandler[]): ClassDecorator & MethodDecorator {\n  return (target: any, propertyKey?: string | symbol) => {\n    if (propertyKey) {\n      pushMethodMeta(\n        METADATA.METHOD_MIDDLEWARES,\n        target.constructor,\n        propertyKey as string,\n        ...handlers,\n      )\n    } else {\n      pushClassMeta(METADATA.CLASS_MIDDLEWARES, target, ...handlers)\n    }\n  }\n}\n\n// ── File Upload Decorator ───────────────────────────────────────────────\n\n/**\n * File filter — accepts short extensions ('jpg'), full MIME types ('image/jpeg'),\n * wildcards ('image/*'), or a function `(mimetype, filename) => boolean` for full control.\n */\nexport type FileTypeFilter = string[] | ((mimetype: string, filename: string) => boolean)\n\n/**\n * Shared upload options used by both the `@FileUpload` decorator and the\n * `upload.single()` / `upload.array()` / `upload.none()` middleware.\n */\nexport interface BaseUploadOptions {\n  /** Max file size in bytes (default: 5MB) */\n  maxSize?: number\n  /**\n   * Allowed file types:\n   * - **string[]** — short extensions ('jpg'), full MIME types ('image/jpeg'), or wildcards ('image/*')\n   * - **function** — `(mimetype, filename) => boolean` for full control\n   */\n  allowedTypes?: FileTypeFilter\n  /** Extend the built-in extension-to-MIME map */\n  customMimeMap?: Record<string, string>\n}\n\nexport interface FileUploadConfig extends BaseUploadOptions {\n  mode: 'single' | 'array' | 'none'\n  /** Form field name (default: 'file') */\n  fieldName?: string\n  /** Max files for array mode (default: 10) */\n  maxCount?: number\n}\n\n/** Configure file upload handling for a controller method */\nexport function FileUpload(config: FileUploadConfig): MethodDecorator {\n  return (target, propertyKey) => {\n    setMethodMeta(METADATA.FILE_UPLOAD, config, target.constructor, propertyKey as string)\n  }\n}\n\n// ── Builder Decorator ───────────────────────────────────────────────────\n\nfunction attachBuilder(target: any): void {\n  setClassMeta(METADATA.BUILDER, true, target)\n  target.builder = function () {\n    const props: Record<string, any> = {}\n    const proxy: any = new Proxy(\n      {},\n      {\n        get(_, key) {\n          if (key === 'build') {\n            return () => Object.assign(new target(), props)\n          }\n          return (value: any) => {\n            props[key as string] = value\n            return proxy\n          }\n        },\n      },\n    )\n    return proxy\n  }\n}\n\n/**\n * Add a static `builder()` method for fluent construction.\n *\n * Legacy decorators cannot widen the class type, so by default the\n * caller sees the unmodified shape. Opt into typing by adding a single\n * `declare static` line:\n *\n * ```ts\n * @Builder\n * class UserDto {\n *   name!: string\n *   email!: string\n *   declare static readonly builder: () => BuilderOf<UserDto>\n * }\n * ```\n *\n * `readonly` keeps SonarQube's `typescript:S1444` quiet — the runtime\n * assigns `target.builder` once at decoration time and never again.\n *\n * If you'd rather not write the `declare`, use `withBuilder()` instead —\n * same runtime, types inferred automatically.\n */\nexport function Builder(target: any): void {\n  attachBuilder(target)\n}\n\n/**\n * Factory variant of `@Builder`. Wraps the class with the same runtime\n * and returns it intersected with `{ builder(): BuilderOf<T> }` so the\n * static is fully typed without any `declare` boilerplate.\n *\n * ```ts\n * class UserDtoBase {\n *   name!: string\n *   email!: string\n * }\n * export const UserDto = withBuilder(UserDtoBase)\n * export type UserDto = InstanceType<typeof UserDto>\n *\n * UserDto.builder().name('Alice').email('a@b.com').build() // fully typed\n * ```\n */\nexport function withBuilder<C extends new (...args: any[]) => any>(\n  ctor: C,\n): C & { builder(): BuilderOf<InstanceType<C>> } {\n  attachBuilder(ctor)\n  return ctor as C & { builder(): BuilderOf<InstanceType<C>> }\n}\n"],"mappings":"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"}

package/dist/core/errors.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/interfaces.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/logger.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/path.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/plugin.d.mts

@@ -1,3 +1,3 @@
 
-import { t as KickPlugin } from "../plugin-JMkG7soG.mjs";
+import { t as KickPlugin } from "../plugin-NMHVmDRF.mjs";
 export { KickPlugin };

package/dist/core/plugin.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/core/reactivity.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *

package/dist/{core-DvTHNOay.mjs → core-CJKmg8QR.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v5.6.0
+ * @forinda/kickjs v5.7.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,6 +8,6 @@
  *
  * @license MIT
  */
-import"./container-D0v17gF8.mjs";import{METADATA}from"./core/interfaces.mjs";import"./core/logger.mjs";import{c as pushClassMeta,l as pushMethodMeta}from"./metadata-IHiynOCv.mjs";import"./core/decorators.mjs";import"./core/cron.mjs";import"./core/cache.mjs";import"reflect-metadata";const mergeConfig$2=(defaults={},overrides={})=>({...defaults,...overrides}),composeName$2=(base,scope)=>`${base}:${scope}`;function defineModule(options){if(typeof options!=`object`||!options)throw TypeError(`defineModule: options must be an object literal. See architecture.md §21 for the spec shape.`);if(typeof options.name!=`string`||options.name.length===0){let got=typeof options.name==`string`?`""`:typeof options.name;throw TypeError(`defineModule: options.name must be a non-empty string (got ${got}). Module names appear in diagnostics and \`.scoped()\` namespacing — anonymous modules make cycle / missing-dep errors hard to localize.`)}if(typeof options.build!=`function`)throw TypeError(`defineModule(${options.name}): options.build is required and must be a function (got ${typeof options.build}). The build function returns the AppModule shape — register() / routes() / contributors() — wired with the resolved config.`);let buildSync=(instanceName,scoped,overrides)=>{let config=mergeConfig$2(options.defaults,overrides),built=options.build(config,{name:instanceName,scoped});return Object.defineProperty(built,`__moduleName`,{value:instanceName,enumerable:!1,writable:!1,configurable:!1}),built},factory=(config=>buildSync(options.name,!1,config));return factory.scoped=(scopeName,config)=>buildSync(composeName$2(options.name,scopeName),!0,config),Object.defineProperty(factory,`definition`,{value:Object.freeze({...options}),writable:!1,enumerable:!0,configurable:!1}),factory}var ModuleList=class extends Array{mount(module){return this.push(module),this}};function defineModules(...initial){let list=new ModuleList;for(let entry of initial)list.push(entry);return list}var MutableModuleRegistry=class{entries=[];mount(module){this.entries.push(module)}},CircuitOpenError=class extends Error{constructor(breakerName){super(`Circuit breaker "${breakerName}" is open — request rejected`),this.breakerName=breakerName,this.name=`CircuitOpenError`}},CircuitBreaker=class{state=`closed`;failures=0;successes=0;halfOpenAttempts=0;lastFailure;openedAt;failureThreshold;resetTimeout;halfOpenMax;constructor(name,options){this.name=name,this.failureThreshold=options.failureThreshold,this.resetTimeout=options.resetTimeout,this.halfOpenMax=options.halfOpenMax??1}async execute(fn){if(this.maybeTransitionToHalfOpen(),this.state===`open`||this.state===`half_open`&&this.halfOpenAttempts>=this.halfOpenMax)throw new CircuitOpenError(this.name);this.state===`half_open`&&this.halfOpenAttempts++;try{let result=await fn();return this.onSuccess(),result}catch(error){throw this.onFailure(),error}}getState(){return this.maybeTransitionToHalfOpen(),this.state}getStats(){return this.maybeTransitionToHalfOpen(),{failures:this.failures,successes:this.successes,state:this.state,...this.lastFailure?{lastFailure:this.lastFailure}:{}}}reset(){this.state=`closed`,this.failures=0,this.successes=0,this.halfOpenAttempts=0,this.lastFailure=void 0,this.openedAt=void 0}onSuccess(){this.state===`half_open`&&(this.state=`closed`,this.failures=0,this.halfOpenAttempts=0,this.openedAt=void 0),this.successes++}onFailure(){this.failures++,this.lastFailure=new Date,this.state===`half_open`?(this.state=`open`,this.openedAt=Date.now(),this.halfOpenAttempts=0):this.state===`closed`&&this.failures>=this.failureThreshold&&(this.state=`open`,this.openedAt=Date.now())}maybeTransitionToHalfOpen(){this.state===`open`&&this.openedAt!=null&&Date.now()-this.openedAt>=this.resetTimeout&&(this.state=`half_open`,this.halfOpenAttempts=0)}};function defineContextDecorator(spec){if(typeof spec!=`object`||!spec)throw TypeError(`defineContextDecorator: spec must be an object literal. See architecture.md §20.4 for the spec shape.`);if(typeof spec.key!=`string`||spec.key.length===0){let got=typeof spec.key==`string`?`""`:typeof spec.key;throw TypeError(`defineContextDecorator: spec.key must be a non-empty string (got ${got}). Pick a name that matches a key declared on \`ContextMeta\` (or one of the framework keys).`)}if(typeof spec.resolve!=`function`)throw TypeError(`defineContextDecorator(${spec.key}): spec.resolve is required and must be a function (got ${typeof spec.resolve}). Each contributor needs a resolver that produces the value to write into ctx.set(${JSON.stringify(spec.key)}, …).`);if(spec.onError!==void 0&&typeof spec.onError!=`function`)throw TypeError(`defineContextDecorator(${spec.key}): spec.onError must be a function when provided (got ${typeof spec.onError}).`);if(spec.dependsOn!==void 0&&!Array.isArray(spec.dependsOn))throw TypeError(`defineContextDecorator(${spec.key}): spec.dependsOn must be an array when provided (got ${typeof spec.dependsOn}).`);if(Array.isArray(spec.dependsOn)&&spec.dependsOn.some(dep=>typeof dep!=`string`||dep.length===0))throw TypeError(`defineContextDecorator(${spec.key}): spec.dependsOn entries must be non-empty strings.`);let definedAt=Error().stack,defaults=Object.freeze({...spec.paramDefaults??{}}),sharedDeps=Object.freeze({...spec.deps??{}}),sharedDependsOn=Object.freeze([...spec.dependsOn??[]]),sharedOptional=spec.optional??!1,buildRegistration=params=>{let frozenParams=Object.freeze({...params}),onError=spec.onError?(err,ctx)=>spec.onError(err,ctx,frozenParams):void 0;return Object.freeze({key:spec.key,deps:sharedDeps,dependsOn:sharedDependsOn,optional:sharedOptional,onError,resolve:(ctx,deps)=>spec.resolve(ctx,deps,frozenParams),definedAt})},defaultRegistration=buildRegistration({...defaults}),isDecoratorCall=args=>args.length===0?!1:args.length>=2||typeof args[0]==`function`,applyAsDecorator=(registration,target,propertyKey)=>{if(propertyKey===void 0)pushClassMeta(METADATA.CLASS_CONTRIBUTORS,target,registration);else{let constructor=target.constructor;pushMethodMeta(METADATA.METHOD_CONTRIBUTORS,constructor,String(propertyKey),registration)}},isPlainObject=value=>{let proto=Object.getPrototypeOf(value);return proto===Object.prototype||proto===null},mergeParams=override=>{if(override===void 0)return{...defaults};if(typeof override!=`object`||!override||Array.isArray(override)||!isPlainObject(override)){let got=override===null?`null`:Array.isArray(override)?`array`:typeof override==`object`?`instance of ${override.constructor?.name??`unknown class`}`:typeof override;throw TypeError(`defineContextDecorator(${spec.key}): factory call requires a plain object literal, got ${got}. Class instances and built-ins (Map, Date, etc) silently spread to empty objects — call the decorator with a spread object literal instead, e.g. \`MyDecorator({ ...someInstance })\`.`)}return{...defaults,...override}};function decoratorOrFactory(...args){if(isDecoratorCall(args)){let[target,propertyKey]=args;applyAsDecorator(defaultRegistration,target,propertyKey);return}let registration=buildRegistration(mergeParams(args[0]));return(target,propertyKey)=>{applyAsDecorator(registration,target,propertyKey)}}Object.defineProperty(decoratorOrFactory,`name`,{value:`ContextDecorator(${spec.key})`,writable:!1,enumerable:!1,configurable:!0});let decorator=Object.assign(decoratorOrFactory,{registration:defaultRegistration,with:params=>({registration:buildRegistration(mergeParams(params))})});return Object.freeze(decorator)}var MissingContributorError=class extends Error{key;dependent;route;dependentDefinedAt;constructor(key,dependent,route,dependentDefinedAt){let where=route?` on route ${route}`:``,declaredAt=formatDeclaredAt(dependentDefinedAt);super(`Missing context contributor '${key}' required by '${dependent}'${where}${declaredAt}`),this.name=`MissingContributorError`,this.key=key,this.dependent=dependent,this.route=route,this.dependentDefinedAt=dependentDefinedAt}};function formatDeclaredAt(stack){if(!stack)return``;let lines=stack.split(`
+import"./container-COmj1vM3.mjs";import{METADATA}from"./core/interfaces.mjs";import"./core/logger.mjs";import{c as pushClassMeta,l as pushMethodMeta}from"./metadata-D9F5Lm-z.mjs";import"./core/decorators.mjs";import"./core/cron.mjs";import"./core/cache.mjs";import"reflect-metadata";const mergeConfig$2=(defaults={},overrides={})=>({...defaults,...overrides}),composeName$2=(base,scope)=>`${base}:${scope}`;function defineModule(options){if(typeof options!=`object`||!options)throw TypeError(`defineModule: options must be an object literal. See architecture.md §21 for the spec shape.`);if(typeof options.name!=`string`||options.name.length===0){let got=typeof options.name==`string`?`""`:typeof options.name;throw TypeError(`defineModule: options.name must be a non-empty string (got ${got}). Module names appear in diagnostics and \`.scoped()\` namespacing — anonymous modules make cycle / missing-dep errors hard to localize.`)}if(typeof options.build!=`function`)throw TypeError(`defineModule(${options.name}): options.build is required and must be a function (got ${typeof options.build}). The build function returns the AppModule shape — register() / routes() / contributors() — wired with the resolved config.`);let buildSync=(instanceName,scoped,overrides)=>{let config=mergeConfig$2(options.defaults,overrides),built=options.build(config,{name:instanceName,scoped});return Object.defineProperty(built,`__moduleName`,{value:instanceName,enumerable:!1,writable:!1,configurable:!1}),built},factory=(config=>buildSync(options.name,!1,config));return factory.scoped=(scopeName,config)=>buildSync(composeName$2(options.name,scopeName),!0,config),Object.defineProperty(factory,`definition`,{value:Object.freeze({...options}),writable:!1,enumerable:!0,configurable:!1}),factory}var ModuleList=class extends Array{mount(module){return this.push(module),this}};function defineModules(...initial){let list=new ModuleList;for(let entry of initial)list.push(entry);return list}var MutableModuleRegistry=class{entries=[];mount(module){this.entries.push(module)}},CircuitOpenError=class extends Error{constructor(breakerName){super(`Circuit breaker "${breakerName}" is open — request rejected`),this.breakerName=breakerName,this.name=`CircuitOpenError`}},CircuitBreaker=class{state=`closed`;failures=0;successes=0;halfOpenAttempts=0;lastFailure;openedAt;failureThreshold;resetTimeout;halfOpenMax;constructor(name,options){this.name=name,this.failureThreshold=options.failureThreshold,this.resetTimeout=options.resetTimeout,this.halfOpenMax=options.halfOpenMax??1}async execute(fn){if(this.maybeTransitionToHalfOpen(),this.state===`open`||this.state===`half_open`&&this.halfOpenAttempts>=this.halfOpenMax)throw new CircuitOpenError(this.name);this.state===`half_open`&&this.halfOpenAttempts++;try{let result=await fn();return this.onSuccess(),result}catch(error){throw this.onFailure(),error}}getState(){return this.maybeTransitionToHalfOpen(),this.state}getStats(){return this.maybeTransitionToHalfOpen(),{failures:this.failures,successes:this.successes,state:this.state,...this.lastFailure?{lastFailure:this.lastFailure}:{}}}reset(){this.state=`closed`,this.failures=0,this.successes=0,this.halfOpenAttempts=0,this.lastFailure=void 0,this.openedAt=void 0}onSuccess(){this.state===`half_open`&&(this.state=`closed`,this.failures=0,this.halfOpenAttempts=0,this.openedAt=void 0),this.successes++}onFailure(){this.failures++,this.lastFailure=new Date,this.state===`half_open`?(this.state=`open`,this.openedAt=Date.now(),this.halfOpenAttempts=0):this.state===`closed`&&this.failures>=this.failureThreshold&&(this.state=`open`,this.openedAt=Date.now())}maybeTransitionToHalfOpen(){this.state===`open`&&this.openedAt!=null&&Date.now()-this.openedAt>=this.resetTimeout&&(this.state=`half_open`,this.halfOpenAttempts=0)}};function defineContextDecorator(spec){if(typeof spec!=`object`||!spec)throw TypeError(`defineContextDecorator: spec must be an object literal. See architecture.md §20.4 for the spec shape.`);if(typeof spec.key!=`string`||spec.key.length===0){let got=typeof spec.key==`string`?`""`:typeof spec.key;throw TypeError(`defineContextDecorator: spec.key must be a non-empty string (got ${got}). Pick a name that matches a key declared on \`ContextMeta\` (or one of the framework keys).`)}if(typeof spec.resolve!=`function`)throw TypeError(`defineContextDecorator(${spec.key}): spec.resolve is required and must be a function (got ${typeof spec.resolve}). Each contributor needs a resolver that produces the value to write into ctx.set(${JSON.stringify(spec.key)}, …).`);if(spec.onError!==void 0&&typeof spec.onError!=`function`)throw TypeError(`defineContextDecorator(${spec.key}): spec.onError must be a function when provided (got ${typeof spec.onError}).`);if(spec.dependsOn!==void 0&&!Array.isArray(spec.dependsOn))throw TypeError(`defineContextDecorator(${spec.key}): spec.dependsOn must be an array when provided (got ${typeof spec.dependsOn}).`);if(Array.isArray(spec.dependsOn)&&spec.dependsOn.some(dep=>typeof dep!=`string`||dep.length===0))throw TypeError(`defineContextDecorator(${spec.key}): spec.dependsOn entries must be non-empty strings.`);let definedAt=Error().stack,defaults=Object.freeze({...spec.paramDefaults??{}}),sharedDeps=Object.freeze({...spec.deps??{}}),sharedDependsOn=Object.freeze([...spec.dependsOn??[]]),sharedOptional=spec.optional??!1,buildRegistration=params=>{let frozenParams=Object.freeze({...params}),onError=spec.onError?(err,ctx)=>spec.onError(err,ctx,frozenParams):void 0;return Object.freeze({key:spec.key,deps:sharedDeps,dependsOn:sharedDependsOn,optional:sharedOptional,onError,resolve:(ctx,deps)=>spec.resolve(ctx,deps,frozenParams),definedAt})},defaultRegistration=buildRegistration({...defaults}),isDecoratorCall=args=>args.length===0?!1:args.length>=2||typeof args[0]==`function`,applyAsDecorator=(registration,target,propertyKey)=>{if(propertyKey===void 0)pushClassMeta(METADATA.CLASS_CONTRIBUTORS,target,registration);else{let constructor=target.constructor;pushMethodMeta(METADATA.METHOD_CONTRIBUTORS,constructor,String(propertyKey),registration)}},isPlainObject=value=>{let proto=Object.getPrototypeOf(value);return proto===Object.prototype||proto===null},mergeParams=override=>{if(override===void 0)return{...defaults};if(typeof override!=`object`||!override||Array.isArray(override)||!isPlainObject(override)){let got=override===null?`null`:Array.isArray(override)?`array`:typeof override==`object`?`instance of ${override.constructor?.name??`unknown class`}`:typeof override;throw TypeError(`defineContextDecorator(${spec.key}): factory call requires a plain object literal, got ${got}. Class instances and built-ins (Map, Date, etc) silently spread to empty objects — call the decorator with a spread object literal instead, e.g. \`MyDecorator({ ...someInstance })\`.`)}return{...defaults,...override}};function decoratorOrFactory(...args){if(isDecoratorCall(args)){let[target,propertyKey]=args;applyAsDecorator(defaultRegistration,target,propertyKey);return}let registration=buildRegistration(mergeParams(args[0]));return(target,propertyKey)=>{applyAsDecorator(registration,target,propertyKey)}}Object.defineProperty(decoratorOrFactory,`name`,{value:`ContextDecorator(${spec.key})`,writable:!1,enumerable:!1,configurable:!0});let decorator=Object.assign(decoratorOrFactory,{registration:defaultRegistration,with:params=>({registration:buildRegistration(mergeParams(params))})});return Object.freeze(decorator)}var MissingContributorError=class extends Error{key;dependent;route;dependentDefinedAt;constructor(key,dependent,route,dependentDefinedAt){let where=route?` on route ${route}`:``,declaredAt=formatDeclaredAt(dependentDefinedAt);super(`Missing context contributor '${key}' required by '${dependent}'${where}${declaredAt}`),this.name=`MissingContributorError`,this.key=key,this.dependent=dependent,this.route=route,this.dependentDefinedAt=dependentDefinedAt}};function formatDeclaredAt(stack){if(!stack)return``;let lines=stack.split(`
 `);for(let line of lines){let trimmed=line.trim();if(trimmed.startsWith(`at `)&&!trimmed.includes(`context-decorator.`)&&!trimmed.includes(`context-errors.`))return`\n    declared at ${trimmed.replace(/^at /,``)}`}return``}var ContributorCycleError=class extends Error{cycle;route;constructor(cycle,route){let where=route?` on route ${route}`:``;super(`Cycle in context contributors${where}: ${cycle.join(` → `)}`),this.name=`ContributorCycleError`,this.cycle=Object.freeze([...cycle]),this.route=route}},DuplicateContributorError=class extends Error{key;sources;constructor(key,sources){super(`Duplicate context contributor for key '${key}' at the same precedence level. Sources: ${sources.join(`, `)}`),this.name=`DuplicateContributorError`,this.key=key,this.sources=Object.freeze([...sources])}};const PRECEDENCE_ORDER=[`method`,`class`,`module`,`adapter`,`global`];function buildPipeline(sources,options={}){let route=options.route,bySource=new Map;for(let src of PRECEDENCE_ORDER)bySource.set(src,[]);for(let entry of sources)bySource.get(entry.source).push(entry);let winners=new Map;for(let src of PRECEDENCE_ORDER){let rows=bySource.get(src),keysAtThisLevel=new Map;for(let row of rows){let key=row.registration.key,existing=keysAtThisLevel.get(key)??[];existing.push(row),keysAtThisLevel.set(key,existing)}for(let[key,rowsForKey]of keysAtThisLevel){if(rowsForKey.length>1)throw new DuplicateContributorError(key,rowsForKey.map((r,i)=>r.label??`${src}#${i}`));winners.has(key)||winners.set(key,rowsForKey[0])}}let survivors=[...winners.values()].map(r=>r.registration),allKeys=new Set(survivors.map(r=>r.key));for(let reg of survivors)for(let dep of reg.dependsOn)if(!allKeys.has(dep))throw new MissingContributorError(dep,reg.key,route,reg.definedAt);let sorted=topoSort(survivors,route);return Object.freeze({contributors:Object.freeze(sorted),keys:allKeys})}function topoSort(registrations,route){let indegree=new Map,dependents=new Map,byKey=new Map;for(let reg of registrations)indegree.set(reg.key,reg.dependsOn.length),byKey.set(reg.key,reg);for(let reg of registrations)for(let dep of reg.dependsOn){let list=dependents.get(dep)??[];list.push(reg),dependents.set(dep,list)}let queue=[];for(let reg of registrations)indegree.get(reg.key)===0&&queue.push(reg);let sorted=[];for(;queue.length>0;){let node=queue.shift();sorted.push(node);for(let dependent of dependents.get(node.key)??[]){let next=(indegree.get(dependent.key)??0)-1;indegree.set(dependent.key,next),next===0&&queue.push(dependent)}}if(sorted.length!==registrations.length)throw new ContributorCycleError(reconstructCycle$1(registrations.filter(r=>(indegree.get(r.key)??0)>0),byKey),route);return sorted}function reconstructCycle$1(residual,byKey){let residualKeys=new Set(residual.map(r=>r.key)),start=residual[0].key,path=[start],seen=new Set([start]),cursor=start;for(;;){let nextDep=byKey.get(cursor).dependsOn.find(d=>residualKeys.has(d));if(nextDep===void 0)break;if(seen.has(nextDep)){let cycleStart=path.indexOf(nextDep);return[...path.slice(cycleStart),nextDep]}path.push(nextDep),seen.add(nextDep),cursor=nextDep}return path}async function runContributors(options){let{pipeline,ctx,container}=options;for(let reg of pipeline.contributors)await runOne(reg,ctx,container)}async function runOne(reg,ctx,container){let value;try{let deps=resolveDeps(reg,container);value=await reg.resolve(ctx,deps)}catch(err){if(reg.optional)return;if(reg.onError){let replacement=await reg.onError(err,ctx);if(replacement===void 0)return;ctx.set(reg.key,replacement);return}throw err}ctx.set(reg.key,value)}function resolveDeps(reg,container){let out={};for(let[key,token]of Object.entries(reg.deps))out[key]=container.resolve(token);return out}var DuplicateMountNameError=class extends Error{kind;mountName;constructor(kind,mountName){super(`Duplicate ${kind} name '${mountName}' — every ${kind} must declare a unique name`),this.name=`DuplicateMountNameError`,this.kind=kind,this.mountName=mountName}},MissingMountDepError=class extends Error{kind;missing;dependent;constructor(kind,missing,dependent){super(`Missing ${kind} dependency '${missing}' required by '${dependent}' — is the ${kind} installed and named correctly?`),this.name=`MissingMountDepError`,this.kind=kind,this.missing=missing,this.dependent=dependent}},MountCycleError=class extends Error{kind;cycle;constructor(kind,cycle){super(`Cycle in ${kind} dependsOn declarations: ${cycle.join(` → `)}`),this.name=`MountCycleError`,this.kind=kind,this.cycle=Object.freeze([...cycle])}};function mountSort(items,kind){let byName=new Map;for(let item of items){if(byName.has(item.name))throw new DuplicateMountNameError(kind,item.name);byName.set(item.name,item)}let indegree=new Map,dependents=new Map;for(let item of items)indegree.set(item.name,item.dependsOn?.length??0);for(let item of items)for(let dep of item.dependsOn??[]){if(!byName.has(dep))throw new MissingMountDepError(kind,dep,item.name);let list=dependents.get(dep)??[];list.push(item),dependents.set(dep,list)}let queue=[];for(let item of items)indegree.get(item.name)===0&&queue.push(item);let sorted=[];for(;queue.length>0;){let node=queue.shift();sorted.push(node);for(let dependent of dependents.get(node.name)??[]){let next=(indegree.get(dependent.name)??0)-1;indegree.set(dependent.name,next),next===0&&queue.push(dependent)}}if(sorted.length!==items.length)throw new MountCycleError(kind,reconstructCycle(items.filter(it=>(indegree.get(it.name)??0)>0),byName));return sorted}function reconstructCycle(residual,byName){let residualNames=new Set(residual.map(r=>r.name)),start=residual[0].name,path=[start],seen=new Set([start]),cursor=start;for(;;){let nextDep=byName.get(cursor).dependsOn?.find(d=>residualNames.has(d));if(nextDep===void 0)break;if(seen.has(nextDep)){let cycleStart=path.indexOf(nextDep);return[...path.slice(cycleStart),nextDep]}path.push(nextDep),seen.add(nextDep),cursor=nextDep}return path}const mergeConfig$1=(defaults={},overrides={})=>({...defaults,...overrides}),composeName$1=(base,scope)=>`${base}:${scope}`;function definePlugin(options){let buildSync=(instanceName,scoped,overrides)=>{let config=mergeConfig$1(options.defaults,overrides),built=options.build(config,{name:instanceName,scoped});return built.name=instanceName,built},buildAsync=(instanceName,opts)=>{let inner,ensureInner=async container=>{if(inner)return inner;let deps=(opts.inject??[]).map(tok=>container.resolve(tok));return inner=buildSync(instanceName,!1,await opts.useFactory(...deps)),inner};return{name:instanceName,async onReady(container){let built=await ensureInner(container);built.register?.(container),await built.onReady?.(container)},async shutdown(){await inner?.shutdown?.()}}},factory=(config=>buildSync(options.name,!1,config));return factory.scoped=(scopeName,config)=>buildSync(composeName$1(options.name,scopeName),!0,config),factory.async=opts=>buildAsync(options.name,opts),Object.defineProperty(factory,`definition`,{value:Object.freeze({...options})}),factory}const mergeConfig=(defaults={},overrides={})=>({...defaults,...overrides}),composeName=(base,scope)=>`${base}:${scope}`;function defineAdapter(options){let buildSync=(instanceName,scoped,overrides)=>{let config=mergeConfig(options.defaults,overrides),built=options.build(config,{name:instanceName,scoped});return built.name=instanceName,built},buildAsync=(instanceName,opts)=>{let inner;return{name:instanceName,async beforeStart(ctx){let deps=(opts.inject??[]).map(tok=>ctx.container.resolve(tok));inner=buildSync(instanceName,!1,await opts.useFactory(...deps)),await inner.beforeStart?.(ctx)},async afterStart(ctx){await inner?.afterStart?.(ctx)},async shutdown(){await inner?.shutdown?.()},async onHealthCheck(){return await inner?.onHealthCheck?.()??{name:instanceName,status:`up`}}}},factory=(config=>buildSync(options.name,!1,config));return factory.scoped=(scopeName,config)=>buildSync(composeName(options.name,scopeName),!0,config),factory.async=opts=>buildAsync(options.name,opts),Object.defineProperty(factory,`definition`,{value:Object.freeze({...options})}),factory}function defineAugmentation(name,meta){}export{ModuleList as _,MissingMountDepError as a,runContributors as c,DuplicateContributorError as d,MissingContributorError as f,MutableModuleRegistry as g,CircuitOpenError as h,DuplicateMountNameError as i,buildPipeline as l,CircuitBreaker as m,defineAdapter as n,MountCycleError as o,defineContextDecorator as p,definePlugin as r,mountSort as s,defineAugmentation as t,ContributorCycleError as u,defineModules as v,defineModule as y};
-//# sourceMappingURL=core-DvTHNOay.mjs.map
+//# sourceMappingURL=core-CJKmg8QR.mjs.map