@forinda/kickjs 9.0.2 → 9.1.0

package/dist/{route-flag-DEUYr5Br.mjs.map → route-flag-sIYXay3q.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"route-flag-DEUYr5Br.mjs","names":[],"sources":["../src/core/route-flag.ts"],"sourcesContent":["/**\n * Route flags — a named, inheritable fact about a route.\n *\n * A flag carries no behaviour. It records something about the route that any\n * consumer may read: `auth.public`, `csrf.exempt`, `rate.limit`. Auth reads it\n * to skip a contributor, a guard reads it to return early, Swagger reads it to\n * mark a security scheme — none of them needs to know about the others.\n *\n * The rule that makes presence checks safe: a flag resolves to **absent**, or\n * **present with a value**. `@Public.off` on a method removes what the class\n * set, rather than storing something falsy — so `flags.has(name)` is always the\n * right question for a boolean flag. Without that, `has('auth.public')` could\n * answer `true` for the route that just opted back IN, which is an\n * authorization bypass rather than a papercut.\n */\nimport { METADATA } from './interfaces'\nimport { getClassMeta, getMethodMeta, pushClassMeta, pushMethodMeta } from './metadata'\n\n/**\n * Augmentable route-flag registry — the flag counterpart of `ContextMeta`.\n *\n * Declare a project's flags here and every use of them narrows: a misspelt\n * name is a compile error rather than a flag that silently never matches, and\n * `flags.get('rate.limit')` comes back typed instead of `unknown`.\n *\n * ```ts\n * declare module '@forinda/kickjs' {\n *   interface KickRouteFlags {\n *     'auth.public': true\n *     'rate.limit': { rpm: number }\n *   }\n * }\n * ```\n *\n * The interface is empty by default, and everything below falls back to plain\n * `string` while it stays that way — a project that has not augmented anything\n * keeps compiling exactly as before. The narrowing switches on with the first\n * declaration.\n *\n * The framework itself declares nothing here: it ships the mechanism and names\n * no flags, so `auth.public` above is a name you chose.\n *\n * Two constraints on what you can declare:\n * - A name cannot start with `!` — that prefix means \"does not carry this flag\"\n *   in a {@link RouteFlagTest}, and `defineRouteFlag` rejects it.\n * - Removal is `@Flag.off`, not `@Flag(false)` — so `false` stays usable as a\n *   real value for a flag declared `boolean`.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface KickRouteFlags {}\n\n/**\n * A flag name. Narrows to the declared keys once {@link KickRouteFlags} is\n * augmented, and stays `string` until then — the same\n * `[Known] extends [never]` fallback `ContextMetaKey` uses, for the same\n * reason: first-day code must keep compiling.\n */\nexport type RouteFlagName = [keyof KickRouteFlags] extends [never]\n  ? string\n  : keyof KickRouteFlags & string\n\n/**\n * The value type declared for a flag, defaulting to `true` for a bare flag and\n * `unknown` for a name the registry does not know.\n */\nexport type RouteFlagValue<K extends string, Fallback = unknown> = K extends keyof KickRouteFlags\n  ? KickRouteFlags[K]\n  : Fallback\n\n/**\n * Marks a declaration as \"remove this flag\" during resolution.\n *\n * A dedicated sentinel rather than `false`: `false` is a perfectly good flag\n * VALUE (a registry entry typed `boolean`), and overloading it meant\n * `@Enabled(false)` deleted the flag while `flags.get('enabled')` could never\n * return `false`. With the sentinel, `false` stores like any other value and\n * removal is spelled `@Enabled.off`.\n *\n * Module-private and NOT `Symbol.for`: a registry-global symbol is reachable\n * by application code, so a flag declared with a `symbol` value could be handed\n * this exact sentinel and be deleted instead of stored. It is created and\n * consumed in this module, so it never needs to cross a realm.\n */\nconst FLAG_UNSET: unique symbol = Symbol('kick.flagUnset') as never\n\n/** One `@Flag` application, before precedence resolution. */\nexport interface RouteFlagDeclaration {\n  readonly name: string\n  /** `false` means \"remove whatever a lower-precedence site declared\". */\n  readonly value: unknown\n}\n\n/**\n * A flag decorator. Usable bare (`@Public`) or called with a value\n * (`@Public(false)`, `@RateLimit({ rpm: 10 })`), on a class or a method.\n */\n/**\n * The bare application forms — `@Public` with no call.\n *\n * Split out so they can be withheld from a flag whose declared value is not\n * assignable from `true`: applying `@Limit` bare would store `true` while\n * `flags.get('rate.limit')` promises `{ rpm: number }`, and nothing would catch\n * the mismatch until a consumer read the wrong shape at runtime.\n */\nexport interface BareRouteFlag {\n  /**\n   * Bare on a class. Typed against `Function` rather than `object` so a flag\n   * VALUE that happens to be an object (`@Limit({ rpm: 10 })`) cannot match\n   * this signature: overload resolution would otherwise pick it, return\n   * `void`, and fail with \"Type 'void' has no call signatures\".\n   */\n  (target: Function): void\n  /**\n   * Bare on a method. `propertyKey` is required for the same reason — it makes\n   * a one-argument call unambiguous.\n   */\n  (target: object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): void\n}\n\n/** The called form — `@Limit({ rpm: 10 })` — plus removal via `.off`. */\nexport interface ValuedRouteFlag<V> {\n  (value: V): (target: object, propertyKey?: string | symbol) => void\n  /**\n   * Remove the flag on this route — `@Public.off` on a method drops what the\n   * controller set.\n   *\n   * Applied bare, like the flag itself. Spelled as its own member rather than\n   * `@Public(false)` so that `false` stays available as a real value: a flag\n   * declared `boolean` can store it, and `flags.get()` can return it.\n   */\n  readonly off: BareRouteFlag\n  readonly flagName: string\n}\n\n/**\n * A flag decorator.\n *\n * Bare application is available only when `true` is a valid value for the flag\n * — which is every flag until {@link KickRouteFlags} declares a value type for\n * it. Declare `'rate.limit': { rpm: number }` and `@RateLimit` on its own stops\n * compiling, because the value it would store is not the value the registry\n * promises readers.\n */\nexport type RouteFlag<V = true> = true extends V\n  ? BareRouteFlag & ValuedRouteFlag<V>\n  : ValuedRouteFlag<V>\n\n/**\n * True when the arguments look like a decorator application rather than a\n * value. The two forms are `@Public` (TS calls it for us) and `@Public(v)`\n * (we return the decorator).\n *\n * Discrimination has to be exact, because a value can be an object:\n * `@RateLimit({ rpm: 10 })` is a single object argument, and treating it as a\n * class-decorator target silently drops the flag.\n *\n * - method decorator → `(prototype, 'name', descriptor?)`, so arg 1 is a\n *   string or symbol\n * - class decorator → `(constructor)`, a single *function* argument\n * - anything else → a value\n */\nfunction isDecoratorApplication(args: unknown[]): boolean {\n  const [target, propertyKey] = args\n  if (typeof propertyKey === 'string' || typeof propertyKey === 'symbol') return true\n  return args.length === 1 && typeof target === 'function'\n}\n\n/**\n * Define a route flag.\n *\n * ```ts\n * export const Public = defineRouteFlag('auth.public')\n * export const RateLimit = defineRouteFlag<{ rpm: number }>('rate.limit')\n * ```\n *\n * Once {@link KickRouteFlags} declares the name, the value type comes from the\n * registry and the explicit generic is redundant:\n *\n * ```ts\n * declare module '@forinda/kickjs' {\n *   interface KickRouteFlags {\n *     'rate.limit': { rpm: number }\n *   }\n * }\n *\n * const RateLimit = defineRouteFlag('rate.limit') // RouteFlag<{ rpm: number }>\n * ```\n */\nexport function defineRouteFlag<const N extends RouteFlagName>(\n  name: N,\n): RouteFlag<RouteFlagValue<N, true>>\nexport function defineRouteFlag<V>(name: RouteFlagName): RouteFlag<V>\nexport function defineRouteFlag(name: string): RouteFlag<never> {\n  // `!` is reserved: a test string starting with it means \"does NOT carry this\n  // flag\", so a flag literally named '!x' would be indistinguishable from the\n  // negation of 'x' — `exemptWhen: '!x'` would silently stop meaning what the\n  // author wrote. Rejecting at definition is the only point where the two can\n  // still be told apart.\n  if (name.startsWith('!')) {\n    throw new Error(\n      `defineRouteFlag('${name}'): a flag name cannot start with '!' — that prefix is reserved ` +\n        `for negated tests ('!${name.slice(1)}' means \"does not carry ${name.slice(1)}\"). ` +\n        `Rename the flag.`,\n    )\n  }\n\n  function apply(value: unknown, target: object, propertyKey?: string | symbol): void {\n    const declaration: RouteFlagDeclaration = { name, value }\n    if (propertyKey === undefined) {\n      pushClassMeta<RouteFlagDeclaration>(METADATA.CLASS_FLAGS, target, declaration)\n      return\n    }\n    // Method decorators receive the prototype; metadata helpers key off the\n    // constructor so class + method lookups land in the same place.\n    pushMethodMeta<RouteFlagDeclaration>(\n      METADATA.METHOD_FLAGS,\n      (target as { constructor: object }).constructor,\n      String(propertyKey),\n      declaration,\n    )\n  }\n\n  const flag = (...args: unknown[]): unknown => {\n    if (isDecoratorApplication(args)) {\n      // Bare form: @Public\n      apply(true, args[0] as object, args[1] as string | symbol | undefined)\n      return undefined\n    }\n    // Called form: @Public(false) / @RateLimit({ rpm: 10 })\n    const value = args[0]\n    return (target: object, propertyKey?: string | symbol): void => {\n      apply(value, target, propertyKey)\n    }\n  }\n\n  Object.defineProperty(flag, 'flagName', { value: name, enumerable: true })\n  // `.off` is the removal decorator: bare-applicable, and the only way to drop\n  // an inherited flag now that `false` is an ordinary value.\n  Object.defineProperty(flag, 'off', {\n    value: (target: object, propertyKey?: string | symbol): void => {\n      apply(FLAG_UNSET, target, propertyKey)\n    },\n    enumerable: true,\n  })\n  return flag as unknown as RouteFlag<never>\n}\n\n/**\n * Resolve the flags in force for one route.\n *\n * Precedence is method > class > mount, matching the contributor pipeline's top\n * three levels. Within a level the last declaration wins (decorators apply\n * bottom-up, so the one nearest the handler is applied last).\n *\n * A resolved `false` deletes the key rather than storing it — see the module\n * docblock.\n */\nexport function resolveRouteFlags(\n  classDeclarations: readonly RouteFlagDeclaration[],\n  methodDeclarations: readonly RouteFlagDeclaration[],\n  mountDeclarations: readonly RouteFlagDeclaration[] = [],\n): RouteFlags {\n  const resolved = new Map<string, unknown>()\n\n  // Lowest precedence first, so higher levels overwrite. Mount comes first\n  // despite being the last parameter — it was added after the other two, and\n  // moving it to the front would break every existing caller for no gain.\n  for (const { name, value } of [\n    ...mountDeclarations,\n    ...classDeclarations,\n    ...methodDeclarations,\n  ]) {\n    if (value === FLAG_UNSET) {\n      resolved.delete(name)\n      continue\n    }\n    resolved.set(name, value)\n  }\n\n  // The map is built from declarations, so its value types are whatever the\n  // registry says they are — this cast is the one place that knowledge crosses\n  // from runtime data into the type system.\n  return resolved as RouteFlags\n}\n\n/**\n * The resolved flags for a route.\n *\n * A `ReadonlyMap` whose `has` is narrowed to known names and whose `get`\n * returns the declared value type — so `flags.get('rate.limit')` is\n * `{ rpm: number } | undefined` rather than `unknown`, once the registry\n * declares it. Until then it behaves like `ReadonlyMap<string, unknown>`.\n */\nexport interface RouteFlags extends ReadonlyMap<string, unknown> {\n  has(name: RouteFlagName): boolean\n  get<K extends RouteFlagName>(name: K): RouteFlagValue<K> | undefined\n}\n\n/**\n * Argument handed to a flag predicate.\n *\n * `route` is undefined only where flags are consulted outside a matched route,\n * which today means a non-HTTP transport running the same contributor pipeline.\n */\nexport interface RouteFlagContext {\n  readonly flags: RouteFlags\n  readonly route?: {\n    readonly method: string\n    readonly path: string\n    readonly controller?: unknown\n    readonly handlerName?: string\n  }\n}\n\n/**\n * A predicate form of a flag test, for conditions a single name cannot express:\n * two flags together, a flag's *value*, a path or controller check, an env\n * switch.\n *\n * ```ts\n * skipWhen: ({ flags }) => flags.has('auth.public') || flags.has('internal'),\n * skipWhen: ({ flags }) => (flags.get('rate.limit') as { rpm: number })?.rpm === 0,\n * skipWhen: ({ route }) => route?.path.startsWith('/webhooks') ?? false,\n * ```\n *\n * Keep predicates pure and cheap — they run per request, per contributor.\n */\nexport type RouteFlagPredicate = (ctx: RouteFlagContext) => boolean\n\n/**\n * How a consumer names the routes it cares about.\n *\n * A bare name for the common case, a list when several flags mean the same\n * thing (matched **any-of**), a predicate for everything else — all-of, a\n * flag's value, the route's path.\n *\n * ```ts\n * skipWhen: 'auth.public'\n * skipWhen: ['auth.public', 'health.probe']            // either one\n * skipWhen: ({ flags }) => flags.has('a') && flags.has('b')   // both\n * ```\n */\n/**\n * A flag name with `!` in front — matches routes that do **not** carry it.\n *\n * Narrows with the registry like the positive form: once `KickRouteFlags`\n * declares `'auth.public'`, this is `'!auth.public' | …`, so a misspelt\n * negation is a compile error too.\n */\nexport type NegatedRouteFlagName = `!${RouteFlagName}`\n\n/**\n * How a consumer names the routes it cares about.\n *\n * - `'auth.public'` — carries the flag\n * - `'!auth.public'` — does **not** carry it\n * - `['a', 'b']` — carries **any** of them\n * - `['!a', '!b']` — carries **none** of them\n * - a predicate — anything else: all-of, a flag's value, the route's path\n *\n * Lists are single-polarity by construction: `['a', '!b']` matches neither\n * array member of this union, so it is a compile error. Mixed polarity has no\n * reading everyone agrees on — under any-of it means \"a present OR b absent\",\n * which most readers parse as \"and\" — and a predicate says it unambiguously.\n */\nexport type RouteFlagTest =\n  | RouteFlagName\n  | NegatedRouteFlagName\n  | readonly RouteFlagName[]\n  | readonly NegatedRouteFlagName[]\n  | RouteFlagPredicate\n\n/**\n * Evaluate a {@link RouteFlagTest} against a route's resolved flags.\n *\n * Shared by every consumer that can be exempted per route — the contributor\n * runner, `csrfGuard`, `rateLimitGuard` — so \"which routes does this apply to\"\n * means the same thing everywhere, and a list is any-of in all of them.\n */\nexport function matchesFlagTest(\n  test: RouteFlagTest,\n  flags: RouteFlags | undefined,\n  route?: RouteFlagContext['route'],\n): boolean {\n  const resolved = flags ?? EMPTY_FLAGS\n  if (typeof test === 'function') return test({ flags: resolved, route })\n\n  if (typeof test === 'string') {\n    return isNegated(test)\n      ? !resolved.has(stripNegation(test))\n      : resolved.has(test as RouteFlagName)\n  }\n\n  if (test.length === 0) return false\n\n  // Single polarity per list — the type forbids mixing, and this guards the\n  // untyped callers (plain JS, a value read from config) that the type cannot.\n  const negated = isNegated(test[0])\n  if (test.some((name) => isNegated(name) !== negated)) {\n    throw new Error(\n      `Route flag test mixes polarities: [${test.map((n) => `'${n}'`).join(', ')}]. ` +\n        `A list is either all names (\"carries any of these\") or all negated ` +\n        `(\"carries none of these\") — for anything else, pass a predicate.`,\n    )\n  }\n\n  // Positive list is any-of; negated list is its complement, none-of. The two\n  // read as opposites, which is what makes flipping every entry do what a\n  // reader expects.\n  return negated\n    ? test.every((name) => !resolved.has(stripNegation(name)))\n    : test.some((name) => resolved.has(name as RouteFlagName))\n}\n\n/**\n * Reject a mixed-polarity list at construction time.\n *\n * A list like `['auth.public', '!metered']` is a static mistake, so it fails\n * where it is written — when the contributor or guard is built — rather than\n * on the first request that reaches it. Same reasoning as the contributor\n * pipeline failing a dependency cycle at boot.\n *\n * Call from every factory that accepts a {@link RouteFlagTest}; the check in\n * {@link matchesFlagTest} stays as a backstop for direct callers.\n */\nexport function assertFlagTest(test: RouteFlagTest, site: string): void {\n  if (typeof test === 'function' || typeof test === 'string' || test.length === 0) return\n  const negated = isNegated(test[0])\n  if (test.some((name) => isNegated(name) !== negated)) {\n    throw new Error(\n      `${site}: route flag test mixes polarities: [${test.map((n) => `'${n}'`).join(', ')}]. ` +\n        `A list is either all names (\"carries any of these\") or all negated ` +\n        `(\"carries none of these\") — for anything else, pass a predicate.`,\n    )\n  }\n}\n\nconst isNegated = (name: string): boolean => name.startsWith('!')\nconst stripNegation = (name: string): RouteFlagName => name.slice(1) as RouteFlagName\n\nconst EMPTY_FLAGS: RouteFlags = new Map()\n\n/**\n * Where the matched route is stashed for `ctx.route` to read.\n *\n * It lives on the **request object**, not on the RequestContext: the Express\n * runtime constructs a fresh `RequestContext` per middleware, so anything\n * written to one ctx is invisible to the next and to the handler. Fastify and\n * h3 build a single ctx per request and would not have shown the difference —\n * the cross-runtime test is what surfaced it.\n *\n * `Symbol.for` rather than a private symbol so a duplicated module instance\n * (pnpm hoisting, a bundled copy) still reads the same slot.\n */\nexport const ROUTE_SLOT: unique symbol = Symbol.for('kick.route') as never\n\n/**\n * Resolve the flags in force for one handler, straight from the controller\n * class — the same method-over-class result `buildRouteTable` computes.\n *\n * For consumers that see a controller and a method name rather than a live\n * request: an adapter's `onRouteMount`, an OpenAPI generator, a DevTools route\n * listing. Inside a request, read `ctx.route.flags` instead — it is already\n * resolved.\n *\n * ```ts\n * // Mark flagged routes public in the OpenAPI spec:\n * SwaggerAdapter({\n *   bearerAuth: true,\n *   securityResolver: ({ controllerClass, handlerName }) =>\n *     getRouteFlags(controllerClass, handlerName).has('auth.public') ? null : undefined,\n * })\n * ```\n */\nexport function getRouteFlags(controllerClass: object, handlerName: string): RouteFlags {\n  return resolveRouteFlags(\n    getClassFlagDeclarations(controllerClass),\n    getMethodFlagDeclarations(controllerClass, handlerName),\n    getMountFlagDeclarations(controllerClass),\n  )\n}\n\n/** Read the class-level declarations off a controller. */\nexport function getClassFlagDeclarations(controllerClass: object): RouteFlagDeclaration[] {\n  return getClassMeta<RouteFlagDeclaration[]>(METADATA.CLASS_FLAGS, controllerClass, [])\n}\n\n/** Read the method-level declarations off a controller method. */\nexport function getMethodFlagDeclarations(\n  controllerClass: object,\n  handlerName: string,\n): RouteFlagDeclaration[] {\n  return getMethodMeta<RouteFlagDeclaration[]>(\n    METADATA.METHOD_FLAGS,\n    controllerClass,\n    handlerName,\n    [],\n  )\n}\n\n/**\n * Flags declared as data rather than as a decorator, keyed by name.\n *\n * ```ts\n * { 'auth.public': true, 'rate.limit': { rpm: 10 } }\n * ```\n */\nexport type RouteFlagRecord = { [K in RouteFlagName]?: RouteFlagValue<K, true> }\n\n/**\n * What a non-decorator registration site accepts.\n *\n * A list is the common case — bare flags, each stored as `true`:\n * `flags: ['auth.public']`. The record form exists for flags that carry a\n * value. Both narrow against {@link KickRouteFlags} once it is augmented.\n */\nexport type RouteFlagDeclarations = readonly RouteFlagName[] | RouteFlagRecord\n\n/**\n * Normalise either input form into declarations.\n *\n * @param site Where the flags came from, for the error message — a name is\n * validated here rather than at read time so a typo'd `!` fails at boot.\n */\nexport function toFlagDeclarations(\n  flags: RouteFlagDeclarations | undefined,\n  site: string,\n): RouteFlagDeclaration[] {\n  if (!flags) return []\n  const entries: [string, unknown][] = Array.isArray(flags)\n    ? flags.map((name) => [name as string, true])\n    : Object.entries(flags as Record<string, unknown>)\n\n  return entries.map(([name, value]) => {\n    // Same reservation as `defineRouteFlag`: `!name` is a negated *test*, and a\n    // flag named that way could never be tested for. Declaring one is always a\n    // mistake — usually someone reaching for \"not public\" on the wrong side.\n    if (name.startsWith('!')) {\n      throw new Error(\n        `${site}: a flag name cannot start with '!' — that prefix is reserved for negated ` +\n          `tests, and a declaration has no negative form. Remove the flag instead of ` +\n          `declaring '${name}'.`,\n      )\n    }\n    return { name, value }\n  })\n}\n\n/**\n * Mount-level declarations, keyed by controller class.\n *\n * A module declares flags for every route it mounts (`ModuleRoutes.flags`), so\n * unlike class and method declarations they are not written by a decorator and\n * have nowhere on the class to live. They are recorded here at mount time so\n * that {@link getRouteFlags} — which sees only a controller and a method name —\n * reports the same flags the runtime resolved. Without it an OpenAPI spec or a\n * DevTools route listing would disagree with `ctx.route.flags`.\n *\n * A `WeakMap`, so a controller from a torn-down app (a test, an HMR reload) is\n * collectable. Mounting the same controller twice replaces rather than appends:\n * a reload re-declares the same flags, and appending would grow without bound.\n */\nconst MOUNT_FLAGS = new WeakMap<object, RouteFlagDeclaration[]>()\n\n/**\n * Record the flags a mount declares for `controllerClass`.\n *\n * @internal Called by the route-table builder; not part of the app-facing API.\n */\nexport function registerMountFlags(\n  controllerClass: object,\n  declarations: readonly RouteFlagDeclaration[],\n): void {\n  if (declarations.length === 0) {\n    MOUNT_FLAGS.delete(controllerClass)\n    return\n  }\n  MOUNT_FLAGS.set(controllerClass, [...declarations])\n}\n\n/** Read the mount-level declarations recorded for a controller. */\nexport function getMountFlagDeclarations(controllerClass: object): RouteFlagDeclaration[] {\n  return MOUNT_FLAGS.get(controllerClass) ?? []\n}\n"],"mappings":"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"}
+{"version":3,"file":"route-flag-sIYXay3q.mjs","names":[],"sources":["../src/core/route-flag.ts"],"sourcesContent":["/**\n * Route flags — a named, inheritable fact about a route.\n *\n * A flag carries no behaviour. It records something about the route that any\n * consumer may read: `auth.public`, `csrf.exempt`, `rate.limit`. Auth reads it\n * to skip a contributor, a guard reads it to return early, Swagger reads it to\n * mark a security scheme — none of them needs to know about the others.\n *\n * The rule that makes presence checks safe: a flag resolves to **absent**, or\n * **present with a value**. `@Public.off` on a method removes what the class\n * set, rather than storing something falsy — so `flags.has(name)` is always the\n * right question for a boolean flag. Without that, `has('auth.public')` could\n * answer `true` for the route that just opted back IN, which is an\n * authorization bypass rather than a papercut.\n */\nimport { METADATA } from './interfaces'\nimport { getClassMeta, getMethodMeta, pushClassMeta, pushMethodMeta } from './metadata'\n\n/**\n * Augmentable route-flag registry — the flag counterpart of `ContextMeta`.\n *\n * Declare a project's flags here and every use of them narrows: a misspelt\n * name is a compile error rather than a flag that silently never matches, and\n * `flags.get('rate.limit')` comes back typed instead of `unknown`.\n *\n * ```ts\n * declare module '@forinda/kickjs' {\n *   interface KickRouteFlags {\n *     'auth.public': true\n *     'rate.limit': { rpm: number }\n *   }\n * }\n * ```\n *\n * The interface is empty by default, and everything below falls back to plain\n * `string` while it stays that way — a project that has not augmented anything\n * keeps compiling exactly as before. The narrowing switches on with the first\n * declaration.\n *\n * The framework itself declares nothing here: it ships the mechanism and names\n * no flags, so `auth.public` above is a name you chose.\n *\n * Two constraints on what you can declare:\n * - A name cannot start with `!` — that prefix means \"does not carry this flag\"\n *   in a {@link RouteFlagTest}, and `defineRouteFlag` rejects it.\n * - Removal is `@Flag.off`, not `@Flag(false)` — so `false` stays usable as a\n *   real value for a flag declared `boolean`.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-interface\nexport interface KickRouteFlags {}\n\n/**\n * A flag name. Narrows to the declared keys once {@link KickRouteFlags} is\n * augmented, and stays `string` until then — the same\n * `[Known] extends [never]` fallback `ContextMetaKey` uses, for the same\n * reason: first-day code must keep compiling.\n */\nexport type RouteFlagName = [keyof KickRouteFlags] extends [never]\n  ? string\n  : keyof KickRouteFlags & string\n\n/**\n * The value type declared for a flag, defaulting to `true` for a bare flag and\n * `unknown` for a name the registry does not know.\n */\nexport type RouteFlagValue<K extends string, Fallback = unknown> = K extends keyof KickRouteFlags\n  ? KickRouteFlags[K]\n  : Fallback\n\n/**\n * Marks a declaration as \"remove this flag\" during resolution.\n *\n * A dedicated sentinel rather than `false`: `false` is a perfectly good flag\n * VALUE (a registry entry typed `boolean`), and overloading it meant\n * `@Enabled(false)` deleted the flag while `flags.get('enabled')` could never\n * return `false`. With the sentinel, `false` stores like any other value and\n * removal is spelled `@Enabled.off`.\n *\n * Module-private and NOT `Symbol.for`: a registry-global symbol is reachable\n * by application code, so a flag declared with a `symbol` value could be handed\n * this exact sentinel and be deleted instead of stored. It is created and\n * consumed in this module, so it never needs to cross a realm.\n */\nconst FLAG_UNSET: unique symbol = Symbol('kick.flagUnset') as never\n\n/** One `@Flag` application, before precedence resolution. */\nexport interface RouteFlagDeclaration {\n  readonly name: string\n  /** `false` means \"remove whatever a lower-precedence site declared\". */\n  readonly value: unknown\n}\n\n/**\n * A flag decorator. Usable bare (`@Public`) or called with a value\n * (`@Public(false)`, `@RateLimit({ rpm: 10 })`), on a class or a method.\n */\n/**\n * The bare application forms — `@Public` with no call.\n *\n * Split out so they can be withheld from a flag whose declared value is not\n * assignable from `true`: applying `@Limit` bare would store `true` while\n * `flags.get('rate.limit')` promises `{ rpm: number }`, and nothing would catch\n * the mismatch until a consumer read the wrong shape at runtime.\n */\nexport interface BareRouteFlag {\n  /**\n   * Bare on a class. Typed against `Function` rather than `object` so a flag\n   * VALUE that happens to be an object (`@Limit({ rpm: 10 })`) cannot match\n   * this signature: overload resolution would otherwise pick it, return\n   * `void`, and fail with \"Type 'void' has no call signatures\".\n   */\n  (target: Function): void\n  /**\n   * Bare on a method. `propertyKey` is required for the same reason — it makes\n   * a one-argument call unambiguous.\n   */\n  (target: object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): void\n}\n\n/** The called form — `@Limit({ rpm: 10 })` — plus removal via `.off`. */\nexport interface ValuedRouteFlag<V> {\n  (value: V): (target: object, propertyKey?: string | symbol) => void\n  /**\n   * Remove the flag on this route — `@Public.off` on a method drops what the\n   * controller set.\n   *\n   * Applied bare, like the flag itself. Spelled as its own member rather than\n   * `@Public(false)` so that `false` stays available as a real value: a flag\n   * declared `boolean` can store it, and `flags.get()` can return it.\n   */\n  readonly off: BareRouteFlag\n  readonly flagName: string\n}\n\n/**\n * A flag decorator.\n *\n * Bare application is available only when `true` is a valid value for the flag\n * — which is every flag until {@link KickRouteFlags} declares a value type for\n * it. Declare `'rate.limit': { rpm: number }` and `@RateLimit` on its own stops\n * compiling, because the value it would store is not the value the registry\n * promises readers.\n */\nexport type RouteFlag<V = true> = true extends V\n  ? BareRouteFlag & ValuedRouteFlag<V>\n  : ValuedRouteFlag<V>\n\n/**\n * True when the arguments look like a decorator application rather than a\n * value. The two forms are `@Public` (TS calls it for us) and `@Public(v)`\n * (we return the decorator).\n *\n * Discrimination has to be exact, because a value can be an object:\n * `@RateLimit({ rpm: 10 })` is a single object argument, and treating it as a\n * class-decorator target silently drops the flag.\n *\n * - method decorator → `(prototype, 'name', descriptor?)`, so arg 1 is a\n *   string or symbol\n * - class decorator → `(constructor)`, a single *function* argument\n * - anything else → a value\n */\nfunction isDecoratorApplication(args: unknown[]): boolean {\n  const [target, propertyKey] = args\n  if (typeof propertyKey === 'string' || typeof propertyKey === 'symbol') return true\n  return args.length === 1 && typeof target === 'function'\n}\n\n/**\n * Define a route flag.\n *\n * ```ts\n * export const Public = defineRouteFlag('auth.public')\n * export const RateLimit = defineRouteFlag<{ rpm: number }>('rate.limit')\n * ```\n *\n * Once {@link KickRouteFlags} declares the name, the value type comes from the\n * registry and the explicit generic is redundant:\n *\n * ```ts\n * declare module '@forinda/kickjs' {\n *   interface KickRouteFlags {\n *     'rate.limit': { rpm: number }\n *   }\n * }\n *\n * const RateLimit = defineRouteFlag('rate.limit') // RouteFlag<{ rpm: number }>\n * ```\n */\nexport function defineRouteFlag<const N extends RouteFlagName>(\n  name: N,\n): RouteFlag<RouteFlagValue<N, true>>\nexport function defineRouteFlag<V>(name: RouteFlagName): RouteFlag<V>\nexport function defineRouteFlag(name: string): RouteFlag<never> {\n  // `!` is reserved: a test string starting with it means \"does NOT carry this\n  // flag\", so a flag literally named '!x' would be indistinguishable from the\n  // negation of 'x' — `exemptWhen: '!x'` would silently stop meaning what the\n  // author wrote. Rejecting at definition is the only point where the two can\n  // still be told apart.\n  if (name.startsWith('!')) {\n    throw new Error(\n      `defineRouteFlag('${name}'): a flag name cannot start with '!' — that prefix is reserved ` +\n        `for negated tests ('!${name.slice(1)}' means \"does not carry ${name.slice(1)}\"). ` +\n        `Rename the flag.`,\n    )\n  }\n\n  function apply(value: unknown, target: object, propertyKey?: string | symbol): void {\n    const declaration: RouteFlagDeclaration = { name, value }\n    if (propertyKey === undefined) {\n      pushClassMeta<RouteFlagDeclaration>(METADATA.CLASS_FLAGS, target, declaration)\n      return\n    }\n    // Method decorators receive the prototype; metadata helpers key off the\n    // constructor so class + method lookups land in the same place.\n    pushMethodMeta<RouteFlagDeclaration>(\n      METADATA.METHOD_FLAGS,\n      (target as { constructor: object }).constructor,\n      String(propertyKey),\n      declaration,\n    )\n  }\n\n  const flag = (...args: unknown[]): unknown => {\n    if (isDecoratorApplication(args)) {\n      // Bare form: @Public\n      apply(true, args[0] as object, args[1] as string | symbol | undefined)\n      return undefined\n    }\n    // Called form: @Public(false) / @RateLimit({ rpm: 10 })\n    const value = args[0]\n    return (target: object, propertyKey?: string | symbol): void => {\n      apply(value, target, propertyKey)\n    }\n  }\n\n  Object.defineProperty(flag, 'flagName', { value: name, enumerable: true })\n  // `.off` is the removal decorator: bare-applicable, and the only way to drop\n  // an inherited flag now that `false` is an ordinary value.\n  Object.defineProperty(flag, 'off', {\n    value: (target: object, propertyKey?: string | symbol): void => {\n      apply(FLAG_UNSET, target, propertyKey)\n    },\n    enumerable: true,\n  })\n  return flag as unknown as RouteFlag<never>\n}\n\n/**\n * Resolve the flags in force for one route.\n *\n * Precedence is method > class > mount, matching the contributor pipeline's top\n * three levels. Within a level the last declaration wins (decorators apply\n * bottom-up, so the one nearest the handler is applied last).\n *\n * A resolved `false` deletes the key rather than storing it — see the module\n * docblock.\n */\nexport function resolveRouteFlags(\n  classDeclarations: readonly RouteFlagDeclaration[],\n  methodDeclarations: readonly RouteFlagDeclaration[],\n  mountDeclarations: readonly RouteFlagDeclaration[] = [],\n): RouteFlags {\n  const resolved = new Map<string, unknown>()\n\n  // Lowest precedence first, so higher levels overwrite. Mount comes first\n  // despite being the last parameter — it was added after the other two, and\n  // moving it to the front would break every existing caller for no gain.\n  for (const { name, value } of [\n    ...mountDeclarations,\n    ...classDeclarations,\n    ...methodDeclarations,\n  ]) {\n    if (value === FLAG_UNSET) {\n      resolved.delete(name)\n      continue\n    }\n    resolved.set(name, value)\n  }\n\n  // The map is built from declarations, so its value types are whatever the\n  // registry says they are — this cast is the one place that knowledge crosses\n  // from runtime data into the type system.\n  return resolved as RouteFlags\n}\n\n/**\n * The resolved flags for a route.\n *\n * A `ReadonlyMap` whose `has` is narrowed to known names and whose `get`\n * returns the declared value type — so `flags.get('rate.limit')` is\n * `{ rpm: number } | undefined` rather than `unknown`, once the registry\n * declares it. Until then it behaves like `ReadonlyMap<string, unknown>`.\n */\nexport interface RouteFlags extends ReadonlyMap<string, unknown> {\n  has(name: RouteFlagName): boolean\n  get<K extends RouteFlagName>(name: K): RouteFlagValue<K> | undefined\n}\n\n/**\n * Argument handed to a flag predicate.\n *\n * `route` is undefined only where flags are consulted outside a matched route,\n * which today means a non-HTTP transport running the same contributor pipeline.\n */\nexport interface RouteFlagContext {\n  readonly flags: RouteFlags\n  readonly route?: {\n    readonly method: string\n    readonly path: string\n    readonly controller?: unknown\n    readonly handlerName?: string\n  }\n}\n\n/**\n * A predicate form of a flag test, for conditions a single name cannot express:\n * two flags together, a flag's *value*, a path or controller check, an env\n * switch.\n *\n * ```ts\n * skipWhen: ({ flags }) => flags.has('auth.public') || flags.has('internal'),\n * skipWhen: ({ flags }) => (flags.get('rate.limit') as { rpm: number })?.rpm === 0,\n * skipWhen: ({ route }) => route?.path.startsWith('/webhooks') ?? false,\n * ```\n *\n * Keep predicates pure and cheap — they run per request, per contributor.\n */\nexport type RouteFlagPredicate = (ctx: RouteFlagContext) => boolean\n\n/**\n * How a consumer names the routes it cares about.\n *\n * A bare name for the common case, a list when several flags mean the same\n * thing (matched **any-of**), a predicate for everything else — all-of, a\n * flag's value, the route's path.\n *\n * ```ts\n * skipWhen: 'auth.public'\n * skipWhen: ['auth.public', 'health.probe']            // either one\n * skipWhen: ({ flags }) => flags.has('a') && flags.has('b')   // both\n * ```\n */\n/**\n * A flag name with `!` in front — matches routes that do **not** carry it.\n *\n * Narrows with the registry like the positive form: once `KickRouteFlags`\n * declares `'auth.public'`, this is `'!auth.public' | …`, so a misspelt\n * negation is a compile error too.\n */\nexport type NegatedRouteFlagName = `!${RouteFlagName}`\n\n/**\n * How a consumer names the routes it cares about.\n *\n * - `'auth.public'` — carries the flag\n * - `'!auth.public'` — does **not** carry it\n * - `['a', 'b']` — carries **any** of them\n * - `['!a', '!b']` — carries **none** of them\n * - a predicate — anything else: all-of, a flag's value, the route's path\n *\n * Lists are single-polarity by construction: `['a', '!b']` matches neither\n * array member of this union, so it is a compile error. Mixed polarity has no\n * reading everyone agrees on — under any-of it means \"a present OR b absent\",\n * which most readers parse as \"and\" — and a predicate says it unambiguously.\n */\nexport type RouteFlagTest =\n  | RouteFlagName\n  | NegatedRouteFlagName\n  | readonly RouteFlagName[]\n  | readonly NegatedRouteFlagName[]\n  | RouteFlagPredicate\n\n/**\n * Evaluate a {@link RouteFlagTest} against a route's resolved flags.\n *\n * Shared by every consumer that can be exempted per route — the contributor\n * runner, `csrfGuard`, `rateLimitGuard` — so \"which routes does this apply to\"\n * means the same thing everywhere, and a list is any-of in all of them.\n */\nexport function matchesFlagTest(\n  test: RouteFlagTest,\n  flags: RouteFlags | undefined,\n  route?: RouteFlagContext['route'],\n): boolean {\n  const resolved = flags ?? EMPTY_FLAGS\n  if (typeof test === 'function') return test({ flags: resolved, route })\n\n  if (typeof test === 'string') {\n    return isNegated(test)\n      ? !resolved.has(stripNegation(test))\n      : resolved.has(test as RouteFlagName)\n  }\n\n  if (test.length === 0) return false\n\n  // Single polarity per list — the type forbids mixing, and this guards the\n  // untyped callers (plain JS, a value read from config) that the type cannot.\n  const negated = isNegated(test[0])\n  if (test.some((name) => isNegated(name) !== negated)) {\n    throw new Error(\n      `Route flag test mixes polarities: [${test.map((n) => `'${n}'`).join(', ')}]. ` +\n        `A list is either all names (\"carries any of these\") or all negated ` +\n        `(\"carries none of these\") — for anything else, pass a predicate.`,\n    )\n  }\n\n  // Positive list is any-of; negated list is its complement, none-of. The two\n  // read as opposites, which is what makes flipping every entry do what a\n  // reader expects.\n  return negated\n    ? test.every((name) => !resolved.has(stripNegation(name)))\n    : test.some((name) => resolved.has(name as RouteFlagName))\n}\n\n/**\n * Reject a mixed-polarity list at construction time.\n *\n * A list like `['auth.public', '!metered']` is a static mistake, so it fails\n * where it is written — when the contributor or guard is built — rather than\n * on the first request that reaches it. Same reasoning as the contributor\n * pipeline failing a dependency cycle at boot.\n *\n * Call from every factory that accepts a {@link RouteFlagTest}; the check in\n * {@link matchesFlagTest} stays as a backstop for direct callers.\n */\nexport function assertFlagTest(test: RouteFlagTest, site: string): void {\n  if (typeof test === 'function' || typeof test === 'string' || test.length === 0) return\n  const negated = isNegated(test[0])\n  if (test.some((name) => isNegated(name) !== negated)) {\n    throw new Error(\n      `${site}: route flag test mixes polarities: [${test.map((n) => `'${n}'`).join(', ')}]. ` +\n        `A list is either all names (\"carries any of these\") or all negated ` +\n        `(\"carries none of these\") — for anything else, pass a predicate.`,\n    )\n  }\n}\n\nconst isNegated = (name: string): boolean => name.startsWith('!')\nconst stripNegation = (name: string): RouteFlagName => name.slice(1) as RouteFlagName\n\nconst EMPTY_FLAGS: RouteFlags = new Map()\n\n/**\n * Where the matched route is stashed for `ctx.route` to read.\n *\n * It lives on the **request object**, not on the RequestContext: the Express\n * runtime constructs a fresh `RequestContext` per middleware, so anything\n * written to one ctx is invisible to the next and to the handler. Fastify and\n * h3 build a single ctx per request and would not have shown the difference —\n * the cross-runtime test is what surfaced it.\n *\n * `Symbol.for` rather than a private symbol so a duplicated module instance\n * (pnpm hoisting, a bundled copy) still reads the same slot.\n */\nexport const ROUTE_SLOT: unique symbol = Symbol.for('kick.route') as never\n\n/**\n * Resolve the flags in force for one handler, straight from the controller\n * class — the same method-over-class result `buildRouteTable` computes.\n *\n * For consumers that see a controller and a method name rather than a live\n * request: an adapter's `onRouteMount`, an OpenAPI generator, a DevTools route\n * listing. Inside a request, read `ctx.route.flags` instead — it is already\n * resolved.\n *\n * ```ts\n * // Mark flagged routes public in the OpenAPI spec:\n * SwaggerAdapter({\n *   bearerAuth: true,\n *   securityResolver: ({ controllerClass, handlerName }) =>\n *     getRouteFlags(controllerClass, handlerName).has('auth.public') ? null : undefined,\n * })\n * ```\n */\nexport function getRouteFlags(controllerClass: object, handlerName: string): RouteFlags {\n  return resolveRouteFlags(\n    getClassFlagDeclarations(controllerClass),\n    getMethodFlagDeclarations(controllerClass, handlerName),\n    getMountFlagDeclarations(controllerClass),\n  )\n}\n\n/** Read the class-level declarations off a controller. */\nexport function getClassFlagDeclarations(controllerClass: object): RouteFlagDeclaration[] {\n  return getClassMeta<RouteFlagDeclaration[]>(METADATA.CLASS_FLAGS, controllerClass, [])\n}\n\n/** Read the method-level declarations off a controller method. */\nexport function getMethodFlagDeclarations(\n  controllerClass: object,\n  handlerName: string,\n): RouteFlagDeclaration[] {\n  return getMethodMeta<RouteFlagDeclaration[]>(\n    METADATA.METHOD_FLAGS,\n    controllerClass,\n    handlerName,\n    [],\n  )\n}\n\n/**\n * Flags declared as data rather than as a decorator, keyed by name.\n *\n * ```ts\n * { 'auth.public': true, 'rate.limit': { rpm: 10 } }\n * ```\n */\nexport type RouteFlagRecord = { [K in RouteFlagName]?: RouteFlagValue<K, true> }\n\n/**\n * What a non-decorator registration site accepts.\n *\n * A list is the common case — bare flags, each stored as `true`:\n * `flags: ['auth.public']`. The record form exists for flags that carry a\n * value. Both narrow against {@link KickRouteFlags} once it is augmented.\n */\nexport type RouteFlagDeclarations = readonly RouteFlagName[] | RouteFlagRecord\n\n/**\n * Normalise either input form into declarations.\n *\n * @param site Where the flags came from, for the error message — a name is\n * validated here rather than at read time so a typo'd `!` fails at boot.\n */\nexport function toFlagDeclarations(\n  flags: RouteFlagDeclarations | undefined,\n  site: string,\n): RouteFlagDeclaration[] {\n  if (!flags) return []\n  const entries: [string, unknown][] = Array.isArray(flags)\n    ? flags.map((name) => [name as string, true])\n    : Object.entries(flags as Record<string, unknown>)\n\n  return entries.map(([name, value]) => {\n    // Same reservation as `defineRouteFlag`: `!name` is a negated *test*, and a\n    // flag named that way could never be tested for. Declaring one is always a\n    // mistake — usually someone reaching for \"not public\" on the wrong side.\n    if (name.startsWith('!')) {\n      throw new Error(\n        `${site}: a flag name cannot start with '!' — that prefix is reserved for negated ` +\n          `tests, and a declaration has no negative form. Remove the flag instead of ` +\n          `declaring '${name}'.`,\n      )\n    }\n    return { name, value }\n  })\n}\n\n/**\n * Mount-level declarations, keyed by controller class.\n *\n * A module declares flags for every route it mounts (`ModuleRoutes.flags`), so\n * unlike class and method declarations they are not written by a decorator and\n * have nowhere on the class to live. They are recorded here at mount time so\n * that {@link getRouteFlags} — which sees only a controller and a method name —\n * reports the same flags the runtime resolved. Without it an OpenAPI spec or a\n * DevTools route listing would disagree with `ctx.route.flags`.\n *\n * A `WeakMap`, so a controller from a torn-down app (a test, an HMR reload) is\n * collectable. Mounting the same controller twice replaces rather than appends:\n * a reload re-declares the same flags, and appending would grow without bound.\n */\nconst MOUNT_FLAGS = new WeakMap<object, RouteFlagDeclaration[]>()\n\n/**\n * Record the flags a mount declares for `controllerClass`.\n *\n * @internal Called by the route-table builder; not part of the app-facing API.\n */\nexport function registerMountFlags(\n  controllerClass: object,\n  declarations: readonly RouteFlagDeclaration[],\n): void {\n  if (declarations.length === 0) {\n    MOUNT_FLAGS.delete(controllerClass)\n    return\n  }\n  MOUNT_FLAGS.set(controllerClass, [...declarations])\n}\n\n/** Read the mount-level declarations recorded for a controller. */\nexport function getMountFlagDeclarations(controllerClass: object): RouteFlagDeclaration[] {\n  return MOUNT_FLAGS.get(controllerClass) ?? []\n}\n"],"mappings":"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"}

package/dist/{route-policy-BmiX7NiW.mjs → route-policy-B6_toGJW.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v9.0.2
+ * @forinda/kickjs v9.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -9,4 +9,4 @@
  * @license MIT
  */
 const EMPTY=new Map;function compile(path){let source=path.replace(/[.+?^${}()|[\]\\]/g,`\\$&`).replace(/\/:[^/]+/g,`/([^/]+)`).replace(/\*/g,`.*`);return RegExp(`^${source}/?$`)}var RoutePolicyTable=class{byMethod=new Map;add(method,path,flags){if(!flags||flags.size===0)return;let verb=method.toUpperCase(),bucket=this.byMethod.get(verb)??[];bucket.push({pattern:compile(path),flags}),this.byMethod.set(verb,bucket)}lookup(method,pathname){let bucket=this.byMethod.get(method.toUpperCase());if(!bucket)return EMPTY;for(let entry of bucket)if(entry.pattern.test(pathname))return entry.flags;return EMPTY}clear(){this.byMethod.clear()}get size(){let total=0;for(let bucket of this.byMethod.values())total+=bucket.length;return total}};const ROUTE_POLICY_SLOT=Symbol.for(`kick.routePolicy`);function bindRoutePolicy(handler,receive){return Object.defineProperty(handler,ROUTE_POLICY_SLOT,{value:receive,enumerable:!1}),handler}function offerRoutePolicy(handler,table){let receive=handler?.[ROUTE_POLICY_SLOT];typeof receive==`function`&&receive(table)}export{bindRoutePolicy as n,offerRoutePolicy as r,RoutePolicyTable as t};
-//# sourceMappingURL=route-policy-BmiX7NiW.mjs.map
+//# sourceMappingURL=route-policy-B6_toGJW.mjs.map

package/dist/{route-policy-BmiX7NiW.mjs.map → route-policy-B6_toGJW.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"route-policy-BmiX7NiW.mjs","names":[],"sources":["../src/core/route-policy.ts"],"sourcesContent":["/**\n * The route policy table — route flags for pre-match middleware.\n *\n * Middleware mounted app-wide (the connect-style `rateLimit()`, `csrf()`) runs\n * *before* a route is matched, so it cannot read `ctx.route.flags`: there is no\n * route yet. That is also the reason to keep it there — an abuse control has to\n * see traffic that matches nothing, which a route-scoped guard never does.\n *\n * So the flags come to it instead. Every mounted route registers its method,\n * full path and resolved flags here at boot; a global middleware asks the table\n * what flags *would* apply to an incoming method + pathname.\n *\n * The table is per-Application, handed to middleware that opts in via\n * {@link bindRoutePolicy}. Nothing global: two apps in one process (a test file,\n * an embedded admin app) each get their own.\n */\n\nimport type { RouteFlags } from './route-flag'\n\n/** Flags for one mounted route, keyed for lookup by an incoming request. */\ninterface PolicyEntry {\n  /** Compiled from the mounted path — `/users/:id` → `^/users/([^/]+)$`. */\n  readonly pattern: RegExp\n  readonly flags: RouteFlags\n}\n\nconst EMPTY: RouteFlags = new Map() as RouteFlags\n\n/**\n * Turn a mounted path into a matcher.\n *\n * Deliberately small: `:param` matches one segment, `*` matches the rest, and\n * everything else is literal. This is a *lookup* over paths the engine already\n * chose to mount, not a second router — if it ever disagrees with the engine,\n * the answer is fewer features here, not more.\n */\nfunction compile(path: string): RegExp {\n  const source = path\n    .replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&')\n    .replace(/\\/:[^/]+/g, '/([^/]+)')\n    .replace(/\\*/g, '.*')\n  return new RegExp(`^${source}/?$`)\n}\n\nexport class RoutePolicyTable {\n  /** Bucketed by method: an incoming request only scans its own verb. */\n  private readonly byMethod = new Map<string, PolicyEntry[]>()\n\n  add(method: string, path: string, flags: RouteFlags | undefined): void {\n    if (!flags || flags.size === 0) return // nothing to say about this route\n    const verb = method.toUpperCase()\n    const bucket = this.byMethod.get(verb) ?? []\n    bucket.push({ pattern: compile(path), flags })\n    this.byMethod.set(verb, bucket)\n  }\n\n  /**\n   * Flags that apply to `method pathname`, or an empty map when the path\n   * matches no flagged route — including when it matches no route at all,\n   * which is exactly the traffic this exists to keep visible.\n   */\n  lookup(method: string, pathname: string): RouteFlags {\n    const bucket = this.byMethod.get(method.toUpperCase())\n    if (!bucket) return EMPTY\n    for (const entry of bucket) {\n      if (entry.pattern.test(pathname)) return entry.flags\n    }\n    return EMPTY\n  }\n\n  /** Drop everything — the Application rebuilds on every HMR reload. */\n  clear(): void {\n    this.byMethod.clear()\n  }\n\n  get size(): number {\n    let total = 0\n    for (const bucket of this.byMethod.values()) total += bucket.length\n    return total\n  }\n}\n\n/**\n * Slot a middleware exposes to say \"hand me the policy table once routes are\n * mounted\". The Application calls it during setup; middleware that never\n * declares it is untouched.\n */\nexport const ROUTE_POLICY_SLOT: unique symbol = Symbol.for('kick.routePolicy') as never\n\n/** A middleware that accepts the policy table. */\nexport interface RoutePolicyAware {\n  [ROUTE_POLICY_SLOT]?: (table: RoutePolicyTable) => void\n}\n\n/**\n * Declare that `handler` wants the policy table.\n *\n * Explicit hand-off rather than a module-level singleton, so the table a\n * middleware reads is always the one belonging to the app that mounted it.\n */\nexport function bindRoutePolicy<T extends object>(\n  handler: T,\n  receive: (table: RoutePolicyTable) => void,\n): T {\n  Object.defineProperty(handler, ROUTE_POLICY_SLOT, { value: receive, enumerable: false })\n  return handler\n}\n\n/** Hand the table to a middleware if it declared the slot. */\nexport function offerRoutePolicy(handler: unknown, table: RoutePolicyTable): void {\n  const receive = (handler as RoutePolicyAware | null)?.[ROUTE_POLICY_SLOT]\n  if (typeof receive === 'function') receive(table)\n}\n"],"mappings":";;;;;;;;;;AA0BA,MAAM,MAAoB,IAAI,IAU9B,SAAS,QAAQ,KAAsB,CACrC,IAAM,OAAS,KACZ,QAAQ,qBAAsB,MAAM,CAAC,CACrC,QAAQ,YAAa,UAAU,CAAC,CAChC,QAAQ,MAAO,IAAI,EACtB,OAAW,OAAO,IAAI,OAAO,IAAI,CACnC,CAEA,IAAa,iBAAb,KAA8B,CAE5B,SAA4B,IAAI,IAEhC,IAAI,OAAgB,KAAc,MAAqC,CACrE,GAAI,CAAC,OAAS,MAAM,OAAS,EAAG,OAChC,IAAM,KAAO,OAAO,YAAY,EAC1B,OAAS,KAAK,SAAS,IAAI,IAAI,GAAK,CAAC,EAC3C,OAAO,KAAK,CAAE,QAAS,QAAQ,IAAI,EAAG,KAAM,CAAC,EAC7C,KAAK,SAAS,IAAI,KAAM,MAAM,CAChC,CAOA,OAAO,OAAgB,SAA8B,CACnD,IAAM,OAAS,KAAK,SAAS,IAAI,OAAO,YAAY,CAAC,EACrD,GAAI,CAAC,OAAQ,OAAO,MACpB,IAAK,IAAM,SAAS,OAClB,GAAI,MAAM,QAAQ,KAAK,QAAQ,EAAG,OAAO,MAAM,MAEjD,OAAO,KACT,CAGA,OAAc,CACZ,KAAK,SAAS,MAAM,CACtB,CAEA,IAAI,MAAe,CACjB,IAAI,MAAQ,EACZ,IAAK,IAAM,UAAU,KAAK,SAAS,OAAO,EAAG,OAAS,OAAO,OAC7D,OAAO,KACT,CACF,EAOA,MAAa,kBAAmC,OAAO,IAAI,kBAAkB,EAa7E,SAAgB,gBACd,QACA,QACG,CAEH,OADA,OAAO,eAAe,QAAS,kBAAmB,CAAE,MAAO,QAAS,WAAY,EAAM,CAAC,EAChF,OACT,CAGA,SAAgB,iBAAiB,QAAkB,MAA+B,CAChF,IAAM,QAAW,UAAsC,mBACnD,OAAO,SAAY,YAAY,QAAQ,KAAK,CAClD"}
+{"version":3,"file":"route-policy-B6_toGJW.mjs","names":[],"sources":["../src/core/route-policy.ts"],"sourcesContent":["/**\n * The route policy table — route flags for pre-match middleware.\n *\n * Middleware mounted app-wide (the connect-style `rateLimit()`, `csrf()`) runs\n * *before* a route is matched, so it cannot read `ctx.route.flags`: there is no\n * route yet. That is also the reason to keep it there — an abuse control has to\n * see traffic that matches nothing, which a route-scoped guard never does.\n *\n * So the flags come to it instead. Every mounted route registers its method,\n * full path and resolved flags here at boot; a global middleware asks the table\n * what flags *would* apply to an incoming method + pathname.\n *\n * The table is per-Application, handed to middleware that opts in via\n * {@link bindRoutePolicy}. Nothing global: two apps in one process (a test file,\n * an embedded admin app) each get their own.\n */\n\nimport type { RouteFlags } from './route-flag'\n\n/** Flags for one mounted route, keyed for lookup by an incoming request. */\ninterface PolicyEntry {\n  /** Compiled from the mounted path — `/users/:id` → `^/users/([^/]+)$`. */\n  readonly pattern: RegExp\n  readonly flags: RouteFlags\n}\n\nconst EMPTY: RouteFlags = new Map() as RouteFlags\n\n/**\n * Turn a mounted path into a matcher.\n *\n * Deliberately small: `:param` matches one segment, `*` matches the rest, and\n * everything else is literal. This is a *lookup* over paths the engine already\n * chose to mount, not a second router — if it ever disagrees with the engine,\n * the answer is fewer features here, not more.\n */\nfunction compile(path: string): RegExp {\n  const source = path\n    .replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&')\n    .replace(/\\/:[^/]+/g, '/([^/]+)')\n    .replace(/\\*/g, '.*')\n  return new RegExp(`^${source}/?$`)\n}\n\nexport class RoutePolicyTable {\n  /** Bucketed by method: an incoming request only scans its own verb. */\n  private readonly byMethod = new Map<string, PolicyEntry[]>()\n\n  add(method: string, path: string, flags: RouteFlags | undefined): void {\n    if (!flags || flags.size === 0) return // nothing to say about this route\n    const verb = method.toUpperCase()\n    const bucket = this.byMethod.get(verb) ?? []\n    bucket.push({ pattern: compile(path), flags })\n    this.byMethod.set(verb, bucket)\n  }\n\n  /**\n   * Flags that apply to `method pathname`, or an empty map when the path\n   * matches no flagged route — including when it matches no route at all,\n   * which is exactly the traffic this exists to keep visible.\n   */\n  lookup(method: string, pathname: string): RouteFlags {\n    const bucket = this.byMethod.get(method.toUpperCase())\n    if (!bucket) return EMPTY\n    for (const entry of bucket) {\n      if (entry.pattern.test(pathname)) return entry.flags\n    }\n    return EMPTY\n  }\n\n  /** Drop everything — the Application rebuilds on every HMR reload. */\n  clear(): void {\n    this.byMethod.clear()\n  }\n\n  get size(): number {\n    let total = 0\n    for (const bucket of this.byMethod.values()) total += bucket.length\n    return total\n  }\n}\n\n/**\n * Slot a middleware exposes to say \"hand me the policy table once routes are\n * mounted\". The Application calls it during setup; middleware that never\n * declares it is untouched.\n */\nexport const ROUTE_POLICY_SLOT: unique symbol = Symbol.for('kick.routePolicy') as never\n\n/** A middleware that accepts the policy table. */\nexport interface RoutePolicyAware {\n  [ROUTE_POLICY_SLOT]?: (table: RoutePolicyTable) => void\n}\n\n/**\n * Declare that `handler` wants the policy table.\n *\n * Explicit hand-off rather than a module-level singleton, so the table a\n * middleware reads is always the one belonging to the app that mounted it.\n */\nexport function bindRoutePolicy<T extends object>(\n  handler: T,\n  receive: (table: RoutePolicyTable) => void,\n): T {\n  Object.defineProperty(handler, ROUTE_POLICY_SLOT, { value: receive, enumerable: false })\n  return handler\n}\n\n/** Hand the table to a middleware if it declared the slot. */\nexport function offerRoutePolicy(handler: unknown, table: RoutePolicyTable): void {\n  const receive = (handler as RoutePolicyAware | null)?.[ROUTE_POLICY_SLOT]\n  if (typeof receive === 'function') receive(table)\n}\n"],"mappings":";;;;;;;;;;AA0BA,MAAM,MAAoB,IAAI,IAU9B,SAAS,QAAQ,KAAsB,CACrC,IAAM,OAAS,KACZ,QAAQ,qBAAsB,MAAM,CAAC,CACrC,QAAQ,YAAa,UAAU,CAAC,CAChC,QAAQ,MAAO,IAAI,EACtB,OAAW,OAAO,IAAI,OAAO,IAAI,CACnC,CAEA,IAAa,iBAAb,KAA8B,CAE5B,SAA4B,IAAI,IAEhC,IAAI,OAAgB,KAAc,MAAqC,CACrE,GAAI,CAAC,OAAS,MAAM,OAAS,EAAG,OAChC,IAAM,KAAO,OAAO,YAAY,EAC1B,OAAS,KAAK,SAAS,IAAI,IAAI,GAAK,CAAC,EAC3C,OAAO,KAAK,CAAE,QAAS,QAAQ,IAAI,EAAG,KAAM,CAAC,EAC7C,KAAK,SAAS,IAAI,KAAM,MAAM,CAChC,CAOA,OAAO,OAAgB,SAA8B,CACnD,IAAM,OAAS,KAAK,SAAS,IAAI,OAAO,YAAY,CAAC,EACrD,GAAI,CAAC,OAAQ,OAAO,MACpB,IAAK,IAAM,SAAS,OAClB,GAAI,MAAM,QAAQ,KAAK,QAAQ,EAAG,OAAO,MAAM,MAEjD,OAAO,KACT,CAGA,OAAc,CACZ,KAAK,SAAS,MAAM,CACtB,CAEA,IAAI,MAAe,CACjB,IAAI,MAAQ,EACZ,IAAK,IAAM,UAAU,KAAK,SAAS,OAAO,EAAG,OAAS,OAAO,OAC7D,OAAO,KACT,CACF,EAOA,MAAa,kBAAmC,OAAO,IAAI,kBAAkB,EAa7E,SAAgB,gBACd,QACA,QACG,CAEH,OADA,OAAO,eAAe,QAAS,kBAAmB,CAAE,MAAO,QAAS,WAAY,EAAM,CAAC,EAChF,OACT,CAGA,SAAgB,iBAAiB,QAAkB,MAA+B,CAChF,IAAM,QAAW,UAAsC,mBACnD,OAAO,SAAY,YAAY,QAAQ,KAAK,CAClD"}

package/dist/{router-builder-Cig7o4BH.mjs → router-builder-CzVjPs5y.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v9.0.2
+ * @forinda/kickjs v9.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,5 +8,5 @@
  *
  * @license MIT
  */
-import{METADATA}from"./core/interfaces.mjs";import{o as duplicateRouteError,t as Container}from"./container-DM3gPzGt.mjs";import{a as getMethodMeta,o as getMethodMetaOrUndefined,t as getClassMeta}from"./metadata-DrCyWXgz.mjs";import{a as getMethodFlagDeclarations,c as registerMountFlags,i as getClassFlagDeclarations,l as resolveRouteFlags,u as toFlagDeclarations}from"./route-flag-DEUYr5Br.mjs";import{i as MissingContributorError,n as DuplicateContributorError,t as ContributorCycleError}from"./context-errors-Cb4jKwm4.mjs";import{t as runContributors}from"./contributor-runner-Buxk3Ay_.mjs";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){let labels=rowsForKey.map((r,i)=>r.label??`${src}#${i}`);throw new DuplicateContributorError(key,labels)}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 splitBeforeValidation(pipeline,route){let early=pipeline.contributors.filter(reg=>reg.beforeValidation);if(early.length===0)return{early:null,late:pipeline};let earlyKeys=new Set(early.map(reg=>reg.key));for(let reg of early){let lateDep=reg.dependsOn.find(dep=>!earlyKeys.has(dep));if(lateDep!==void 0)throw Error(`Contributor '${reg.key}'${route?` on ${route}`:``} sets beforeValidation but depends on '${lateDep}', which runs after validation. Set beforeValidation on '${lateDep}' too, or remove it from '${reg.key}'.`)}let late=pipeline.contributors.filter(reg=>!reg.beforeValidation);return{early:Object.freeze({contributors:Object.freeze(early),keys:earlyKeys}),late:late.length===0?null:Object.freeze({contributors:Object.freeze(late),keys:new Set(late.map(reg=>reg.key))})}}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){let remaining=registrations.filter(r=>(indegree.get(r.key)??0)>0);throw new ContributorCycleError(reconstructCycle(remaining,byKey),route)}return sorted}function reconstructCycle(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}let _externalContributorSources=[];function _setExternalContributorSources(sources){_externalContributorSources=sources}function assertRouteUnique(registry,method,fullPath,owner){let key=`${method.toUpperCase()} ${fullPath.replace(/:[^/]+/g,`:*`)}`,prior=registry.get(key);if(prior!==void 0)throw duplicateRouteError(method.toUpperCase(),fullPath,owner,prior);registry.set(key,owner)}function buildRouteTable(controllerClass,options={}){let container=Container.getInstance(),externalSources=options.externalSources??_externalContributorSources,routes=getClassMeta(METADATA.ROUTES,controllerClass,[]),classMiddlewares=getClassMeta(METADATA.CLASS_MIDDLEWARES,controllerClass,[]),classContributors=getClassMeta(METADATA.CLASS_CONTRIBUTORS,controllerClass,[]),classFlagDeclarations=getClassFlagDeclarations(controllerClass),mountFlagDeclarations=toFlagDeclarations(options.mountFlags,`${controllerClass?.name??`controller`} mount flags`);registerMountFlags(controllerClass,mountFlagDeclarations);let entries=[];for(let route of routes){let method=route.method.toUpperCase(),fullPath=route.path||`/`,methodMiddlewares=getMethodMeta(METADATA.METHOD_MIDDLEWARES,controllerClass,route.handlerName,[]),fileUploadConfig=getMethodMetaOrUndefined(METADATA.FILE_UPLOAD,controllerClass,route.handlerName),methodContributors=getMethodMeta(METADATA.METHOD_CONTRIBUTORS,controllerClass,route.handlerName,[]),flags=resolveRouteFlags(classFlagDeclarations,getMethodFlagDeclarations(controllerClass,route.handlerName),mountFlagDeclarations),contributorRunner=null,earlyContributorRunner=null;if(classContributors.length>0||methodContributors.length>0||externalSources.length>0){let sources=[...methodContributors.map((registration,i)=>({source:`method`,registration,label:`${controllerClass.name}.${String(route.handlerName)}#${i}(${registration.key})`})),...classContributors.map((registration,i)=>({source:`class`,registration,label:`${controllerClass.name}.@class#${i}(${registration.key})`})),...externalSources],routeLabel=`${method} ${fullPath}`,{early,late}=splitBeforeValidation(buildPipeline(sources,{route:routeLabel}),routeLabel);early&&(earlyContributorRunner=ctx=>runContributors({pipeline:early,ctx,container,flags})),late&&(contributorRunner=ctx=>runContributors({pipeline:late,ctx,container,flags}))}let handler=ctx=>container.resolve(controllerClass)[route.handlerName](ctx);entries.push({method,path:fullPath,middlewares:[...classMiddlewares,...methodMiddlewares],contributorRunner,earlyContributorRunner,handler,meta:{controller:controllerClass,handlerName:route.handlerName,validation:route.validation,upload:fileUploadConfig,flags}})}return entries}export{buildPipeline as i,assertRouteUnique as n,buildRouteTable as r,_setExternalContributorSources as t};
-//# sourceMappingURL=router-builder-Cig7o4BH.mjs.map
+import{METADATA}from"./core/interfaces.mjs";import{o as duplicateRouteError,t as Container}from"./container-ZnfelY_a.mjs";import{a as getMethodMeta,o as getMethodMetaOrUndefined,t as getClassMeta}from"./metadata-CW4I35nN.mjs";import{a as getMethodFlagDeclarations,c as registerMountFlags,i as getClassFlagDeclarations,l as resolveRouteFlags,u as toFlagDeclarations}from"./route-flag-sIYXay3q.mjs";import{i as MissingContributorError,n as DuplicateContributorError,t as ContributorCycleError}from"./context-errors-Cgtrrqfs.mjs";import{t as runContributors}from"./contributor-runner-BSpshfPN.mjs";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){let labels=rowsForKey.map((r,i)=>r.label??`${src}#${i}`);throw new DuplicateContributorError(key,labels)}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 splitBeforeValidation(pipeline,route){let early=pipeline.contributors.filter(reg=>reg.beforeValidation);if(early.length===0)return{early:null,late:pipeline};let earlyKeys=new Set(early.map(reg=>reg.key));for(let reg of early){let lateDep=reg.dependsOn.find(dep=>!earlyKeys.has(dep));if(lateDep!==void 0)throw Error(`Contributor '${reg.key}'${route?` on ${route}`:``} sets beforeValidation but depends on '${lateDep}', which runs after validation. Set beforeValidation on '${lateDep}' too, or remove it from '${reg.key}'.`)}let late=pipeline.contributors.filter(reg=>!reg.beforeValidation);return{early:Object.freeze({contributors:Object.freeze(early),keys:earlyKeys}),late:late.length===0?null:Object.freeze({contributors:Object.freeze(late),keys:new Set(late.map(reg=>reg.key))})}}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){let remaining=registrations.filter(r=>(indegree.get(r.key)??0)>0);throw new ContributorCycleError(reconstructCycle(remaining,byKey),route)}return sorted}function reconstructCycle(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}let _externalContributorSources=[];function _setExternalContributorSources(sources){_externalContributorSources=sources}function assertRouteUnique(registry,method,fullPath,owner){let key=`${method.toUpperCase()} ${fullPath.replace(/:[^/]+/g,`:*`)}`,prior=registry.get(key);if(prior!==void 0)throw duplicateRouteError(method.toUpperCase(),fullPath,owner,prior);registry.set(key,owner)}function buildRouteTable(controllerClass,options={}){let container=Container.getInstance(),externalSources=options.externalSources??_externalContributorSources,routes=getClassMeta(METADATA.ROUTES,controllerClass,[]),classMiddlewares=getClassMeta(METADATA.CLASS_MIDDLEWARES,controllerClass,[]),classContributors=getClassMeta(METADATA.CLASS_CONTRIBUTORS,controllerClass,[]),classFlagDeclarations=getClassFlagDeclarations(controllerClass),mountFlagDeclarations=toFlagDeclarations(options.mountFlags,`${controllerClass?.name??`controller`} mount flags`);registerMountFlags(controllerClass,mountFlagDeclarations);let entries=[];for(let route of routes){let method=route.method.toUpperCase(),fullPath=route.path||`/`,methodMiddlewares=getMethodMeta(METADATA.METHOD_MIDDLEWARES,controllerClass,route.handlerName,[]),fileUploadConfig=getMethodMetaOrUndefined(METADATA.FILE_UPLOAD,controllerClass,route.handlerName),methodContributors=getMethodMeta(METADATA.METHOD_CONTRIBUTORS,controllerClass,route.handlerName,[]),flags=resolveRouteFlags(classFlagDeclarations,getMethodFlagDeclarations(controllerClass,route.handlerName),mountFlagDeclarations),contributorRunner=null,earlyContributorRunner=null;if(classContributors.length>0||methodContributors.length>0||externalSources.length>0){let sources=[...methodContributors.map((registration,i)=>({source:`method`,registration,label:`${controllerClass.name}.${String(route.handlerName)}#${i}(${registration.key})`})),...classContributors.map((registration,i)=>({source:`class`,registration,label:`${controllerClass.name}.@class#${i}(${registration.key})`})),...externalSources],routeLabel=`${method} ${fullPath}`,{early,late}=splitBeforeValidation(buildPipeline(sources,{route:routeLabel}),routeLabel);early&&(earlyContributorRunner=ctx=>runContributors({pipeline:early,ctx,container,flags})),late&&(contributorRunner=ctx=>runContributors({pipeline:late,ctx,container,flags}))}let handler=ctx=>container.resolve(controllerClass)[route.handlerName](ctx);entries.push({method,path:fullPath,middlewares:[...classMiddlewares,...methodMiddlewares],contributorRunner,earlyContributorRunner,handler,meta:{controller:controllerClass,handlerName:route.handlerName,validation:route.validation,upload:fileUploadConfig,flags}})}return entries}export{buildPipeline as i,assertRouteUnique as n,buildRouteTable as r,_setExternalContributorSources as t};
+//# sourceMappingURL=router-builder-CzVjPs5y.mjs.map

package/dist/{router-builder-Cig7o4BH.mjs.map → router-builder-CzVjPs5y.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"router-builder-Cig7o4BH.mjs","names":[],"sources":["../src/core/contributor-pipeline.ts","../src/http/router-builder.ts"],"sourcesContent":["import type { AnyContributorRegistration } from './context-decorator'\nimport {\n  ContributorCycleError,\n  DuplicateContributorError,\n  MissingContributorError,\n} from './context-errors'\n\n/**\n * Where a contributor was registered, ordered by precedence\n * (lower index wins). Mirrors `architecture.md` §20.4.\n *\n * Levels (highest → lowest precedence):\n * - `'method'` — `@LoadX` on a controller method.\n * - `'class'`  — `@LoadX` on a controller class.\n * - `'module'` — returned by `AppModule.contributors?()`. Per-module scope.\n * - `'adapter'` — returned by `AppAdapter.contributors?()`. Cross-cutting, applies\n *   to every module's routes.\n * - `'global'` — `ApplicationOptions.contributors`. App-wide default.\n */\nexport type ContributorSource = 'method' | 'class' | 'module' | 'adapter' | 'global'\n\n/** Precedence-ranked source list. Index = precedence; method (0) wins ties. */\nconst PRECEDENCE_ORDER: readonly ContributorSource[] = [\n  'method',\n  'class',\n  'module',\n  'adapter',\n  'global',\n]\n\n/**\n * Input row to {@link buildPipeline}. Pairs a registration with its origin\n * so dedup can apply the precedence rule and diagnostic errors can name\n * the offending site.\n *\n * `registration` is the type-erased {@link AnyContributorRegistration}\n * — the runner doesn't care about each registration's narrow `D` /\n * `Ctx` shape, and adopters frequently mix HTTP / transport-agnostic\n * contributors in the same `externalSources` / `contributors()`\n * array. The narrow generics from `defineContextDecorator` survive\n * at the *definition* site (where `resolve` is typed); they're erased\n * here so collections compose without `as any` casts.\n */\nexport interface SourcedRegistration {\n  registration: AnyContributorRegistration\n  source: ContributorSource\n  /** Human label surfaced in DuplicateContributorError messages. */\n  label?: string\n}\n\n/**\n * Resolved, validated, topo-sorted pipeline ready for execution.\n *\n * `contributors` is in execution order — every entry's `dependsOn`\n * keys appear earlier. `keys` is the set of all keys this pipeline\n * produces; the runner uses it for fast existence checks and the\n * builder uses it for missing-dep validation.\n */\nexport interface ContributorPipeline {\n  readonly contributors: readonly AnyContributorRegistration[]\n  readonly keys: ReadonlySet<string>\n}\n\nexport interface BuildPipelineOptions {\n  /** Optional route identifier surfaced in diagnostic errors (e.g., 'GET /projects/:id'). */\n  route?: string\n}\n\n/**\n * Build, validate, and topo-sort a contributor pipeline.\n *\n * Pipeline:\n *\n * 1. Group sources by precedence (method > class > module > adapter > global).\n * 2. Within each precedence level, two contributors with the same `key`\n *    raise {@link DuplicateContributorError}.\n * 3. Across levels, the highest-precedence contributor wins each key\n *    (lower-precedence duplicates are silently dropped — that is the\n *    documented override mechanism, not an error).\n * 4. Every key referenced by `dependsOn` must be produced by the\n *    surviving set, otherwise {@link MissingContributorError}.\n * 5. Kahn's algorithm topo-sorts the survivors. Any nodes left after\n *    the queue drains form a cycle → {@link ContributorCycleError}\n *    with a reconstructed path.\n *\n * Pure function — no DI, no I/O. Safe to call once at startup per\n * route and cache the result.\n */\nexport function buildPipeline(\n  sources: readonly SourcedRegistration[],\n  options: BuildPipelineOptions = {},\n): ContributorPipeline {\n  const route = options.route\n\n  // Step 1: group by source.\n  const bySource = new Map<ContributorSource, SourcedRegistration[]>()\n  for (const src of PRECEDENCE_ORDER) bySource.set(src, [])\n  for (const entry of sources) bySource.get(entry.source)!.push(entry)\n\n  // Step 2 + 3: dedup with precedence. We walk highest precedence first,\n  // claim its keys, and drop lower-precedence rows that conflict.\n  const winners = new Map<string, SourcedRegistration>()\n  for (const src of PRECEDENCE_ORDER) {\n    const rows = bySource.get(src)!\n    const keysAtThisLevel = new Map<string, SourcedRegistration[]>()\n    for (const row of rows) {\n      const key = row.registration.key\n      const existing = keysAtThisLevel.get(key) ?? []\n      existing.push(row)\n      keysAtThisLevel.set(key, existing)\n    }\n    for (const [key, rowsForKey] of keysAtThisLevel) {\n      if (rowsForKey.length > 1) {\n        const labels = rowsForKey.map((r, i) => r.label ?? `${src}#${i}`)\n        throw new DuplicateContributorError(key, labels)\n      }\n      if (!winners.has(key)) winners.set(key, rowsForKey[0])\n    }\n  }\n\n  const survivors = [...winners.values()].map((r) => r.registration)\n  const allKeys = new Set(survivors.map((r) => r.key))\n\n  // Step 4: dependsOn validation.\n  for (const reg of survivors) {\n    for (const dep of reg.dependsOn) {\n      if (!allKeys.has(dep)) {\n        throw new MissingContributorError(dep, reg.key, route, reg.definedAt)\n      }\n    }\n  }\n\n  // Step 5: Kahn topo-sort.\n  const sorted = topoSort(survivors, route)\n\n  return Object.freeze({\n    contributors: Object.freeze(sorted),\n    keys: allKeys,\n  })\n}\n\n/**\n * Split a built pipeline into the contributors that run before request\n * validation (`beforeValidation: true`) and the rest, which keep their place\n * after `@Middleware()`. Both halves stay in topo order.\n *\n * An early contributor can only depend on other early ones — its dependency\n * would not have run yet otherwise — so that fails here, at boot.\n */\nexport function splitBeforeValidation(\n  pipeline: ContributorPipeline,\n  route?: string,\n): { early: ContributorPipeline | null; late: ContributorPipeline | null } {\n  const early = pipeline.contributors.filter((reg) => reg.beforeValidation)\n  if (early.length === 0) return { early: null, late: pipeline }\n\n  const earlyKeys = new Set(early.map((reg) => reg.key))\n  for (const reg of early) {\n    const lateDep = reg.dependsOn.find((dep) => !earlyKeys.has(dep))\n    if (lateDep !== undefined) {\n      throw new Error(\n        `Contributor '${reg.key}'${route ? ` on ${route}` : ''} sets beforeValidation but ` +\n          `depends on '${lateDep}', which runs after validation. Set beforeValidation on ` +\n          `'${lateDep}' too, or remove it from '${reg.key}'.`,\n      )\n    }\n  }\n\n  const late = pipeline.contributors.filter((reg) => !reg.beforeValidation)\n  return {\n    early: Object.freeze({ contributors: Object.freeze(early), keys: earlyKeys }),\n    late:\n      late.length === 0\n        ? null\n        : Object.freeze({\n            contributors: Object.freeze(late),\n            keys: new Set(late.map((reg) => reg.key)),\n          }),\n  }\n}\n\n/**\n * Kahn's algorithm with deterministic ordering on ties.\n *\n * Nodes with no remaining incoming edges enter the queue in input\n * order. Cycles surface as nodes still present after the queue\n * drains; we reconstruct one cycle path for diagnostics.\n */\nfunction topoSort(\n  registrations: readonly AnyContributorRegistration[],\n  route: string | undefined,\n): AnyContributorRegistration[] {\n  // indegree[key] = number of unresolved dependsOn entries for key\n  const indegree = new Map<string, number>()\n  // dependents[depKey] = list of registrations that depend on depKey\n  const dependents = new Map<string, AnyContributorRegistration[]>()\n  const byKey = new Map<string, AnyContributorRegistration>()\n\n  for (const reg of registrations) {\n    indegree.set(reg.key, reg.dependsOn.length)\n    byKey.set(reg.key, reg)\n  }\n  for (const reg of registrations) {\n    for (const dep of reg.dependsOn) {\n      const list = dependents.get(dep) ?? []\n      list.push(reg)\n      dependents.set(dep, list)\n    }\n  }\n\n  // Initial queue: registrations with zero indegree, preserving input order.\n  const queue: AnyContributorRegistration[] = []\n  for (const reg of registrations) {\n    if (indegree.get(reg.key) === 0) queue.push(reg)\n  }\n\n  const sorted: AnyContributorRegistration[] = []\n  while (queue.length > 0) {\n    const node = queue.shift()!\n    sorted.push(node)\n    for (const dependent of dependents.get(node.key) ?? []) {\n      const next = (indegree.get(dependent.key) ?? 0) - 1\n      indegree.set(dependent.key, next)\n      if (next === 0) queue.push(dependent)\n    }\n  }\n\n  if (sorted.length !== registrations.length) {\n    const remaining = registrations.filter((r) => (indegree.get(r.key) ?? 0) > 0)\n    throw new ContributorCycleError(reconstructCycle(remaining, byKey), route)\n  }\n\n  return sorted\n}\n\n/**\n * Reconstruct one cycle path from the residual graph.\n *\n * Walks from any remaining node, following its first dependency that's\n * still in the residual set, until we revisit a node. The path returned\n * starts and ends with the same key so the message reads naturally:\n * `tenant → project → tenant`.\n */\nfunction reconstructCycle(\n  residual: readonly AnyContributorRegistration[],\n  byKey: ReadonlyMap<string, AnyContributorRegistration>,\n): string[] {\n  const residualKeys = new Set(residual.map((r) => r.key))\n  const start = residual[0].key\n  const path: string[] = [start]\n  const seen = new Set<string>([start])\n  let cursor: string = start\n\n  while (true) {\n    const reg = byKey.get(cursor)!\n    const nextDep = reg.dependsOn.find((d) => residualKeys.has(d))\n    if (nextDep === undefined) break\n    if (seen.has(nextDep)) {\n      // Trim the prefix that isn't part of the cycle.\n      const cycleStart = path.indexOf(nextDep)\n      return [...path.slice(cycleStart), nextDep]\n    }\n    path.push(nextDep)\n    seen.add(nextDep)\n    cursor = nextDep\n  }\n\n  // Fallback — couldn't reconstruct a strict cycle, return what we walked.\n  return path\n}\n","// Concrete-module imports (NOT the `../core` barrel): the barrel re-exports\n// the asset manager, whose eager `node:fs` import would poison the edge-safe\n// `@forinda/kickjs/web` entry graph that flows through this file.\nimport {\n  buildPipeline,\n  splitBeforeValidation,\n  type SourcedRegistration,\n} from '../core/contributor-pipeline'\nimport { runContributors } from '../core/contributor-runner'\nimport { Container } from '../core/container'\nimport { METADATA } from '../core/interfaces'\nimport type { ContributorRegistration } from '../core/context-decorator'\nimport type { FileUploadConfig, MiddlewareHandler, RouteDefinition } from '../core/decorators'\nimport { getClassMeta, getMethodMeta, getMethodMetaOrUndefined } from '../core/metadata'\nimport {\n  getClassFlagDeclarations,\n  getMethodFlagDeclarations,\n  registerMountFlags,\n  resolveRouteFlags,\n  toFlagDeclarations,\n  type RouteFlagDeclarations,\n} from '../core/route-flag'\nimport { duplicateRouteError } from '../core/kick-errors'\nimport type { CtxHandler, RouteEntry, RouteMethod } from './runtime'\n\n/**\n * Per-module SourcedRegistration[] threaded through the route-mount loop by\n * Application.setup(). Carries module + adapter + global contributors so\n * buildRouteTable() can merge them with class + method ones into a single pipeline.\n *\n * Module setup is sequential, so this slot is race-free. Cleared in a finally\n * block after each module mounts. Outside of Application setup the slot is\n * empty — direct buildRouteTable()/buildRoutes() callers (mostly tests) see only\n * class + method contributors unless they pass `externalSources` explicitly.\n *\n * Same idiom as `Container._requestStoreProvider`: an internal escape hatch for\n * cross-module wiring without inversion-of-control gymnastics.\n *\n * @internal\n */\nlet _externalContributorSources: readonly SourcedRegistration[] = []\n\n/** @internal — set by Application.setup() before each `mod.routes()` call. */\nexport function _setExternalContributorSources(sources: readonly SourcedRegistration[]): void {\n  _externalContributorSources = sources\n}\n\n/**\n * Boot-time duplicate-route guard shared by the node and web mount loops.\n *\n * Registers `METHOD /mounted/path` into `registry` and throws\n * {@link duplicateRouteError} (KICK006) if another handler already claimed\n * it. Param *names* are ignored — `/tasks/:id` and `/tasks/:taskId` are the\n * same route at dispatch time, so they collide here too.\n *\n * @internal\n */\nexport function assertRouteUnique(\n  registry: Map<string, string>,\n  method: string,\n  fullPath: string,\n  owner: string,\n): void {\n  const key = `${method.toUpperCase()} ${fullPath.replace(/:[^/]+/g, ':*')}`\n  const prior = registry.get(key)\n  if (prior !== undefined) {\n    throw duplicateRouteError(method.toUpperCase(), fullPath, owner, prior)\n  }\n  registry.set(key, owner)\n}\n\nexport interface BuildRoutesOptions {\n  /**\n   * Extra contributors to merge into the per-route pipeline at their declared\n   * precedence levels. Pass explicitly when calling buildRouteTable/buildRoutes\n   * outside the Application route-mount loop (typically in tests). When omitted,\n   * falls back to the slot set by Application.setup().\n   */\n  externalSources?: readonly SourcedRegistration[]\n  /**\n   * Flags the mounting module declares for every route on this controller\n   * (`ModuleRoutes.flags`). Lowest precedence — a class or method declaration\n   * of the same name wins, and `@Flag.off` on a method removes it.\n   */\n  mountFlags?: RouteFlagDeclarations\n}\n\n/**\n * Turn a controller class decorated with @Get, @Post, etc. into a plain-data\n * {@link RouteEntry}[] — the engine-neutral route table an {@link HttpRuntime}\n * materializes.\n *\n * What used to be per-handler Express `(req, res, next)` closures is now\n * captured as data: `middlewares` keep their `(ctx, next)` shape, the contributor\n * pipeline is pre-built into a `contributorRunner` closure, validation / upload\n * stay as metadata, and the terminal `handler` resolves the controller per-request\n * (to respect DI scoping) and invokes it. The runtime owns how these get wrapped\n * onto its engine.\n *\n * Routes use only the method-level decorator paths (e.g. @Get('/me') → '/me').\n * The @Controller path is NOT baked in — it is metadata for Swagger/introspection.\n * The module's routes().path is the single source of truth for the mount prefix,\n * which avoids path doubling when both the module and controller specify the path.\n *\n * The contributor pipeline is built here, so a cycle or missing `dependsOn`\n * throws at table-build time (boot) rather than on first request.\n */\nexport function buildRouteTable(\n  controllerClass: any,\n  options: BuildRoutesOptions = {},\n): RouteEntry[] {\n  const container = Container.getInstance()\n  const externalSources = options.externalSources ?? _externalContributorSources\n  const routes: RouteDefinition[] = getClassMeta<RouteDefinition[]>(\n    METADATA.ROUTES,\n    controllerClass,\n    [],\n  )\n\n  // Class-level middleware\n  const classMiddlewares: MiddlewareHandler[] = getClassMeta<MiddlewareHandler[]>(\n    METADATA.CLASS_MIDDLEWARES,\n    controllerClass,\n    [],\n  )\n\n  // Class-level Context Contributors (#107) — applied to every method on the\n  // controller. Method-level contributors are added per-route below.\n  const classContributors: ContributorRegistration[] = getClassMeta<ContributorRegistration[]>(\n    METADATA.CLASS_CONTRIBUTORS,\n    controllerClass,\n    [],\n  )\n\n  // Route flags declared on the controller — inherited by every method below\n  // unless a method declares the same flag `false` (see core/route-flag.ts).\n  const classFlagDeclarations = getClassFlagDeclarations(controllerClass)\n\n  // Flags the module declared for this whole mount. Recorded against the class\n  // so `getRouteFlags()` — the resolver Swagger and DevTools use, which sees no\n  // mount — reports what the runtime actually resolved.\n  const mountFlagDeclarations = toFlagDeclarations(\n    options.mountFlags,\n    `${controllerClass?.name ?? 'controller'} mount flags`,\n  )\n  registerMountFlags(controllerClass, mountFlagDeclarations)\n\n  const entries: RouteEntry[] = []\n\n  for (const route of routes) {\n    const method = route.method.toUpperCase() as RouteMethod\n    const fullPath = route.path || '/'\n\n    // Method-level middleware\n    const methodMiddlewares: MiddlewareHandler[] = getMethodMeta<MiddlewareHandler[]>(\n      METADATA.METHOD_MIDDLEWARES,\n      controllerClass,\n      route.handlerName,\n      [],\n    )\n\n    // @FileUpload decorator — runtime supplies the upload backend.\n    const fileUploadConfig = getMethodMetaOrUndefined<FileUploadConfig>(\n      METADATA.FILE_UPLOAD,\n      controllerClass,\n      route.handlerName,\n    )\n\n    // Context Contributor pipeline (#107) — class + method contributors,\n    // built once at mount time so cycle/missing-dep failures abort boot.\n    const methodContributors: ContributorRegistration[] = getMethodMeta<ContributorRegistration[]>(\n      METADATA.METHOD_CONTRIBUTORS,\n      controllerClass,\n      route.handlerName,\n      [],\n    )\n\n    // Flags in force for THIS route: class declarations overridden by method\n    // ones. Resolved at build time so the per-request cost is a map lookup.\n    const flags = resolveRouteFlags(\n      classFlagDeclarations,\n      getMethodFlagDeclarations(controllerClass, route.handlerName),\n      mountFlagDeclarations,\n    )\n\n    let contributorRunner: CtxHandler | null = null\n    let earlyContributorRunner: CtxHandler | null = null\n    if (\n      classContributors.length > 0 ||\n      methodContributors.length > 0 ||\n      externalSources.length > 0\n    ) {\n      // Labels are surfaced in DuplicateContributorError messages — include\n      // the registration's key + the original index so a same-key collision\n      // at one precedence level points at the conflicting decorator slot,\n      // not just the host method/class.\n      const sources: SourcedRegistration[] = [\n        ...methodContributors.map((registration, i): SourcedRegistration => ({\n          source: 'method',\n          registration,\n          label: `${controllerClass.name}.${String(route.handlerName)}#${i}(${registration.key})`,\n        })),\n        ...classContributors.map((registration, i): SourcedRegistration => ({\n          source: 'class',\n          registration,\n          label: `${controllerClass.name}.@class#${i}(${registration.key})`,\n        })),\n        ...externalSources,\n      ]\n      const routeLabel = `${method} ${fullPath}`\n      const { early, late } = splitBeforeValidation(\n        buildPipeline(sources, { route: routeLabel }),\n        routeLabel,\n      )\n      if (early) {\n        earlyContributorRunner = (ctx) =>\n          runContributors({ pipeline: early, ctx, container, flags })\n      }\n      if (late) {\n        contributorRunner = (ctx) => runContributors({ pipeline: late, ctx, container, flags })\n      }\n    }\n\n    // Terminal handler — resolve controller per-request to respect DI scoping.\n    const handler: CtxHandler = (ctx) => container.resolve(controllerClass)[route.handlerName](ctx)\n\n    entries.push({\n      method,\n      path: fullPath,\n      middlewares: [...classMiddlewares, ...methodMiddlewares],\n      contributorRunner,\n      earlyContributorRunner,\n      handler,\n      meta: {\n        controller: controllerClass,\n        handlerName: route.handlerName,\n        validation: route.validation,\n        upload: fileUploadConfig,\n        flags,\n      },\n    })\n  }\n\n  return entries\n}\n"],"mappings":"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"}
+{"version":3,"file":"router-builder-CzVjPs5y.mjs","names":[],"sources":["../src/core/contributor-pipeline.ts","../src/http/router-builder.ts"],"sourcesContent":["import type { AnyContributorRegistration } from './context-decorator'\nimport {\n  ContributorCycleError,\n  DuplicateContributorError,\n  MissingContributorError,\n} from './context-errors'\n\n/**\n * Where a contributor was registered, ordered by precedence\n * (lower index wins). Mirrors `architecture.md` §20.4.\n *\n * Levels (highest → lowest precedence):\n * - `'method'` — `@LoadX` on a controller method.\n * - `'class'`  — `@LoadX` on a controller class.\n * - `'module'` — returned by `AppModule.contributors?()`. Per-module scope.\n * - `'adapter'` — returned by `AppAdapter.contributors?()`. Cross-cutting, applies\n *   to every module's routes.\n * - `'global'` — `ApplicationOptions.contributors`. App-wide default.\n */\nexport type ContributorSource = 'method' | 'class' | 'module' | 'adapter' | 'global'\n\n/** Precedence-ranked source list. Index = precedence; method (0) wins ties. */\nconst PRECEDENCE_ORDER: readonly ContributorSource[] = [\n  'method',\n  'class',\n  'module',\n  'adapter',\n  'global',\n]\n\n/**\n * Input row to {@link buildPipeline}. Pairs a registration with its origin\n * so dedup can apply the precedence rule and diagnostic errors can name\n * the offending site.\n *\n * `registration` is the type-erased {@link AnyContributorRegistration}\n * — the runner doesn't care about each registration's narrow `D` /\n * `Ctx` shape, and adopters frequently mix HTTP / transport-agnostic\n * contributors in the same `externalSources` / `contributors()`\n * array. The narrow generics from `defineContextDecorator` survive\n * at the *definition* site (where `resolve` is typed); they're erased\n * here so collections compose without `as any` casts.\n */\nexport interface SourcedRegistration {\n  registration: AnyContributorRegistration\n  source: ContributorSource\n  /** Human label surfaced in DuplicateContributorError messages. */\n  label?: string\n}\n\n/**\n * Resolved, validated, topo-sorted pipeline ready for execution.\n *\n * `contributors` is in execution order — every entry's `dependsOn`\n * keys appear earlier. `keys` is the set of all keys this pipeline\n * produces; the runner uses it for fast existence checks and the\n * builder uses it for missing-dep validation.\n */\nexport interface ContributorPipeline {\n  readonly contributors: readonly AnyContributorRegistration[]\n  readonly keys: ReadonlySet<string>\n}\n\nexport interface BuildPipelineOptions {\n  /** Optional route identifier surfaced in diagnostic errors (e.g., 'GET /projects/:id'). */\n  route?: string\n}\n\n/**\n * Build, validate, and topo-sort a contributor pipeline.\n *\n * Pipeline:\n *\n * 1. Group sources by precedence (method > class > module > adapter > global).\n * 2. Within each precedence level, two contributors with the same `key`\n *    raise {@link DuplicateContributorError}.\n * 3. Across levels, the highest-precedence contributor wins each key\n *    (lower-precedence duplicates are silently dropped — that is the\n *    documented override mechanism, not an error).\n * 4. Every key referenced by `dependsOn` must be produced by the\n *    surviving set, otherwise {@link MissingContributorError}.\n * 5. Kahn's algorithm topo-sorts the survivors. Any nodes left after\n *    the queue drains form a cycle → {@link ContributorCycleError}\n *    with a reconstructed path.\n *\n * Pure function — no DI, no I/O. Safe to call once at startup per\n * route and cache the result.\n */\nexport function buildPipeline(\n  sources: readonly SourcedRegistration[],\n  options: BuildPipelineOptions = {},\n): ContributorPipeline {\n  const route = options.route\n\n  // Step 1: group by source.\n  const bySource = new Map<ContributorSource, SourcedRegistration[]>()\n  for (const src of PRECEDENCE_ORDER) bySource.set(src, [])\n  for (const entry of sources) bySource.get(entry.source)!.push(entry)\n\n  // Step 2 + 3: dedup with precedence. We walk highest precedence first,\n  // claim its keys, and drop lower-precedence rows that conflict.\n  const winners = new Map<string, SourcedRegistration>()\n  for (const src of PRECEDENCE_ORDER) {\n    const rows = bySource.get(src)!\n    const keysAtThisLevel = new Map<string, SourcedRegistration[]>()\n    for (const row of rows) {\n      const key = row.registration.key\n      const existing = keysAtThisLevel.get(key) ?? []\n      existing.push(row)\n      keysAtThisLevel.set(key, existing)\n    }\n    for (const [key, rowsForKey] of keysAtThisLevel) {\n      if (rowsForKey.length > 1) {\n        const labels = rowsForKey.map((r, i) => r.label ?? `${src}#${i}`)\n        throw new DuplicateContributorError(key, labels)\n      }\n      if (!winners.has(key)) winners.set(key, rowsForKey[0])\n    }\n  }\n\n  const survivors = [...winners.values()].map((r) => r.registration)\n  const allKeys = new Set(survivors.map((r) => r.key))\n\n  // Step 4: dependsOn validation.\n  for (const reg of survivors) {\n    for (const dep of reg.dependsOn) {\n      if (!allKeys.has(dep)) {\n        throw new MissingContributorError(dep, reg.key, route, reg.definedAt)\n      }\n    }\n  }\n\n  // Step 5: Kahn topo-sort.\n  const sorted = topoSort(survivors, route)\n\n  return Object.freeze({\n    contributors: Object.freeze(sorted),\n    keys: allKeys,\n  })\n}\n\n/**\n * Split a built pipeline into the contributors that run before request\n * validation (`beforeValidation: true`) and the rest, which keep their place\n * after `@Middleware()`. Both halves stay in topo order.\n *\n * An early contributor can only depend on other early ones — its dependency\n * would not have run yet otherwise — so that fails here, at boot.\n */\nexport function splitBeforeValidation(\n  pipeline: ContributorPipeline,\n  route?: string,\n): { early: ContributorPipeline | null; late: ContributorPipeline | null } {\n  const early = pipeline.contributors.filter((reg) => reg.beforeValidation)\n  if (early.length === 0) return { early: null, late: pipeline }\n\n  const earlyKeys = new Set(early.map((reg) => reg.key))\n  for (const reg of early) {\n    const lateDep = reg.dependsOn.find((dep) => !earlyKeys.has(dep))\n    if (lateDep !== undefined) {\n      throw new Error(\n        `Contributor '${reg.key}'${route ? ` on ${route}` : ''} sets beforeValidation but ` +\n          `depends on '${lateDep}', which runs after validation. Set beforeValidation on ` +\n          `'${lateDep}' too, or remove it from '${reg.key}'.`,\n      )\n    }\n  }\n\n  const late = pipeline.contributors.filter((reg) => !reg.beforeValidation)\n  return {\n    early: Object.freeze({ contributors: Object.freeze(early), keys: earlyKeys }),\n    late:\n      late.length === 0\n        ? null\n        : Object.freeze({\n            contributors: Object.freeze(late),\n            keys: new Set(late.map((reg) => reg.key)),\n          }),\n  }\n}\n\n/**\n * Kahn's algorithm with deterministic ordering on ties.\n *\n * Nodes with no remaining incoming edges enter the queue in input\n * order. Cycles surface as nodes still present after the queue\n * drains; we reconstruct one cycle path for diagnostics.\n */\nfunction topoSort(\n  registrations: readonly AnyContributorRegistration[],\n  route: string | undefined,\n): AnyContributorRegistration[] {\n  // indegree[key] = number of unresolved dependsOn entries for key\n  const indegree = new Map<string, number>()\n  // dependents[depKey] = list of registrations that depend on depKey\n  const dependents = new Map<string, AnyContributorRegistration[]>()\n  const byKey = new Map<string, AnyContributorRegistration>()\n\n  for (const reg of registrations) {\n    indegree.set(reg.key, reg.dependsOn.length)\n    byKey.set(reg.key, reg)\n  }\n  for (const reg of registrations) {\n    for (const dep of reg.dependsOn) {\n      const list = dependents.get(dep) ?? []\n      list.push(reg)\n      dependents.set(dep, list)\n    }\n  }\n\n  // Initial queue: registrations with zero indegree, preserving input order.\n  const queue: AnyContributorRegistration[] = []\n  for (const reg of registrations) {\n    if (indegree.get(reg.key) === 0) queue.push(reg)\n  }\n\n  const sorted: AnyContributorRegistration[] = []\n  while (queue.length > 0) {\n    const node = queue.shift()!\n    sorted.push(node)\n    for (const dependent of dependents.get(node.key) ?? []) {\n      const next = (indegree.get(dependent.key) ?? 0) - 1\n      indegree.set(dependent.key, next)\n      if (next === 0) queue.push(dependent)\n    }\n  }\n\n  if (sorted.length !== registrations.length) {\n    const remaining = registrations.filter((r) => (indegree.get(r.key) ?? 0) > 0)\n    throw new ContributorCycleError(reconstructCycle(remaining, byKey), route)\n  }\n\n  return sorted\n}\n\n/**\n * Reconstruct one cycle path from the residual graph.\n *\n * Walks from any remaining node, following its first dependency that's\n * still in the residual set, until we revisit a node. The path returned\n * starts and ends with the same key so the message reads naturally:\n * `tenant → project → tenant`.\n */\nfunction reconstructCycle(\n  residual: readonly AnyContributorRegistration[],\n  byKey: ReadonlyMap<string, AnyContributorRegistration>,\n): string[] {\n  const residualKeys = new Set(residual.map((r) => r.key))\n  const start = residual[0].key\n  const path: string[] = [start]\n  const seen = new Set<string>([start])\n  let cursor: string = start\n\n  while (true) {\n    const reg = byKey.get(cursor)!\n    const nextDep = reg.dependsOn.find((d) => residualKeys.has(d))\n    if (nextDep === undefined) break\n    if (seen.has(nextDep)) {\n      // Trim the prefix that isn't part of the cycle.\n      const cycleStart = path.indexOf(nextDep)\n      return [...path.slice(cycleStart), nextDep]\n    }\n    path.push(nextDep)\n    seen.add(nextDep)\n    cursor = nextDep\n  }\n\n  // Fallback — couldn't reconstruct a strict cycle, return what we walked.\n  return path\n}\n","// Concrete-module imports (NOT the `../core` barrel): the barrel re-exports\n// the asset manager, whose eager `node:fs` import would poison the edge-safe\n// `@forinda/kickjs/web` entry graph that flows through this file.\nimport {\n  buildPipeline,\n  splitBeforeValidation,\n  type SourcedRegistration,\n} from '../core/contributor-pipeline'\nimport { runContributors } from '../core/contributor-runner'\nimport { Container } from '../core/container'\nimport { METADATA } from '../core/interfaces'\nimport type { ContributorRegistration } from '../core/context-decorator'\nimport type { FileUploadConfig, MiddlewareHandler, RouteDefinition } from '../core/decorators'\nimport { getClassMeta, getMethodMeta, getMethodMetaOrUndefined } from '../core/metadata'\nimport {\n  getClassFlagDeclarations,\n  getMethodFlagDeclarations,\n  registerMountFlags,\n  resolveRouteFlags,\n  toFlagDeclarations,\n  type RouteFlagDeclarations,\n} from '../core/route-flag'\nimport { duplicateRouteError } from '../core/kick-errors'\nimport type { CtxHandler, RouteEntry, RouteMethod } from './runtime'\n\n/**\n * Per-module SourcedRegistration[] threaded through the route-mount loop by\n * Application.setup(). Carries module + adapter + global contributors so\n * buildRouteTable() can merge them with class + method ones into a single pipeline.\n *\n * Module setup is sequential, so this slot is race-free. Cleared in a finally\n * block after each module mounts. Outside of Application setup the slot is\n * empty — direct buildRouteTable()/buildRoutes() callers (mostly tests) see only\n * class + method contributors unless they pass `externalSources` explicitly.\n *\n * Same idiom as `Container._requestStoreProvider`: an internal escape hatch for\n * cross-module wiring without inversion-of-control gymnastics.\n *\n * @internal\n */\nlet _externalContributorSources: readonly SourcedRegistration[] = []\n\n/** @internal — set by Application.setup() before each `mod.routes()` call. */\nexport function _setExternalContributorSources(sources: readonly SourcedRegistration[]): void {\n  _externalContributorSources = sources\n}\n\n/**\n * Boot-time duplicate-route guard shared by the node and web mount loops.\n *\n * Registers `METHOD /mounted/path` into `registry` and throws\n * {@link duplicateRouteError} (KICK006) if another handler already claimed\n * it. Param *names* are ignored — `/tasks/:id` and `/tasks/:taskId` are the\n * same route at dispatch time, so they collide here too.\n *\n * @internal\n */\nexport function assertRouteUnique(\n  registry: Map<string, string>,\n  method: string,\n  fullPath: string,\n  owner: string,\n): void {\n  const key = `${method.toUpperCase()} ${fullPath.replace(/:[^/]+/g, ':*')}`\n  const prior = registry.get(key)\n  if (prior !== undefined) {\n    throw duplicateRouteError(method.toUpperCase(), fullPath, owner, prior)\n  }\n  registry.set(key, owner)\n}\n\nexport interface BuildRoutesOptions {\n  /**\n   * Extra contributors to merge into the per-route pipeline at their declared\n   * precedence levels. Pass explicitly when calling buildRouteTable/buildRoutes\n   * outside the Application route-mount loop (typically in tests). When omitted,\n   * falls back to the slot set by Application.setup().\n   */\n  externalSources?: readonly SourcedRegistration[]\n  /**\n   * Flags the mounting module declares for every route on this controller\n   * (`ModuleRoutes.flags`). Lowest precedence — a class or method declaration\n   * of the same name wins, and `@Flag.off` on a method removes it.\n   */\n  mountFlags?: RouteFlagDeclarations\n}\n\n/**\n * Turn a controller class decorated with @Get, @Post, etc. into a plain-data\n * {@link RouteEntry}[] — the engine-neutral route table an {@link HttpRuntime}\n * materializes.\n *\n * What used to be per-handler Express `(req, res, next)` closures is now\n * captured as data: `middlewares` keep their `(ctx, next)` shape, the contributor\n * pipeline is pre-built into a `contributorRunner` closure, validation / upload\n * stay as metadata, and the terminal `handler` resolves the controller per-request\n * (to respect DI scoping) and invokes it. The runtime owns how these get wrapped\n * onto its engine.\n *\n * Routes use only the method-level decorator paths (e.g. @Get('/me') → '/me').\n * The @Controller path is NOT baked in — it is metadata for Swagger/introspection.\n * The module's routes().path is the single source of truth for the mount prefix,\n * which avoids path doubling when both the module and controller specify the path.\n *\n * The contributor pipeline is built here, so a cycle or missing `dependsOn`\n * throws at table-build time (boot) rather than on first request.\n */\nexport function buildRouteTable(\n  controllerClass: any,\n  options: BuildRoutesOptions = {},\n): RouteEntry[] {\n  const container = Container.getInstance()\n  const externalSources = options.externalSources ?? _externalContributorSources\n  const routes: RouteDefinition[] = getClassMeta<RouteDefinition[]>(\n    METADATA.ROUTES,\n    controllerClass,\n    [],\n  )\n\n  // Class-level middleware\n  const classMiddlewares: MiddlewareHandler[] = getClassMeta<MiddlewareHandler[]>(\n    METADATA.CLASS_MIDDLEWARES,\n    controllerClass,\n    [],\n  )\n\n  // Class-level Context Contributors (#107) — applied to every method on the\n  // controller. Method-level contributors are added per-route below.\n  const classContributors: ContributorRegistration[] = getClassMeta<ContributorRegistration[]>(\n    METADATA.CLASS_CONTRIBUTORS,\n    controllerClass,\n    [],\n  )\n\n  // Route flags declared on the controller — inherited by every method below\n  // unless a method declares the same flag `false` (see core/route-flag.ts).\n  const classFlagDeclarations = getClassFlagDeclarations(controllerClass)\n\n  // Flags the module declared for this whole mount. Recorded against the class\n  // so `getRouteFlags()` — the resolver Swagger and DevTools use, which sees no\n  // mount — reports what the runtime actually resolved.\n  const mountFlagDeclarations = toFlagDeclarations(\n    options.mountFlags,\n    `${controllerClass?.name ?? 'controller'} mount flags`,\n  )\n  registerMountFlags(controllerClass, mountFlagDeclarations)\n\n  const entries: RouteEntry[] = []\n\n  for (const route of routes) {\n    const method = route.method.toUpperCase() as RouteMethod\n    const fullPath = route.path || '/'\n\n    // Method-level middleware\n    const methodMiddlewares: MiddlewareHandler[] = getMethodMeta<MiddlewareHandler[]>(\n      METADATA.METHOD_MIDDLEWARES,\n      controllerClass,\n      route.handlerName,\n      [],\n    )\n\n    // @FileUpload decorator — runtime supplies the upload backend.\n    const fileUploadConfig = getMethodMetaOrUndefined<FileUploadConfig>(\n      METADATA.FILE_UPLOAD,\n      controllerClass,\n      route.handlerName,\n    )\n\n    // Context Contributor pipeline (#107) — class + method contributors,\n    // built once at mount time so cycle/missing-dep failures abort boot.\n    const methodContributors: ContributorRegistration[] = getMethodMeta<ContributorRegistration[]>(\n      METADATA.METHOD_CONTRIBUTORS,\n      controllerClass,\n      route.handlerName,\n      [],\n    )\n\n    // Flags in force for THIS route: class declarations overridden by method\n    // ones. Resolved at build time so the per-request cost is a map lookup.\n    const flags = resolveRouteFlags(\n      classFlagDeclarations,\n      getMethodFlagDeclarations(controllerClass, route.handlerName),\n      mountFlagDeclarations,\n    )\n\n    let contributorRunner: CtxHandler | null = null\n    let earlyContributorRunner: CtxHandler | null = null\n    if (\n      classContributors.length > 0 ||\n      methodContributors.length > 0 ||\n      externalSources.length > 0\n    ) {\n      // Labels are surfaced in DuplicateContributorError messages — include\n      // the registration's key + the original index so a same-key collision\n      // at one precedence level points at the conflicting decorator slot,\n      // not just the host method/class.\n      const sources: SourcedRegistration[] = [\n        ...methodContributors.map((registration, i): SourcedRegistration => ({\n          source: 'method',\n          registration,\n          label: `${controllerClass.name}.${String(route.handlerName)}#${i}(${registration.key})`,\n        })),\n        ...classContributors.map((registration, i): SourcedRegistration => ({\n          source: 'class',\n          registration,\n          label: `${controllerClass.name}.@class#${i}(${registration.key})`,\n        })),\n        ...externalSources,\n      ]\n      const routeLabel = `${method} ${fullPath}`\n      const { early, late } = splitBeforeValidation(\n        buildPipeline(sources, { route: routeLabel }),\n        routeLabel,\n      )\n      if (early) {\n        earlyContributorRunner = (ctx) =>\n          runContributors({ pipeline: early, ctx, container, flags })\n      }\n      if (late) {\n        contributorRunner = (ctx) => runContributors({ pipeline: late, ctx, container, flags })\n      }\n    }\n\n    // Terminal handler — resolve controller per-request to respect DI scoping.\n    const handler: CtxHandler = (ctx) => container.resolve(controllerClass)[route.handlerName](ctx)\n\n    entries.push({\n      method,\n      path: fullPath,\n      middlewares: [...classMiddlewares, ...methodMiddlewares],\n      contributorRunner,\n      earlyContributorRunner,\n      handler,\n      meta: {\n        controller: controllerClass,\n        handlerName: route.handlerName,\n        validation: route.validation,\n        upload: fileUploadConfig,\n        flags,\n      },\n    })\n  }\n\n  return entries\n}\n"],"mappings":"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"}

package/dist/{runtime-C3izjAep.mjs → runtime-CDz5ayBt.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v9.0.2
+ * @forinda/kickjs v9.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,5 +8,5 @@
  *
  * @license MIT
  */
-import{METADATA}from"./core/interfaces.mjs";import{createLogger}from"./core/logger.mjs";import{n as getClassMetaOrUndefined}from"./metadata-DrCyWXgz.mjs";import{HttpException}from"./core/errors.mjs";import{t as ROUTE_SLOT}from"./route-flag-DEUYr5Br.mjs";import{l as requestStore}from"./context-DEntnLmq.mjs";function normalizeMediaType(contentType){return((Array.isArray(contentType)?contentType[0]:contentType)??``).split(`;`)[0].trim().toLowerCase()}function isJsonMediaType(mediaType){return mediaType===`application/json`||/^application\/[\w.+-]+\+json$/.test(mediaType)}function classifyMediaType(contentType){let mediaType=normalizeMediaType(contentType);return mediaType?isJsonMediaType(mediaType)?`json`:mediaType===`application/x-www-form-urlencoded`?`urlencoded`:mediaType.startsWith(`multipart/`)?`multipart`:mediaType.startsWith(`text/`)?`text`:`unsupported`:`unsupported`}const EXPRESS_JSON_TYPES=[`application/json`,`application/*+json`],SUPPORTED_BODY_TYPES=[`application/json`,`application/*+json`,`application/x-www-form-urlencoded`,`text/*`,`multipart/form-data`];function unsupportedMediaTypeError(contentType){let mediaType=normalizeMediaType(contentType);return new HttpException(415,mediaType?`Unsupported Media Type: ${mediaType}`:`Unsupported Media Type: request has a body but no Content-Type`,void 0,{Accept:SUPPORTED_BODY_TYPES.join(`, `)})}const BODY_METHODS=new Set([`POST`,`PUT`,`PATCH`,`DELETE`]);function rejectUnsupportedBody(){return(req,_res,next)=>{if(!BODY_METHODS.has((req.method??`GET`).toUpperCase())||classifyMediaType(req.headers?.[`content-type`])!==`unsupported`)return next();let reject=()=>next(unsupportedMediaTypeError(req.headers?.[`content-type`])),length=req.headers?.[`content-length`];if(length!==void 0)return length===`0`?next():reject();if(req.headers?.[`transfer-encoding`]===void 0)return next();let decided=!1,settle=fn=>()=>{decided||(decided=!0,req.off?.(`data`,onData),req.off?.(`end`,onEnd),fn())},onData=settle(reject),onEnd=settle(()=>next());req.on?.(`data`,onData),req.on?.(`end`,onEnd)}}const log=createLogger(`RequestScope`),preDestroyCache=new Map;function preDestroyMethod(ctor){let method=preDestroyCache.get(ctor);return method===void 0&&(method=getClassMetaOrUndefined(METADATA.PRE_DESTROY,ctor.prototype)??null,preDestroyCache.set(ctor,method)),method}function disposeRequestStore(store){if(!store.disposed&&(store.disposed=!0,store.instances.size!==0)){for(let instance of store.instances.values()){if(typeof instance!=`object`||!instance)continue;let method=preDestroyMethod(instance.constructor);if(method&&typeof instance[method]==`function`)try{let result=instance[method]();result&&typeof result.then==`function`&&result.catch(err=>log.error(err,`@PreDestroy on ${instance.constructor.name} rejected`))}catch(err){log.error(err,`@PreDestroy on ${instance.constructor.name} threw`)}}store.instances.clear()}}const REQUEST_SCOPE_MIDDLEWARE_MARKER=Symbol.for(`@kickjs/requestScopeMiddleware`);function createRequestStore(requestId){return{requestId:requestId||crypto.randomUUID(),instances:new Map,values:new Map}}function requestScopeMiddleware(){let mw=(req,res,next)=>{let requestIdHeader=req.headers[`x-request-id`],requestId=(Array.isArray(requestIdHeader)?requestIdHeader[0]:requestIdHeader)||crypto.randomUUID(),store=createRequestStore(requestId);req.requestId=requestId,res.once(`close`,()=>disposeRequestStore(store)),requestStore.run(store,next)};return mw[REQUEST_SCOPE_MIDDLEWARE_MARKER]=!0,mw}function isRequestScopeMiddleware(value){return typeof value==`function`&&value[REQUEST_SCOPE_MIDDLEWARE_MARKER]===!0}const REPLY_BRAND=Symbol.for(`kickjs.reply`);function reply(status,body){return{[REPLY_BRAND]:!0,status,body}}reply.ok=body=>reply(200,body),reply.created=body=>reply(201,body),reply.accepted=body=>reply(202,body),reply.noContent=()=>reply(204,void 0);function isReply(value){return typeof value==`object`&&!!value&&value[REPLY_BRAND]===!0}function applyHandlerResult(ctx,result){return result===void 0?!1:isReply(result)?result.status===204?(ctx.noContent(),!0):(ctx.json(result.body,result.status),!0):(ctx.json(result),!0)}function publishMatchedRoute(req,entry){req[ROUTE_SLOT]={method:entry.method,path:entry.path,controller:entry.meta.controller,handlerName:entry.meta.handlerName,flags:entry.meta.flags??EMPTY_FLAGS,pattern:entry.meta.pattern??entry.path}}const EMPTY_FLAGS=new Map;export{createRequestStore as a,requestScopeMiddleware as c,rejectUnsupportedBody as d,unsupportedMediaTypeError as f,reply as i,EXPRESS_JSON_TYPES as l,applyHandlerResult as n,disposeRequestStore as o,isReply as r,isRequestScopeMiddleware as s,publishMatchedRoute as t,classifyMediaType as u};
-//# sourceMappingURL=runtime-C3izjAep.mjs.map
+import{METADATA}from"./core/interfaces.mjs";import{createLogger}from"./core/logger.mjs";import{n as getClassMetaOrUndefined}from"./metadata-CW4I35nN.mjs";import{HttpException}from"./core/errors.mjs";import{t as ROUTE_SLOT}from"./route-flag-sIYXay3q.mjs";import{l as requestStore}from"./context-BGPof8bs.mjs";function normalizeMediaType(contentType){return((Array.isArray(contentType)?contentType[0]:contentType)??``).split(`;`)[0].trim().toLowerCase()}function isJsonMediaType(mediaType){return mediaType===`application/json`||/^application\/[\w.+-]+\+json$/.test(mediaType)}function classifyMediaType(contentType){let mediaType=normalizeMediaType(contentType);return mediaType?isJsonMediaType(mediaType)?`json`:mediaType===`application/x-www-form-urlencoded`?`urlencoded`:mediaType.startsWith(`multipart/`)?`multipart`:mediaType.startsWith(`text/`)?`text`:`unsupported`:`unsupported`}const EXPRESS_JSON_TYPES=[`application/json`,`application/*+json`],SUPPORTED_BODY_TYPES=[`application/json`,`application/*+json`,`application/x-www-form-urlencoded`,`text/*`,`multipart/form-data`];function unsupportedMediaTypeError(contentType){let mediaType=normalizeMediaType(contentType);return new HttpException(415,mediaType?`Unsupported Media Type: ${mediaType}`:`Unsupported Media Type: request has a body but no Content-Type`,void 0,{Accept:SUPPORTED_BODY_TYPES.join(`, `)})}const BODY_METHODS=new Set([`POST`,`PUT`,`PATCH`,`DELETE`]);function rejectUnsupportedBody(){return(req,_res,next)=>{if(!BODY_METHODS.has((req.method??`GET`).toUpperCase())||classifyMediaType(req.headers?.[`content-type`])!==`unsupported`)return next();let reject=()=>next(unsupportedMediaTypeError(req.headers?.[`content-type`])),length=req.headers?.[`content-length`];if(length!==void 0)return length===`0`?next():reject();if(req.headers?.[`transfer-encoding`]===void 0)return next();let decided=!1,settle=fn=>()=>{decided||(decided=!0,req.off?.(`data`,onData),req.off?.(`end`,onEnd),fn())},onData=settle(reject),onEnd=settle(()=>next());req.on?.(`data`,onData),req.on?.(`end`,onEnd)}}const log=createLogger(`RequestScope`),preDestroyCache=new Map;function preDestroyMethod(ctor){let method=preDestroyCache.get(ctor);return method===void 0&&(method=getClassMetaOrUndefined(METADATA.PRE_DESTROY,ctor.prototype)??null,preDestroyCache.set(ctor,method)),method}function disposeRequestStore(store){if(!store.disposed&&(store.disposed=!0,store.instances.size!==0)){for(let instance of store.instances.values()){if(typeof instance!=`object`||!instance)continue;let method=preDestroyMethod(instance.constructor);if(method&&typeof instance[method]==`function`)try{let result=instance[method]();result&&typeof result.then==`function`&&result.catch(err=>log.error(err,`@PreDestroy on ${instance.constructor.name} rejected`))}catch(err){log.error(err,`@PreDestroy on ${instance.constructor.name} threw`)}}store.instances.clear()}}const REQUEST_SCOPE_MIDDLEWARE_MARKER=Symbol.for(`@kickjs/requestScopeMiddleware`);function createRequestStore(requestId){return{requestId:requestId||crypto.randomUUID(),instances:new Map,values:new Map}}function requestScopeMiddleware(){let mw=(req,res,next)=>{let requestIdHeader=req.headers[`x-request-id`],requestId=(Array.isArray(requestIdHeader)?requestIdHeader[0]:requestIdHeader)||crypto.randomUUID(),store=createRequestStore(requestId);req.requestId=requestId,res.once(`close`,()=>disposeRequestStore(store)),requestStore.run(store,next)};return mw[REQUEST_SCOPE_MIDDLEWARE_MARKER]=!0,mw}function isRequestScopeMiddleware(value){return typeof value==`function`&&value[REQUEST_SCOPE_MIDDLEWARE_MARKER]===!0}const REPLY_BRAND=Symbol.for(`kickjs.reply`);function reply(status,body){return{[REPLY_BRAND]:!0,status,body}}reply.ok=body=>reply(200,body),reply.created=body=>reply(201,body),reply.accepted=body=>reply(202,body),reply.noContent=()=>reply(204,void 0);function isReply(value){return typeof value==`object`&&!!value&&value[REPLY_BRAND]===!0}function applyHandlerResult(ctx,result){return result===void 0?!1:isReply(result)?result.status===204?(ctx.noContent(),!0):(ctx.json(result.body,result.status),!0):(ctx.json(result),!0)}function publishMatchedRoute(req,entry){req[ROUTE_SLOT]={method:entry.method,path:entry.path,controller:entry.meta.controller,handlerName:entry.meta.handlerName,flags:entry.meta.flags??EMPTY_FLAGS,pattern:entry.meta.pattern??entry.path}}const EMPTY_FLAGS=new Map;export{createRequestStore as a,requestScopeMiddleware as c,rejectUnsupportedBody as d,unsupportedMediaTypeError as f,reply as i,EXPRESS_JSON_TYPES as l,applyHandlerResult as n,disposeRequestStore as o,isReply as r,isRequestScopeMiddleware as s,publishMatchedRoute as t,classifyMediaType as u};
+//# sourceMappingURL=runtime-CDz5ayBt.mjs.map

package/dist/{runtime-C3izjAep.mjs.map → runtime-CDz5ayBt.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"runtime-C3izjAep.mjs","names":[],"sources":["../src/http/body-policy.ts","../src/http/middleware/request-scope.ts","../src/http/reply.ts","../src/http/runtime.ts"],"sourcesContent":["/**\n * How a request body is interpreted, decided in ONE place for every runtime.\n *\n * Before this, each engine brought its own library's opinion: Express parsed\n * only exact `application/json` and silently left everything else `undefined`,\n * Fastify answered 415 for anything it had no parser for, and h3 routed\n * unrecognised types through `destr` — so the same request produced a parsed\n * object, an empty body, or a 415 depending on which engine the app was\n * configured with. The runtime is meant to be swappable; that made it not\n * swappable for any app accepting a body outside `application/json` (#590).\n *\n * @module @forinda/kickjs/http/body-policy\n */\n\nimport { HttpException } from '../core/errors'\n\n/**\n * A header as the runtimes hand it over. Node's `IncomingHttpHeaders` and\n * Fastify's normalised map both allow `string[]`, so take the union here\n * rather than casting at every call site.\n */\nexport type HeaderValue = string | string[] | undefined\n\n/** What the framework does with a body of a given media type. */\nexport type BodyKind =\n  /** Parse as JSON, strictly. */\n  | 'json'\n  /** Parse as `application/x-www-form-urlencoded` into an object. */\n  | 'urlencoded'\n  /** Hand the handler the raw string. Never JSON — see `classifyMediaType`. */\n  | 'text'\n  /** Left to the upload path, which consumes the stream itself. */\n  | 'multipart'\n  /** Not parsed. `ctx.body` stays undefined. */\n  | 'unsupported'\n\n/**\n * Strip parameters and normalise: `Application/JSON; charset=utf-8` →\n * `application/json`. h3's own check is `===` against the bare type, which is\n * why `application/json; charset=utf-8` — what most clients actually send —\n * missed it and fell to a non-strict branch.\n */\nexport function normalizeMediaType(contentType: HeaderValue): string {\n  const value = Array.isArray(contentType) ? contentType[0] : contentType\n  return (value ?? '').split(';')[0].trim().toLowerCase()\n}\n\n/**\n * `application/*+json` is JSON, and this is not a judgement call: RFC 6838\n * §4.2.8 says a media type \"MUST NOT be given names incorporating suffixes for\n * structured syntaxes they do not actually employ\", and RFC 6839 §2 exists so\n * receivers can \"do generic processing of the underlying representation\".\n * Spring, ASP.NET Core and Hono's validator all match the suffix by default.\n *\n * So `application/merge-patch+json` (RFC 7396) and `application/problem+json`\n * (RFC 9457) parse as JSON — which the framework already emits for every\n * problem response, and previously could not read back.\n */\nfunction isJsonMediaType(mediaType: string): boolean {\n  return mediaType === 'application/json' || /^application\\/[\\w.+-]+\\+json$/.test(mediaType)\n}\n\n/**\n * Decide how to treat a body, from its declared media type alone.\n *\n * `text/*` deliberately yields the raw string and is NEVER JSON-parsed.\n * `text/plain` is one of three CORS-safelisted content types, so it crosses\n * origins without a preflight; JSON-parsing it would re-open the simple-request\n * CSRF that requiring `application/json` closes. h3's own source carries this\n * warning, and h3 v2 pulled back from `destr` partly because of it.\n */\nexport function classifyMediaType(contentType: HeaderValue): BodyKind {\n  const mediaType = normalizeMediaType(contentType)\n  if (!mediaType) return 'unsupported'\n  if (isJsonMediaType(mediaType)) return 'json'\n  if (mediaType === 'application/x-www-form-urlencoded') return 'urlencoded'\n  if (mediaType.startsWith('multipart/')) return 'multipart'\n  if (mediaType.startsWith('text/')) return 'text'\n  return 'unsupported'\n}\n\n/**\n * Media types Express should hand to its JSON body parser. `express.json()`\n * defaults to the exact string `application/json`, and `type-is` will not match\n * `application/json` against a bare wildcard-plus-json pattern (a length guard rejects\n * it), so BOTH entries are required — passing only the wildcard silently stops\n * parsing ordinary JSON.\n */\nexport const EXPRESS_JSON_TYPES = ['application/json', 'application/*+json'] as const\n\n/** Media types the framework claims to parse, for diagnostics and docs. */\nexport const SUPPORTED_BODY_TYPES = [\n  'application/json',\n  'application/*+json',\n  'application/x-www-form-urlencoded',\n  'text/*',\n  'multipart/form-data',\n] as const\n\n/**\n * The 415 for a body whose media type the framework does not parse.\n *\n * Only ever raised when a body was actually SENT. An absent or empty body is\n * treated as absent regardless of its declared type — the same call Spring's\n * `readWithMessageConverters` and ASP.NET's `BodyModelBinder` both make, and\n * the reason neither rejects a bodyless POST. A bare `POST` with no payload is\n * a legitimate request, not an unsupported one.\n *\n * Carries `Accept`, which RFC 9110 §15.5.16 says a 415 \"can\" use to indicate\n * which media types would have been accepted.\n */\nexport function unsupportedMediaTypeError(contentType: HeaderValue): HttpException {\n  const mediaType = normalizeMediaType(contentType)\n  return new HttpException(\n    415,\n    mediaType\n      ? `Unsupported Media Type: ${mediaType}`\n      : 'Unsupported Media Type: request has a body but no Content-Type',\n    undefined,\n    { Accept: SUPPORTED_BODY_TYPES.join(', ') },\n  )\n}\n\n/** Verbs whose body the framework reads. */\nconst BODY_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])\n\n/**\n * Did this request actually carry a body? Decided from the framing headers\n * rather than from whether a parser produced anything — the distinction that\n * separates \"nothing was sent\" from \"something was sent that we could not\n * read\", which is the whole basis for answering 415 on one and 200 on the other.\n */\nexport function hasRequestBody(headers: Record<string, unknown>): boolean {\n  const length = headers['content-length'] as string | undefined\n  const encoding = headers['transfer-encoding'] as string | undefined\n  return encoding !== undefined || (length !== undefined && length !== '0')\n}\n\n/**\n * Connect middleware that answers 415 for a body Express's parsers left\n * untouched.\n *\n * Express has no concept of an unsupported type: a parser whose `type` does not\n * match simply calls `next()` and leaves `req.body` undefined, indistinguishable\n * from a request that sent nothing. Mounted after the parsers, this restores the\n * distinction so Express agrees with the other runtimes.\n */\nexport function rejectUnsupportedBody() {\n  return (req: any, _res: unknown, next: (err?: unknown) => void): void => {\n    if (!BODY_METHODS.has((req.method ?? 'GET').toUpperCase())) return next()\n    if (classifyMediaType(req.headers?.['content-type']) !== 'unsupported') return next()\n\n    const reject = (): void => next(unsupportedMediaTypeError(req.headers?.['content-type']))\n    const length = req.headers?.['content-length'] as string | undefined\n    if (length !== undefined) return length === '0' ? next() : reject()\n    if (req.headers?.['transfer-encoding'] === undefined) return next()\n\n    // Chunked: the framing headers say a body MAY follow, but an empty chunked\n    // post sends none. Deciding on the headers alone would 415 a request that\n    // sent nothing, so wait to see whether a byte actually arrives — the same\n    // distinction the other runtimes make by inspecting the read body.\n    let decided = false\n    const settle = (fn: () => void) => (): void => {\n      if (decided) return\n      decided = true\n      req.off?.('data', onData)\n      req.off?.('end', onEnd)\n      fn()\n    }\n    const onData = settle(reject)\n    const onEnd = settle(() => next())\n    req.on?.('data', onData)\n    req.on?.('end', onEnd)\n  }\n}\n","// Web Crypto via globalThis.crypto (randomUUID) — portable across\n// node/bun/deno/workers; node:crypto deliberately NOT imported here so this\n// module stays on the edge-safe request path.\nimport type { Request, Response, NextFunction } from 'express'\nimport { requestStore, type RequestStore } from '../request-store'\nimport { METADATA } from '../../core/interfaces'\nimport { getClassMetaOrUndefined } from '../../core/metadata'\nimport { createLogger } from '../../core/logger'\n\nconst log = createLogger('RequestScope')\n\n// Per-class @PreDestroy method-name cache: the metadata is immutable after\n// class definition, so pay the Reflect read once per class, not once per\n// instance per request. `null` = \"checked, none declared\".\nconst preDestroyCache = new Map<Function, string | symbol | null>()\n\nfunction preDestroyMethod(ctor: Function): string | symbol | null {\n  let method = preDestroyCache.get(ctor)\n  if (method === undefined) {\n    method =\n      getClassMetaOrUndefined<string | symbol>(METADATA.PRE_DESTROY, (ctor as any).prototype) ??\n      null\n    preDestroyCache.set(ctor, method)\n  }\n  return method\n}\n\n/**\n * Run `@PreDestroy` hooks on every REQUEST-scoped instance the request\n * created, then drop them. Called when the response closes (finished or\n * aborted) — the counterpart to `@PostConstruct`, closing the lifecycle gap\n * where per-request services holding transactions/handles/subscriptions were\n * silently dropped with no cleanup callback.\n *\n * Idempotent (guarded by `store.disposed`); hook errors are logged and\n * swallowed so one failing teardown can't break request completion. Async\n * hooks are fired without being awaited — the response is already gone.\n */\nexport function disposeRequestStore(store: RequestStore): void {\n  if (store.disposed) return\n  store.disposed = true\n  if (store.instances.size === 0) return\n  for (const instance of store.instances.values()) {\n    if (instance === null || typeof instance !== 'object') continue\n    const method = preDestroyMethod(instance.constructor)\n    if (!method || typeof instance[method] !== 'function') continue\n    try {\n      const result = instance[method]()\n      if (result && typeof result.then === 'function') {\n        ;(result as Promise<void>).catch((err) =>\n          log.error(err, `@PreDestroy on ${instance.constructor.name} rejected`),\n        )\n      }\n    } catch (err) {\n      log.error(err, `@PreDestroy on ${instance.constructor.name} threw`)\n    }\n  }\n  store.instances.clear()\n}\n\n/**\n * Marker symbol stamped on the function returned by {@link requestScopeMiddleware}.\n *\n * `Application.setup()` uses {@link isRequestScopeMiddleware} to detect whether\n * the user-supplied middleware list already contains the request-scope wrapper,\n * and skips its automatic auto-mount when one is found. Lets adopters control\n * the exact position of the ALS frame in their pipeline (e.g., after a custom\n * tracing wrapper) without ending up with two nested frames.\n */\n// `Symbol.for(...)` returns a plain `symbol` (not `unique symbol`), but the\n// runtime detection marker doesn't need the unique nominal property — it only\n// needs the interned-slot reference equality that `Symbol.for` already provides.\nconst REQUEST_SCOPE_MIDDLEWARE_MARKER = Symbol.for('@kickjs/requestScopeMiddleware')\n\n/**\n * Build a fresh per-request store. Shared by {@link requestScopeMiddleware}\n * (Express) and by runtimes whose handler runs outside the connect-middleware\n * chain (e.g. Fastify), so both establish an identical ALS frame.\n */\nexport function createRequestStore(requestId?: string): RequestStore {\n  return {\n    requestId: requestId || crypto.randomUUID(),\n    instances: new Map(),\n    // Explicit generic locks the \"string keys only\" decision.\n    values: new Map<string, unknown>(),\n  }\n}\n\n/**\n * Wraps each request in an AsyncLocalStorage context.\n * Enables REQUEST-scoped DI and automatic requestId propagation to logs.\n *\n * Should be mounted early in the middleware pipeline (before route handlers).\n * `Application` mounts this automatically unless `contextStore: 'manual'` is set\n * or the user already includes one in their middleware list.\n */\nexport function requestScopeMiddleware() {\n  const mw = (req: Request, res: Response, next: NextFunction) => {\n    const requestIdHeader = req.headers['x-request-id']\n    const requestId =\n      (Array.isArray(requestIdHeader) ? requestIdHeader[0] : requestIdHeader) || crypto.randomUUID()\n    const store = createRequestStore(requestId)\n    // Surface the requestId on req so the standalone requestId() middleware\n    // (when also mounted) reuses this value instead of generating a divergent\n    // second one. Without this, log lines that read from the ALS store would\n    // disagree with the X-Request-Id response header for any request that\n    // didn't carry an inbound x-request-id header.\n    ;(req as Request & { requestId?: string }).requestId = requestId\n    // 'close' fires once the response finished OR the client aborted — run\n    // @PreDestroy teardown for the request's scoped instances either way.\n    res.once('close', () => disposeRequestStore(store))\n    // Pass `next` directly — `run` invokes it with no args, so the arrow\n    // wrapper previously allocated per request added nothing.\n    requestStore.run(store, next)\n  }\n  ;(mw as unknown as Record<symbol, unknown>)[REQUEST_SCOPE_MIDDLEWARE_MARKER] = true\n  return mw\n}\n\n/**\n * Returns `true` when `value` is the function produced by {@link requestScopeMiddleware}.\n *\n * Detection uses a `Symbol.for(...)` marker so the check survives different\n * copies of `@forinda/kickjs` loaded under different module identities (e.g.,\n * a published package alongside a workspace-linked one during local dev).\n */\nexport function isRequestScopeMiddleware(value: unknown): boolean {\n  if (typeof value !== 'function') return false\n  return (value as unknown as Record<symbol, unknown>)[REQUEST_SCOPE_MIDDLEWARE_MARKER] === true\n}\n","// Return-value handler support.\n//\n// Handlers may RETURN their response payload instead of calling `ctx.json`:\n// the runtime auto-sends it when the pipeline finishes with nothing written.\n// `reply(status, body)` wraps a payload with a non-200 status while staying\n// transparent to type inference (`Reply<201, Task>` carries both statically).\n//\n// Edge-safe: no node imports — shared by all four runtimes including the\n// `@forinda/kickjs/web` entry.\n\nimport type { RequestContext } from './context'\nimport type { RuntimeResponse } from './runtime'\n\n// `Symbol.for` so the brand survives duplicate module copies (workspace-linked\n// + published package in one process — same rationale as the request-scope\n// middleware marker).\nconst REPLY_BRAND = Symbol.for('kickjs.reply')\n\n/**\n * A status-carrying response payload for return-value handlers. Create via\n * {@link reply} — the brand is what runtimes detect, and the generics are\n * what the `kick/routes` response typegen unwraps (`Reply<S, T>` → `T`).\n */\nexport interface Reply<S extends number = number, T = unknown> {\n  readonly [REPLY_BRAND]: true\n  readonly status: S\n  readonly body: T\n}\n\n/**\n * Wrap a return-value handler's payload with an explicit status code:\n *\n * ```ts\n * @Post('/')\n * async create(ctx: RequestContext) {\n *   return reply(201, await this.tasks.create(ctx.body))\n * }\n * ```\n */\nexport function reply<S extends number, T>(status: S, body: T): Reply<S, T> {\n  return { [REPLY_BRAND]: true, status, body }\n}\n\n/** `reply(200, body)` — explicit form of a bare `return body`. */\nreply.ok = <T>(body: T): Reply<200, T> => reply(200, body)\n/** `reply(201, body)` */\nreply.created = <T>(body: T): Reply<201, T> => reply(201, body)\n/** `reply(202, body)` */\nreply.accepted = <T>(body: T): Reply<202, T> => reply(202, body)\n/** Empty 204 — maps to `ctx.noContent()`. */\nreply.noContent = (): Reply<204, undefined> => reply(204, undefined)\n\n/**\n * The statically-inferred response type of a controller handler — what\n * `kick typegen` emits into `KickRoutes[...].response`:\n *\n * - `Awaited<ReturnType>` of the method\n * - `Reply<S, T>` unwraps to `T`\n * - `void`/`undefined` members are dropped (imperative `ctx.json` branches);\n *   a handler that never returns a value stays `unknown`, matching the\n *   pre-inference emission\n *\n * ```ts\n * type R = InferHandlerResponse<UsersController['get']> // → User\n * ```\n */\nexport type InferHandlerResponse<H> = H extends (...args: never[]) => infer R\n  ? [Exclude<Awaited<R>, void | undefined>] extends [never]\n    ? unknown\n    : UnwrapReply<Exclude<Awaited<R>, void | undefined>>\n  : unknown\n\ntype UnwrapReply<A> =\n  A extends Reply<number, infer B>\n    ? B\n    : A extends RuntimeResponse\n      ? // The engine's own response object says nothing about the body, so a\n        // handler ending `return ctx.json(...)` degrades to `unknown` — which is\n        // what the typegen comment always claimed happened. It did not: the bare\n        // `RuntimeResponse` leaked into `KickRoutes[...].response`, offering\n        // `.status()` / `.setHeader()` to a client expecting a payload.\n        // Confidently wrong is worse than unknown.\n        //\n        // To carry a payload, return it (`return user`) or wrap it\n        // (`return reply(201, user)`) — that is what `reply` is for.\n        unknown\n      : A\n\nexport function isReply(value: unknown): value is Reply {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as Record<symbol, unknown>)[REPLY_BRAND] === true\n  )\n}\n\n/**\n * Send a handler's RETURN value when the pipeline finished without anything\n * having written a response. Callers guard on \"driver/response unsettled\" —\n * this only decides how to send:\n *\n * - `undefined` → not handled (returns false; runtime keeps today's behavior)\n * - `Reply` wrapper → status + body (204 → `ctx.noContent()`)\n * - anything else → `ctx.json(value)` (200)\n *\n * Returns true when a response was produced.\n */\nexport function applyHandlerResult(ctx: RequestContext, result: unknown): boolean {\n  if (result === undefined) return false\n  if (isReply(result)) {\n    // Only 204 maps to noContent — an undefined body must NOT coerce the\n    // declared status (reply(304, undefined) keeps its 304; the json body\n    // is simply empty).\n    if (result.status === 204) {\n      ctx.noContent()\n      return true\n    }\n    ctx.json(result.body, result.status)\n    return true\n  }\n  ctx.json(result)\n  return true\n}\n","// The HttpRuntime seam.\n//\n// Decorators no longer emit an `express.Router` directly. `buildRouteTable()`\n// turns controller metadata into a plain-data `RouteEntry[]`; an `HttpRuntime`\n// materializes that table onto whatever engine it owns. Express is the default\n// runtime and the only one shipped in M1 — its materializer reproduces the exact\n// handler chain the old `buildRoutes()` built, so behavior is unchanged.\n//\n// Fastify / h3 runtimes (later milestones) consume the SAME `RouteEntry` data\n// and the SAME `HttpRuntime` contract; the request/response driver abstraction\n// that lets `RequestContext` run engine-agnostically lands with them (M3), since\n// under Express the drivers ARE the Express request/response objects already.\n//\n// Why a seam: running Fastify / h3 behind an Express-compat layer\n// (`@fastify/express`, h3's node bridge) bypasses their router and\n// serialization, and rebuilding `ctx` over web-standard Request/Response\n// would break SSE / streaming, multer uploads and `ctx.res` for every adopter.\n// The seam keeps `ctx` and swaps only the engine underneath it.\n\nimport { ROUTE_SLOT, type RouteFlags } from '../core/route-flag'\nimport type { IncomingMessage, ServerResponse } from 'node:http'\nimport type {\n  RequestHandler,\n  ErrorRequestHandler,\n  Express,\n  Request as ExpressRequest,\n  Response as ExpressResponse,\n} from 'express'\n\nimport type { Constructor, FileUploadConfig, MiddlewareHandler, RouteDefinition } from '../core'\nimport type { RequestContext } from './context'\n\n/** HTTP verbs the router emits. Mirrors the decorator surface (@Get/@Post/...). */\nexport type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'\n\n/**\n * A context-based handler: the runtime-neutral unit of the request pipeline.\n * Contributors, route middleware (via {@link MiddlewareHandler}), and the\n * terminal controller call all reduce to this shape. The runtime owns how a\n * `CtxHandler` is wrapped onto its engine (Express wraps it in `(req, res,\n * next)`; Fastify in its own handler).\n */\nexport type CtxHandler = (ctx: RequestContext) => unknown | Promise<unknown>\n\n/**\n * Connect-style middleware — the portable middleware format. Built-in\n * middleware and adopter-supplied Express middleware are this shape. The\n * Express runtime hands them straight to `app.use`; later runtimes bridge\n * them (Fastify via `@fastify/middie`, h3 via its node adapter).\n *\n * Typed as the Express handler union for M1 (Express is the only runtime);\n * a future milestone narrows this to bare node `(req, res, next)` primitives\n * once the driver layer lands.\n */\nexport type ConnectMiddleware = RequestHandler | ErrorRequestHandler\n\n/**\n * One materialized route, as plain data. Produced by {@link buildRouteTable}\n * from decorator metadata; consumed by {@link HttpRuntime.mountRoutes}.\n *\n * The shape is deliberately richer than a flat `CtxHandler[]`: `middlewares`\n * keep the `(ctx, next)` signature (they may short-circuit or call `next(err)`),\n * `contributorRunner` is a closure over the pre-built pipeline + container (the\n * pipeline is built — and any cycle / missing-dep error thrown — at table-build\n * time, i.e. boot), and `validation` / `upload` stay as metadata the runtime\n * materializes its own way. Faithfully reproducing the legacy Express chain —\n * not collapsing it — is what keeps M1 behavior-neutral.\n */\nexport interface RouteEntry {\n  method: RouteMethod\n  /** Path with `:param` segments — the portable subset all engines accept. */\n  path: string\n  /** Class + method middleware, in execution order; each receives `(ctx, next)`. */\n  middlewares: MiddlewareHandler[]\n  /**\n   * Runs the contributor pipeline against `ctx` (populates `ctx.set(...)`),\n   * or `null` when no contributors apply. Closes over the built pipeline and\n   * the DI container so it stays engine-neutral; the runtime advances the\n   * chain (Express: call `next()`) once it resolves.\n   */\n  contributorRunner: CtxHandler | null\n  /**\n   * Contributors registered with `beforeValidation: true`. Runtimes run this\n   * right after publishing the matched route — before validation, upload and\n   * middleware — so a rejection (401) lands before a malformed body's 422.\n   * Absent or `null` when no contributor asks for it.\n   */\n  earlyContributorRunner?: CtxHandler | null\n  /** Terminal handler: resolves the controller per-request and invokes it. */\n  handler: CtxHandler\n  /** Introspection + runtime-materialized concerns (swagger/typegen read this). */\n  meta: RouteMeta\n}\n\n/** Per-route metadata: introspection refs plus runtime-materialized concerns. */\nexport interface RouteMeta {\n  /**\n   * Owning controller class — for DI resolution and adapter introspection.\n   * Absent for ad-hoc routes registered through {@link AdapterHttp.route},\n   * which have no controller class behind them.\n   */\n  controller?: Constructor\n  /** Handler method name on the controller, when there is one. */\n  handlerName?: string\n  /** Zod/JSON-schema validation config from the route decorator, if any. */\n  validation?: RouteDefinition['validation']\n  /** `@FileUpload` config, if present — the runtime supplies the backend. */\n  upload?: FileUploadConfig\n  /**\n   * Route flags in force here, resolved at build time (method over class).\n   * Enabled flags only: a flag declared `false` at a higher-precedence site is\n   * absent rather than present-and-false, so `has()` is always the right\n   * question. See `core/route-flag.ts`.\n   */\n  flags?: RouteFlags\n  /**\n   * The full mounted pattern (`/api/v1/users/:id`) — set by the Application\n   * for controller routes. `path` is relative to the module mount.\n   */\n  pattern?: string\n}\n\n/**\n * The route a request matched, published on `ctx.route`.\n *\n * Everything that holds a {@link RequestContext} — handlers, `@Middleware()`,\n * guards, contributors — can read it, which is what lets one declaration on a\n * route serve every consumer.\n */\n/**\n * Publish the matched route on the request, for `ctx.route` to read.\n *\n * Called by each runtime once per dispatch, before it builds a RequestContext.\n * It lives on `req` rather than on the ctx because the Express runtime\n * constructs a fresh RequestContext per middleware step — anything written to\n * one ctx would be invisible to the next and to the handler.\n */\nexport function publishMatchedRoute(req: unknown, entry: RouteEntry): void {\n  ;(req as Record<symbol, MatchedRoute>)[ROUTE_SLOT] = {\n    method: entry.method,\n    path: entry.path,\n    controller: entry.meta.controller,\n    handlerName: entry.meta.handlerName,\n    flags: entry.meta.flags ?? EMPTY_FLAGS,\n    pattern: entry.meta.pattern ?? entry.path,\n  }\n}\n\nconst EMPTY_FLAGS: RouteFlags = new Map() as RouteFlags\n\nexport interface MatchedRoute {\n  method: RouteMethod\n  /** Path as declared on the handler, e.g. `/:id`. */\n  path: string\n  /**\n   * The full route pattern including the mount prefix and version, e.g.\n   * `/api/v1/users/:id` — what metrics and spans should be keyed by. Falls\n   * back to `path` for routes registered without a mount.\n   */\n  pattern: string\n  controller?: Constructor\n  handlerName?: string\n  /** Enabled flags only — see {@link RouteMeta.flags}. */\n  flags: RouteFlags\n}\n\n/** A controller's routes grouped under the module mount prefix. */\nexport type RouteTable = { mountPath: string; routes: RouteEntry[] }[]\n\n/**\n * The response surface {@link RequestContext}'s helpers (`json` / `html` /\n * `sse` / `download` / `render` / `problem`) drive, instead of calling Express\n * `res` methods directly (spec §4.3). Sized so `express.Response` satisfies it\n * structurally — under the Express runtime the driver IS the Express response,\n * so there is no wrapping and no behavior change. Other runtimes (Fastify / h3)\n * provide a thin object implementing this over their native reply.\n *\n * The terminal methods return `RuntimeResponse` for fluent chaining (Express's\n * `Response` is assignable, since it is a superset).\n */\nexport interface RuntimeResponse {\n  status(code: number): RuntimeResponse\n  json(data: unknown): RuntimeResponse\n  send(data: unknown): RuntimeResponse\n  type(contentType: string): RuntimeResponse\n  setHeader(name: string, value: string | number | readonly string[]): unknown\n  render(view: string, data?: Record<string, unknown>): unknown\n  writeHead(statusCode: number, headers?: Record<string, string>): unknown\n  flushHeaders(): unknown\n  write(chunk: string | Buffer): boolean\n  end(data?: unknown): unknown\n  once(event: 'close' | 'drain', listener: () => void): unknown\n  readonly headersSent: boolean\n}\n\n// ── Runtime-typed escape hatches (spec §4.3b) ─────────────────────────────\n\n/**\n * Per-runtime type map: the engine-native request / response / app types an\n * `HttpRuntime` exposes through `ctx.req.raw` / `ctx.res.raw` / `AdapterContext.app`.\n */\nexport interface RuntimeTypeMap {\n  request: unknown\n  response: unknown\n  app: unknown\n}\n\n/** The Express runtime's native types — the default when nothing is augmented. */\nexport interface ExpressRuntimeTypes {\n  request: ExpressRequest\n  response: ExpressResponse\n  app: Express\n}\n\n/**\n * Augmentable runtime registry. Empty by default; the `kick/runtime` typegen\n * plugin emits a `{ runtime: <RuntimeTypeMap> }` augmentation from the configured\n * runtime, which flips the engine-native escape-hatch types — `AdapterContext.app`,\n * `getRuntimeApp()`, and (once the driver layer lands) `ctx.req.raw` / `ctx.res.raw`\n * — to that runtime. Mirrors `KickDbRegister` / `KickEnv`, so the type story is\n * uniform with `kick/db` and env typing.\n *\n * @example\n * ```ts\n * // .kickjs/types/kick__runtime.d.ts — generated by typegen\n * declare module '@forinda/kickjs' {\n *   interface KickRuntimeRegister {\n *     runtime: import('@forinda/kickjs/fastify').FastifyRuntimeTypes\n *   }\n * }\n * ```\n */\n\nexport interface KickRuntimeRegister {}\n\n/** The active runtime's type map — the augmented one, or Express by default. */\nexport type ActiveRuntime = KickRuntimeRegister extends { runtime: infer R extends RuntimeTypeMap }\n  ? R\n  : ExpressRuntimeTypes\n\n/** Options passed to {@link HttpRuntime.createApp}. */\nexport interface RuntimeAppOptions {\n  /**\n   * Express `trust proxy` setting (and the equivalent on other engines). The\n   * function form is Express-specific; other runtimes interpret the simpler\n   * shapes (or normalize X-Forwarded-For themselves — see spec §10 Q1).\n   */\n  trustProxy?: boolean | string | number | string[] | ((ip: string, hopIndex: number) => boolean)\n}\n\n/** Where a connect middleware sits and what it scopes to. */\nexport interface UseConnectOptions {\n  path?: string | RegExp | ReadonlyArray<string | RegExp>\n}\n\n/**\n * Optional engine capabilities. Absence means the corresponding `ctx` feature\n * raises a clear error on that runtime rather than failing obscurely.\n */\nexport interface RuntimeCapabilities {\n  /** View-engine rendering (`ctx.render`). Express: true; Fastify/h3: false initially. */\n  render: boolean\n  /** File uploads (`ctx.file` / `@FileUpload`). All engines, different backends. */\n  uploads: boolean\n  /** Connect-style middleware. Express/Fastify(middie): true; h3: best-effort. */\n  connectMiddleware: boolean\n  /**\n   * The engine parses request bodies itself (Fastify, h3). When true, the\n   * Application skips its default `express.json()` so the body stream isn't\n   * consumed twice (which would deadlock the engine's own parser). Express:\n   * false — it relies on the `express.json()` connect middleware.\n   */\n  nativeBodyParsing: boolean\n  /**\n   * The engine's `nodeHandler` works behind `node:http2` (the HTTP/2\n   * compatibility API), so `server: { http2: true }` may use it. Fastify/h3:\n   * true. Express: false — it does not run on that layer. Absent = false, so\n   * custom runtimes opt in explicitly.\n   */\n  http2?: boolean\n}\n\n/**\n * The engine driver. KickJS owns decorators → {@link RouteTable}, the\n * contributor pipeline, the `RequestContext` surface, and error mapping. The\n * runtime owns app/server creation, route materialization, connect-middleware\n * registration, static serving, and the terminal not-found / error handlers.\n *\n * `expressRuntime()` is the default and the M1 reference implementation.\n */\nexport interface HttpRuntime<TApp = unknown> {\n  readonly name: 'express' | 'fastify' | 'h3' | (string & {})\n\n  /** Create the engine app. Called once per Application (and per HMR rebuild). */\n  createApp(options?: RuntimeAppOptions): TApp\n\n  /**\n   * Node-compatible request listener — the transport contract.\n   * `http.createServer(handler)` in prod, Vite post-middleware in dev. MUST\n   * invoke `next` (when given) instead of 404-ing if no route matched — the\n   * Vite dev chain depends on fall-through.\n   */\n  nodeHandler(\n    app: TApp,\n  ): (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void\n\n  /** Materialize the framework-built route table onto the engine. */\n  mountRoutes(app: TApp, table: RouteTable): void\n\n  /** Register a connect-style middleware (built-ins + adopter middleware). */\n  useConnect(app: TApp, mw: ConnectMiddleware, opts?: UseConnectOptions): void\n\n  /** Serve a static directory (swagger-ui assets, devtools SPA). */\n  serveStatic(app: TApp, prefix: string, dir: string): void\n\n  /** Terminal not-found handler. */\n  setNotFound(app: TApp, mw: ConnectMiddleware): void\n\n  /** Terminal error handler. */\n  setErrorHandler(app: TApp, mw: ConnectMiddleware): void\n\n  readonly capabilities: RuntimeCapabilities\n}\n\n/**\n * The supported surface adapters use to add HTTP routes, mounts, static dirs,\n * and middleware — engine-agnostic, in place of reaching for the raw Express\n * `app` (spec §4.4). Exposed as {@link AdapterContext.http}. Built by the\n * Application over the active {@link HttpRuntime}, so an adapter written against\n * this works under any runtime; the raw `app` escape hatch stays available for\n * the rare engine-specific need.\n */\nexport interface AdapterHttp {\n  /** Register a single context-handler route (e.g. a docs or transport endpoint). */\n  route(method: RouteMethod, path: string, handler: CtxHandler): void\n  /** Mount a pre-built route table under a path prefix. */\n  mount(prefix: string, routes: RouteEntry[]): void\n  /** Serve a static directory under a path prefix. */\n  serveStatic(prefix: string, dir: string): void\n  /** Register a connect-style middleware (optionally path-scoped). */\n  use(mw: ConnectMiddleware, opts?: UseConnectOptions): void\n}\n"],"mappings":"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"}
+{"version":3,"file":"runtime-CDz5ayBt.mjs","names":[],"sources":["../src/http/body-policy.ts","../src/http/middleware/request-scope.ts","../src/http/reply.ts","../src/http/runtime.ts"],"sourcesContent":["/**\n * How a request body is interpreted, decided in ONE place for every runtime.\n *\n * Before this, each engine brought its own library's opinion: Express parsed\n * only exact `application/json` and silently left everything else `undefined`,\n * Fastify answered 415 for anything it had no parser for, and h3 routed\n * unrecognised types through `destr` — so the same request produced a parsed\n * object, an empty body, or a 415 depending on which engine the app was\n * configured with. The runtime is meant to be swappable; that made it not\n * swappable for any app accepting a body outside `application/json` (#590).\n *\n * @module @forinda/kickjs/http/body-policy\n */\n\nimport { HttpException } from '../core/errors'\n\n/**\n * A header as the runtimes hand it over. Node's `IncomingHttpHeaders` and\n * Fastify's normalised map both allow `string[]`, so take the union here\n * rather than casting at every call site.\n */\nexport type HeaderValue = string | string[] | undefined\n\n/** What the framework does with a body of a given media type. */\nexport type BodyKind =\n  /** Parse as JSON, strictly. */\n  | 'json'\n  /** Parse as `application/x-www-form-urlencoded` into an object. */\n  | 'urlencoded'\n  /** Hand the handler the raw string. Never JSON — see `classifyMediaType`. */\n  | 'text'\n  /** Left to the upload path, which consumes the stream itself. */\n  | 'multipart'\n  /** Not parsed. `ctx.body` stays undefined. */\n  | 'unsupported'\n\n/**\n * Strip parameters and normalise: `Application/JSON; charset=utf-8` →\n * `application/json`. h3's own check is `===` against the bare type, which is\n * why `application/json; charset=utf-8` — what most clients actually send —\n * missed it and fell to a non-strict branch.\n */\nexport function normalizeMediaType(contentType: HeaderValue): string {\n  const value = Array.isArray(contentType) ? contentType[0] : contentType\n  return (value ?? '').split(';')[0].trim().toLowerCase()\n}\n\n/**\n * `application/*+json` is JSON, and this is not a judgement call: RFC 6838\n * §4.2.8 says a media type \"MUST NOT be given names incorporating suffixes for\n * structured syntaxes they do not actually employ\", and RFC 6839 §2 exists so\n * receivers can \"do generic processing of the underlying representation\".\n * Spring, ASP.NET Core and Hono's validator all match the suffix by default.\n *\n * So `application/merge-patch+json` (RFC 7396) and `application/problem+json`\n * (RFC 9457) parse as JSON — which the framework already emits for every\n * problem response, and previously could not read back.\n */\nfunction isJsonMediaType(mediaType: string): boolean {\n  return mediaType === 'application/json' || /^application\\/[\\w.+-]+\\+json$/.test(mediaType)\n}\n\n/**\n * Decide how to treat a body, from its declared media type alone.\n *\n * `text/*` deliberately yields the raw string and is NEVER JSON-parsed.\n * `text/plain` is one of three CORS-safelisted content types, so it crosses\n * origins without a preflight; JSON-parsing it would re-open the simple-request\n * CSRF that requiring `application/json` closes. h3's own source carries this\n * warning, and h3 v2 pulled back from `destr` partly because of it.\n */\nexport function classifyMediaType(contentType: HeaderValue): BodyKind {\n  const mediaType = normalizeMediaType(contentType)\n  if (!mediaType) return 'unsupported'\n  if (isJsonMediaType(mediaType)) return 'json'\n  if (mediaType === 'application/x-www-form-urlencoded') return 'urlencoded'\n  if (mediaType.startsWith('multipart/')) return 'multipart'\n  if (mediaType.startsWith('text/')) return 'text'\n  return 'unsupported'\n}\n\n/**\n * Media types Express should hand to its JSON body parser. `express.json()`\n * defaults to the exact string `application/json`, and `type-is` will not match\n * `application/json` against a bare wildcard-plus-json pattern (a length guard rejects\n * it), so BOTH entries are required — passing only the wildcard silently stops\n * parsing ordinary JSON.\n */\nexport const EXPRESS_JSON_TYPES = ['application/json', 'application/*+json'] as const\n\n/** Media types the framework claims to parse, for diagnostics and docs. */\nexport const SUPPORTED_BODY_TYPES = [\n  'application/json',\n  'application/*+json',\n  'application/x-www-form-urlencoded',\n  'text/*',\n  'multipart/form-data',\n] as const\n\n/**\n * The 415 for a body whose media type the framework does not parse.\n *\n * Only ever raised when a body was actually SENT. An absent or empty body is\n * treated as absent regardless of its declared type — the same call Spring's\n * `readWithMessageConverters` and ASP.NET's `BodyModelBinder` both make, and\n * the reason neither rejects a bodyless POST. A bare `POST` with no payload is\n * a legitimate request, not an unsupported one.\n *\n * Carries `Accept`, which RFC 9110 §15.5.16 says a 415 \"can\" use to indicate\n * which media types would have been accepted.\n */\nexport function unsupportedMediaTypeError(contentType: HeaderValue): HttpException {\n  const mediaType = normalizeMediaType(contentType)\n  return new HttpException(\n    415,\n    mediaType\n      ? `Unsupported Media Type: ${mediaType}`\n      : 'Unsupported Media Type: request has a body but no Content-Type',\n    undefined,\n    { Accept: SUPPORTED_BODY_TYPES.join(', ') },\n  )\n}\n\n/** Verbs whose body the framework reads. */\nconst BODY_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])\n\n/**\n * Did this request actually carry a body? Decided from the framing headers\n * rather than from whether a parser produced anything — the distinction that\n * separates \"nothing was sent\" from \"something was sent that we could not\n * read\", which is the whole basis for answering 415 on one and 200 on the other.\n */\nexport function hasRequestBody(headers: Record<string, unknown>): boolean {\n  const length = headers['content-length'] as string | undefined\n  const encoding = headers['transfer-encoding'] as string | undefined\n  return encoding !== undefined || (length !== undefined && length !== '0')\n}\n\n/**\n * Connect middleware that answers 415 for a body Express's parsers left\n * untouched.\n *\n * Express has no concept of an unsupported type: a parser whose `type` does not\n * match simply calls `next()` and leaves `req.body` undefined, indistinguishable\n * from a request that sent nothing. Mounted after the parsers, this restores the\n * distinction so Express agrees with the other runtimes.\n */\nexport function rejectUnsupportedBody() {\n  return (req: any, _res: unknown, next: (err?: unknown) => void): void => {\n    if (!BODY_METHODS.has((req.method ?? 'GET').toUpperCase())) return next()\n    if (classifyMediaType(req.headers?.['content-type']) !== 'unsupported') return next()\n\n    const reject = (): void => next(unsupportedMediaTypeError(req.headers?.['content-type']))\n    const length = req.headers?.['content-length'] as string | undefined\n    if (length !== undefined) return length === '0' ? next() : reject()\n    if (req.headers?.['transfer-encoding'] === undefined) return next()\n\n    // Chunked: the framing headers say a body MAY follow, but an empty chunked\n    // post sends none. Deciding on the headers alone would 415 a request that\n    // sent nothing, so wait to see whether a byte actually arrives — the same\n    // distinction the other runtimes make by inspecting the read body.\n    let decided = false\n    const settle = (fn: () => void) => (): void => {\n      if (decided) return\n      decided = true\n      req.off?.('data', onData)\n      req.off?.('end', onEnd)\n      fn()\n    }\n    const onData = settle(reject)\n    const onEnd = settle(() => next())\n    req.on?.('data', onData)\n    req.on?.('end', onEnd)\n  }\n}\n","// Web Crypto via globalThis.crypto (randomUUID) — portable across\n// node/bun/deno/workers; node:crypto deliberately NOT imported here so this\n// module stays on the edge-safe request path.\nimport type { Request, Response, NextFunction } from 'express'\nimport { requestStore, type RequestStore } from '../request-store'\nimport { METADATA } from '../../core/interfaces'\nimport { getClassMetaOrUndefined } from '../../core/metadata'\nimport { createLogger } from '../../core/logger'\n\nconst log = createLogger('RequestScope')\n\n// Per-class @PreDestroy method-name cache: the metadata is immutable after\n// class definition, so pay the Reflect read once per class, not once per\n// instance per request. `null` = \"checked, none declared\".\nconst preDestroyCache = new Map<Function, string | symbol | null>()\n\nfunction preDestroyMethod(ctor: Function): string | symbol | null {\n  let method = preDestroyCache.get(ctor)\n  if (method === undefined) {\n    method =\n      getClassMetaOrUndefined<string | symbol>(METADATA.PRE_DESTROY, (ctor as any).prototype) ??\n      null\n    preDestroyCache.set(ctor, method)\n  }\n  return method\n}\n\n/**\n * Run `@PreDestroy` hooks on every REQUEST-scoped instance the request\n * created, then drop them. Called when the response closes (finished or\n * aborted) — the counterpart to `@PostConstruct`, closing the lifecycle gap\n * where per-request services holding transactions/handles/subscriptions were\n * silently dropped with no cleanup callback.\n *\n * Idempotent (guarded by `store.disposed`); hook errors are logged and\n * swallowed so one failing teardown can't break request completion. Async\n * hooks are fired without being awaited — the response is already gone.\n */\nexport function disposeRequestStore(store: RequestStore): void {\n  if (store.disposed) return\n  store.disposed = true\n  if (store.instances.size === 0) return\n  for (const instance of store.instances.values()) {\n    if (instance === null || typeof instance !== 'object') continue\n    const method = preDestroyMethod(instance.constructor)\n    if (!method || typeof instance[method] !== 'function') continue\n    try {\n      const result = instance[method]()\n      if (result && typeof result.then === 'function') {\n        ;(result as Promise<void>).catch((err) =>\n          log.error(err, `@PreDestroy on ${instance.constructor.name} rejected`),\n        )\n      }\n    } catch (err) {\n      log.error(err, `@PreDestroy on ${instance.constructor.name} threw`)\n    }\n  }\n  store.instances.clear()\n}\n\n/**\n * Marker symbol stamped on the function returned by {@link requestScopeMiddleware}.\n *\n * `Application.setup()` uses {@link isRequestScopeMiddleware} to detect whether\n * the user-supplied middleware list already contains the request-scope wrapper,\n * and skips its automatic auto-mount when one is found. Lets adopters control\n * the exact position of the ALS frame in their pipeline (e.g., after a custom\n * tracing wrapper) without ending up with two nested frames.\n */\n// `Symbol.for(...)` returns a plain `symbol` (not `unique symbol`), but the\n// runtime detection marker doesn't need the unique nominal property — it only\n// needs the interned-slot reference equality that `Symbol.for` already provides.\nconst REQUEST_SCOPE_MIDDLEWARE_MARKER = Symbol.for('@kickjs/requestScopeMiddleware')\n\n/**\n * Build a fresh per-request store. Shared by {@link requestScopeMiddleware}\n * (Express) and by runtimes whose handler runs outside the connect-middleware\n * chain (e.g. Fastify), so both establish an identical ALS frame.\n */\nexport function createRequestStore(requestId?: string): RequestStore {\n  return {\n    requestId: requestId || crypto.randomUUID(),\n    instances: new Map(),\n    // Explicit generic locks the \"string keys only\" decision.\n    values: new Map<string, unknown>(),\n  }\n}\n\n/**\n * Wraps each request in an AsyncLocalStorage context.\n * Enables REQUEST-scoped DI and automatic requestId propagation to logs.\n *\n * Should be mounted early in the middleware pipeline (before route handlers).\n * `Application` mounts this automatically unless `contextStore: 'manual'` is set\n * or the user already includes one in their middleware list.\n */\nexport function requestScopeMiddleware() {\n  const mw = (req: Request, res: Response, next: NextFunction) => {\n    const requestIdHeader = req.headers['x-request-id']\n    const requestId =\n      (Array.isArray(requestIdHeader) ? requestIdHeader[0] : requestIdHeader) || crypto.randomUUID()\n    const store = createRequestStore(requestId)\n    // Surface the requestId on req so the standalone requestId() middleware\n    // (when also mounted) reuses this value instead of generating a divergent\n    // second one. Without this, log lines that read from the ALS store would\n    // disagree with the X-Request-Id response header for any request that\n    // didn't carry an inbound x-request-id header.\n    ;(req as Request & { requestId?: string }).requestId = requestId\n    // 'close' fires once the response finished OR the client aborted — run\n    // @PreDestroy teardown for the request's scoped instances either way.\n    res.once('close', () => disposeRequestStore(store))\n    // Pass `next` directly — `run` invokes it with no args, so the arrow\n    // wrapper previously allocated per request added nothing.\n    requestStore.run(store, next)\n  }\n  ;(mw as unknown as Record<symbol, unknown>)[REQUEST_SCOPE_MIDDLEWARE_MARKER] = true\n  return mw\n}\n\n/**\n * Returns `true` when `value` is the function produced by {@link requestScopeMiddleware}.\n *\n * Detection uses a `Symbol.for(...)` marker so the check survives different\n * copies of `@forinda/kickjs` loaded under different module identities (e.g.,\n * a published package alongside a workspace-linked one during local dev).\n */\nexport function isRequestScopeMiddleware(value: unknown): boolean {\n  if (typeof value !== 'function') return false\n  return (value as unknown as Record<symbol, unknown>)[REQUEST_SCOPE_MIDDLEWARE_MARKER] === true\n}\n","// Return-value handler support.\n//\n// Handlers may RETURN their response payload instead of calling `ctx.json`:\n// the runtime auto-sends it when the pipeline finishes with nothing written.\n// `reply(status, body)` wraps a payload with a non-200 status while staying\n// transparent to type inference (`Reply<201, Task>` carries both statically).\n//\n// Edge-safe: no node imports — shared by all four runtimes including the\n// `@forinda/kickjs/web` entry.\n\nimport type { RequestContext } from './context'\nimport type { RuntimeResponse } from './runtime'\n\n// `Symbol.for` so the brand survives duplicate module copies (workspace-linked\n// + published package in one process — same rationale as the request-scope\n// middleware marker).\nconst REPLY_BRAND = Symbol.for('kickjs.reply')\n\n/**\n * A status-carrying response payload for return-value handlers. Create via\n * {@link reply} — the brand is what runtimes detect, and the generics are\n * what the `kick/routes` response typegen unwraps (`Reply<S, T>` → `T`).\n */\nexport interface Reply<S extends number = number, T = unknown> {\n  readonly [REPLY_BRAND]: true\n  readonly status: S\n  readonly body: T\n}\n\n/**\n * Wrap a return-value handler's payload with an explicit status code:\n *\n * ```ts\n * @Post('/')\n * async create(ctx: RequestContext) {\n *   return reply(201, await this.tasks.create(ctx.body))\n * }\n * ```\n */\nexport function reply<S extends number, T>(status: S, body: T): Reply<S, T> {\n  return { [REPLY_BRAND]: true, status, body }\n}\n\n/** `reply(200, body)` — explicit form of a bare `return body`. */\nreply.ok = <T>(body: T): Reply<200, T> => reply(200, body)\n/** `reply(201, body)` */\nreply.created = <T>(body: T): Reply<201, T> => reply(201, body)\n/** `reply(202, body)` */\nreply.accepted = <T>(body: T): Reply<202, T> => reply(202, body)\n/** Empty 204 — maps to `ctx.noContent()`. */\nreply.noContent = (): Reply<204, undefined> => reply(204, undefined)\n\n/**\n * The statically-inferred response type of a controller handler — what\n * `kick typegen` emits into `KickRoutes[...].response`:\n *\n * - `Awaited<ReturnType>` of the method\n * - `Reply<S, T>` unwraps to `T`\n * - `void`/`undefined` members are dropped (imperative `ctx.json` branches);\n *   a handler that never returns a value stays `unknown`, matching the\n *   pre-inference emission\n *\n * ```ts\n * type R = InferHandlerResponse<UsersController['get']> // → User\n * ```\n */\nexport type InferHandlerResponse<H> = H extends (...args: never[]) => infer R\n  ? [Exclude<Awaited<R>, void | undefined>] extends [never]\n    ? unknown\n    : UnwrapReply<Exclude<Awaited<R>, void | undefined>>\n  : unknown\n\ntype UnwrapReply<A> =\n  A extends Reply<number, infer B>\n    ? B\n    : A extends RuntimeResponse\n      ? // The engine's own response object says nothing about the body, so a\n        // handler ending `return ctx.json(...)` degrades to `unknown` — which is\n        // what the typegen comment always claimed happened. It did not: the bare\n        // `RuntimeResponse` leaked into `KickRoutes[...].response`, offering\n        // `.status()` / `.setHeader()` to a client expecting a payload.\n        // Confidently wrong is worse than unknown.\n        //\n        // To carry a payload, return it (`return user`) or wrap it\n        // (`return reply(201, user)`) — that is what `reply` is for.\n        unknown\n      : A\n\nexport function isReply(value: unknown): value is Reply {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as Record<symbol, unknown>)[REPLY_BRAND] === true\n  )\n}\n\n/**\n * Send a handler's RETURN value when the pipeline finished without anything\n * having written a response. Callers guard on \"driver/response unsettled\" —\n * this only decides how to send:\n *\n * - `undefined` → not handled (returns false; runtime keeps today's behavior)\n * - `Reply` wrapper → status + body (204 → `ctx.noContent()`)\n * - anything else → `ctx.json(value)` (200)\n *\n * Returns true when a response was produced.\n */\nexport function applyHandlerResult(ctx: RequestContext, result: unknown): boolean {\n  if (result === undefined) return false\n  if (isReply(result)) {\n    // Only 204 maps to noContent — an undefined body must NOT coerce the\n    // declared status (reply(304, undefined) keeps its 304; the json body\n    // is simply empty).\n    if (result.status === 204) {\n      ctx.noContent()\n      return true\n    }\n    ctx.json(result.body, result.status)\n    return true\n  }\n  ctx.json(result)\n  return true\n}\n","// The HttpRuntime seam.\n//\n// Decorators no longer emit an `express.Router` directly. `buildRouteTable()`\n// turns controller metadata into a plain-data `RouteEntry[]`; an `HttpRuntime`\n// materializes that table onto whatever engine it owns. Express is the default\n// runtime and the only one shipped in M1 — its materializer reproduces the exact\n// handler chain the old `buildRoutes()` built, so behavior is unchanged.\n//\n// Fastify / h3 runtimes (later milestones) consume the SAME `RouteEntry` data\n// and the SAME `HttpRuntime` contract; the request/response driver abstraction\n// that lets `RequestContext` run engine-agnostically lands with them (M3), since\n// under Express the drivers ARE the Express request/response objects already.\n//\n// Why a seam: running Fastify / h3 behind an Express-compat layer\n// (`@fastify/express`, h3's node bridge) bypasses their router and\n// serialization, and rebuilding `ctx` over web-standard Request/Response\n// would break SSE / streaming, multer uploads and `ctx.res` for every adopter.\n// The seam keeps `ctx` and swaps only the engine underneath it.\n\nimport { ROUTE_SLOT, type RouteFlags } from '../core/route-flag'\nimport type { IncomingMessage, ServerResponse } from 'node:http'\nimport type {\n  RequestHandler,\n  ErrorRequestHandler,\n  Express,\n  Request as ExpressRequest,\n  Response as ExpressResponse,\n} from 'express'\n\nimport type { Constructor, FileUploadConfig, MiddlewareHandler, RouteDefinition } from '../core'\nimport type { RequestContext } from './context'\n\n/** HTTP verbs the router emits. Mirrors the decorator surface (@Get/@Post/...). */\nexport type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'\n\n/**\n * A context-based handler: the runtime-neutral unit of the request pipeline.\n * Contributors, route middleware (via {@link MiddlewareHandler}), and the\n * terminal controller call all reduce to this shape. The runtime owns how a\n * `CtxHandler` is wrapped onto its engine (Express wraps it in `(req, res,\n * next)`; Fastify in its own handler).\n */\nexport type CtxHandler = (ctx: RequestContext) => unknown | Promise<unknown>\n\n/**\n * Connect-style middleware — the portable middleware format. Built-in\n * middleware and adopter-supplied Express middleware are this shape. The\n * Express runtime hands them straight to `app.use`; later runtimes bridge\n * them (Fastify via `@fastify/middie`, h3 via its node adapter).\n *\n * Typed as the Express handler union for M1 (Express is the only runtime);\n * a future milestone narrows this to bare node `(req, res, next)` primitives\n * once the driver layer lands.\n */\nexport type ConnectMiddleware = RequestHandler | ErrorRequestHandler\n\n/**\n * One materialized route, as plain data. Produced by {@link buildRouteTable}\n * from decorator metadata; consumed by {@link HttpRuntime.mountRoutes}.\n *\n * The shape is deliberately richer than a flat `CtxHandler[]`: `middlewares`\n * keep the `(ctx, next)` signature (they may short-circuit or call `next(err)`),\n * `contributorRunner` is a closure over the pre-built pipeline + container (the\n * pipeline is built — and any cycle / missing-dep error thrown — at table-build\n * time, i.e. boot), and `validation` / `upload` stay as metadata the runtime\n * materializes its own way. Faithfully reproducing the legacy Express chain —\n * not collapsing it — is what keeps M1 behavior-neutral.\n */\nexport interface RouteEntry {\n  method: RouteMethod\n  /** Path with `:param` segments — the portable subset all engines accept. */\n  path: string\n  /** Class + method middleware, in execution order; each receives `(ctx, next)`. */\n  middlewares: MiddlewareHandler[]\n  /**\n   * Runs the contributor pipeline against `ctx` (populates `ctx.set(...)`),\n   * or `null` when no contributors apply. Closes over the built pipeline and\n   * the DI container so it stays engine-neutral; the runtime advances the\n   * chain (Express: call `next()`) once it resolves.\n   */\n  contributorRunner: CtxHandler | null\n  /**\n   * Contributors registered with `beforeValidation: true`. Runtimes run this\n   * right after publishing the matched route — before validation, upload and\n   * middleware — so a rejection (401) lands before a malformed body's 422.\n   * Absent or `null` when no contributor asks for it.\n   */\n  earlyContributorRunner?: CtxHandler | null\n  /** Terminal handler: resolves the controller per-request and invokes it. */\n  handler: CtxHandler\n  /** Introspection + runtime-materialized concerns (swagger/typegen read this). */\n  meta: RouteMeta\n}\n\n/** Per-route metadata: introspection refs plus runtime-materialized concerns. */\nexport interface RouteMeta {\n  /**\n   * Owning controller class — for DI resolution and adapter introspection.\n   * Absent for ad-hoc routes registered through {@link AdapterHttp.route},\n   * which have no controller class behind them.\n   */\n  controller?: Constructor\n  /** Handler method name on the controller, when there is one. */\n  handlerName?: string\n  /** Zod/JSON-schema validation config from the route decorator, if any. */\n  validation?: RouteDefinition['validation']\n  /** `@FileUpload` config, if present — the runtime supplies the backend. */\n  upload?: FileUploadConfig\n  /**\n   * Route flags in force here, resolved at build time (method over class).\n   * Enabled flags only: a flag declared `false` at a higher-precedence site is\n   * absent rather than present-and-false, so `has()` is always the right\n   * question. See `core/route-flag.ts`.\n   */\n  flags?: RouteFlags\n  /**\n   * The full mounted pattern (`/api/v1/users/:id`) — set by the Application\n   * for controller routes. `path` is relative to the module mount.\n   */\n  pattern?: string\n}\n\n/**\n * The route a request matched, published on `ctx.route`.\n *\n * Everything that holds a {@link RequestContext} — handlers, `@Middleware()`,\n * guards, contributors — can read it, which is what lets one declaration on a\n * route serve every consumer.\n */\n/**\n * Publish the matched route on the request, for `ctx.route` to read.\n *\n * Called by each runtime once per dispatch, before it builds a RequestContext.\n * It lives on `req` rather than on the ctx because the Express runtime\n * constructs a fresh RequestContext per middleware step — anything written to\n * one ctx would be invisible to the next and to the handler.\n */\nexport function publishMatchedRoute(req: unknown, entry: RouteEntry): void {\n  ;(req as Record<symbol, MatchedRoute>)[ROUTE_SLOT] = {\n    method: entry.method,\n    path: entry.path,\n    controller: entry.meta.controller,\n    handlerName: entry.meta.handlerName,\n    flags: entry.meta.flags ?? EMPTY_FLAGS,\n    pattern: entry.meta.pattern ?? entry.path,\n  }\n}\n\nconst EMPTY_FLAGS: RouteFlags = new Map() as RouteFlags\n\nexport interface MatchedRoute {\n  method: RouteMethod\n  /** Path as declared on the handler, e.g. `/:id`. */\n  path: string\n  /**\n   * The full route pattern including the mount prefix and version, e.g.\n   * `/api/v1/users/:id` — what metrics and spans should be keyed by. Falls\n   * back to `path` for routes registered without a mount.\n   */\n  pattern: string\n  controller?: Constructor\n  handlerName?: string\n  /** Enabled flags only — see {@link RouteMeta.flags}. */\n  flags: RouteFlags\n}\n\n/** A controller's routes grouped under the module mount prefix. */\nexport type RouteTable = { mountPath: string; routes: RouteEntry[] }[]\n\n/**\n * The response surface {@link RequestContext}'s helpers (`json` / `html` /\n * `sse` / `download` / `render` / `problem`) drive, instead of calling Express\n * `res` methods directly (spec §4.3). Sized so `express.Response` satisfies it\n * structurally — under the Express runtime the driver IS the Express response,\n * so there is no wrapping and no behavior change. Other runtimes (Fastify / h3)\n * provide a thin object implementing this over their native reply.\n *\n * The terminal methods return `RuntimeResponse` for fluent chaining (Express's\n * `Response` is assignable, since it is a superset).\n */\nexport interface RuntimeResponse {\n  status(code: number): RuntimeResponse\n  json(data: unknown): RuntimeResponse\n  send(data: unknown): RuntimeResponse\n  type(contentType: string): RuntimeResponse\n  setHeader(name: string, value: string | number | readonly string[]): unknown\n  render(view: string, data?: Record<string, unknown>): unknown\n  writeHead(statusCode: number, headers?: Record<string, string>): unknown\n  flushHeaders(): unknown\n  write(chunk: string | Buffer): boolean\n  end(data?: unknown): unknown\n  once(event: 'close' | 'drain', listener: () => void): unknown\n  readonly headersSent: boolean\n}\n\n// ── Runtime-typed escape hatches (spec §4.3b) ─────────────────────────────\n\n/**\n * Per-runtime type map: the engine-native request / response / app types an\n * `HttpRuntime` exposes through `ctx.req.raw` / `ctx.res.raw` / `AdapterContext.app`.\n */\nexport interface RuntimeTypeMap {\n  request: unknown\n  response: unknown\n  app: unknown\n}\n\n/** The Express runtime's native types — the default when nothing is augmented. */\nexport interface ExpressRuntimeTypes {\n  request: ExpressRequest\n  response: ExpressResponse\n  app: Express\n}\n\n/**\n * Augmentable runtime registry. Empty by default; the `kick/runtime` typegen\n * plugin emits a `{ runtime: <RuntimeTypeMap> }` augmentation from the configured\n * runtime, which flips the engine-native escape-hatch types — `AdapterContext.app`,\n * `getRuntimeApp()`, and (once the driver layer lands) `ctx.req.raw` / `ctx.res.raw`\n * — to that runtime. Mirrors `KickDbRegister` / `KickEnv`, so the type story is\n * uniform with `kick/db` and env typing.\n *\n * @example\n * ```ts\n * // .kickjs/types/kick__runtime.d.ts — generated by typegen\n * declare module '@forinda/kickjs' {\n *   interface KickRuntimeRegister {\n *     runtime: import('@forinda/kickjs/fastify').FastifyRuntimeTypes\n *   }\n * }\n * ```\n */\n\nexport interface KickRuntimeRegister {}\n\n/** The active runtime's type map — the augmented one, or Express by default. */\nexport type ActiveRuntime = KickRuntimeRegister extends { runtime: infer R extends RuntimeTypeMap }\n  ? R\n  : ExpressRuntimeTypes\n\n/** Options passed to {@link HttpRuntime.createApp}. */\nexport interface RuntimeAppOptions {\n  /**\n   * Express `trust proxy` setting (and the equivalent on other engines). The\n   * function form is Express-specific; other runtimes interpret the simpler\n   * shapes (or normalize X-Forwarded-For themselves — see spec §10 Q1).\n   */\n  trustProxy?: boolean | string | number | string[] | ((ip: string, hopIndex: number) => boolean)\n}\n\n/** Where a connect middleware sits and what it scopes to. */\nexport interface UseConnectOptions {\n  path?: string | RegExp | ReadonlyArray<string | RegExp>\n}\n\n/**\n * Optional engine capabilities. Absence means the corresponding `ctx` feature\n * raises a clear error on that runtime rather than failing obscurely.\n */\nexport interface RuntimeCapabilities {\n  /** View-engine rendering (`ctx.render`). Express: true; Fastify/h3: false initially. */\n  render: boolean\n  /** File uploads (`ctx.file` / `@FileUpload`). All engines, different backends. */\n  uploads: boolean\n  /** Connect-style middleware. Express/Fastify(middie): true; h3: best-effort. */\n  connectMiddleware: boolean\n  /**\n   * The engine parses request bodies itself (Fastify, h3). When true, the\n   * Application skips its default `express.json()` so the body stream isn't\n   * consumed twice (which would deadlock the engine's own parser). Express:\n   * false — it relies on the `express.json()` connect middleware.\n   */\n  nativeBodyParsing: boolean\n  /**\n   * The engine's `nodeHandler` works behind `node:http2` (the HTTP/2\n   * compatibility API), so `server: { http2: true }` may use it. Fastify/h3:\n   * true. Express: false — it does not run on that layer. Absent = false, so\n   * custom runtimes opt in explicitly.\n   */\n  http2?: boolean\n}\n\n/**\n * The engine driver. KickJS owns decorators → {@link RouteTable}, the\n * contributor pipeline, the `RequestContext` surface, and error mapping. The\n * runtime owns app/server creation, route materialization, connect-middleware\n * registration, static serving, and the terminal not-found / error handlers.\n *\n * `expressRuntime()` is the default and the M1 reference implementation.\n */\nexport interface HttpRuntime<TApp = unknown> {\n  readonly name: 'express' | 'fastify' | 'h3' | (string & {})\n\n  /** Create the engine app. Called once per Application (and per HMR rebuild). */\n  createApp(options?: RuntimeAppOptions): TApp\n\n  /**\n   * Node-compatible request listener — the transport contract.\n   * `http.createServer(handler)` in prod, Vite post-middleware in dev. MUST\n   * invoke `next` (when given) instead of 404-ing if no route matched — the\n   * Vite dev chain depends on fall-through.\n   */\n  nodeHandler(\n    app: TApp,\n  ): (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void\n\n  /** Materialize the framework-built route table onto the engine. */\n  mountRoutes(app: TApp, table: RouteTable): void\n\n  /** Register a connect-style middleware (built-ins + adopter middleware). */\n  useConnect(app: TApp, mw: ConnectMiddleware, opts?: UseConnectOptions): void\n\n  /** Serve a static directory (swagger-ui assets, devtools SPA). */\n  serveStatic(app: TApp, prefix: string, dir: string): void\n\n  /** Terminal not-found handler. */\n  setNotFound(app: TApp, mw: ConnectMiddleware): void\n\n  /** Terminal error handler. */\n  setErrorHandler(app: TApp, mw: ConnectMiddleware): void\n\n  readonly capabilities: RuntimeCapabilities\n}\n\n/**\n * The supported surface adapters use to add HTTP routes, mounts, static dirs,\n * and middleware — engine-agnostic, in place of reaching for the raw Express\n * `app` (spec §4.4). Exposed as {@link AdapterContext.http}. Built by the\n * Application over the active {@link HttpRuntime}, so an adapter written against\n * this works under any runtime; the raw `app` escape hatch stays available for\n * the rare engine-specific need.\n */\nexport interface AdapterHttp {\n  /** Register a single context-handler route (e.g. a docs or transport endpoint). */\n  route(method: RouteMethod, path: string, handler: CtxHandler): void\n  /** Mount a pre-built route table under a path prefix. */\n  mount(prefix: string, routes: RouteEntry[]): void\n  /** Serve a static directory under a path prefix. */\n  serveStatic(prefix: string, dir: string): void\n  /** Register a connect-style middleware (optionally path-scoped). */\n  use(mw: ConnectMiddleware, opts?: UseConnectOptions): void\n}\n"],"mappings":"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"}

package/dist/{upload-config-BhaBjCiB.mjs → upload-config-d0pisVsK.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v9.0.2
+ * @forinda/kickjs v9.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -9,4 +9,4 @@
  * @license MIT
  */
 import{HttpException,HttpStatus}from"./core/errors.mjs";const MIME_MAP={jpg:`image/jpeg`,jpeg:`image/jpeg`,png:`image/png`,gif:`image/gif`,webp:`image/webp`,svg:`image/svg+xml`,bmp:`image/bmp`,ico:`image/x-icon`,tiff:`image/tiff`,tif:`image/tiff`,avif:`image/avif`,pdf:`application/pdf`,doc:`application/msword`,docx:`application/vnd.openxmlformats-officedocument.wordprocessingml.document`,xls:`application/vnd.ms-excel`,xlsx:`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`,ppt:`application/vnd.ms-powerpoint`,pptx:`application/vnd.openxmlformats-officedocument.presentationml.presentation`,odt:`application/vnd.oasis.opendocument.text`,ods:`application/vnd.oasis.opendocument.spreadsheet`,odp:`application/vnd.oasis.opendocument.presentation`,rtf:`application/rtf`,txt:`text/plain`,csv:`text/csv`,zip:`application/zip`,gz:`application/gzip`,tar:`application/x-tar`,rar:`application/vnd.rar`,"7z":`application/x-7z-compressed`,mp3:`audio/mpeg`,wav:`audio/wav`,ogg:`audio/ogg`,flac:`audio/flac`,aac:`audio/aac`,mp4:`video/mp4`,webm:`video/webm`,avi:`video/x-msvideo`,mov:`video/quicktime`,mkv:`video/x-matroska`,json:`application/json`,xml:`application/xml`,html:`text/html`};function resolveMimeTypes(types){return types.map(t=>{let lower=t.toLowerCase().replace(/^\./,``);return MIME_MAP[lower]??t})}function buildFileTypeFilter(allowedTypes,customMimeMap){if(!allowedTypes)return()=>!0;if(typeof allowedTypes==`function`)return allowedTypes;let mimeMap=customMimeMap?{...MIME_MAP,...customMimeMap}:MIME_MAP,resolved=allowedTypes.map(t=>mimeMap[t.toLowerCase().replace(/^\./,``)]??t);return mimetype=>resolved.some(type=>type.endsWith(`/*`)?mimetype.startsWith(type.replace(`/*`,`/`)):mimetype===type)}function applyUploadConfig(parts,config){if(config.mode===`none`)return{};let field=config.fieldName??`file`,maxSize=config.maxSize??5242880,typeAllowed=buildFileTypeFilter(config.allowedTypes,config.customMimeMap),files=parts.filter(p=>p.fieldname===field).map(p=>{if(!typeAllowed(p.mimetype,p.filename))throw new HttpException(HttpStatus.UNSUPPORTED_MEDIA_TYPE,`File type ${p.mimetype} is not allowed`);if(p.buffer.length>maxSize)throw new HttpException(HttpStatus.PAYLOAD_TOO_LARGE,`File ${p.filename} exceeds the ${maxSize}-byte limit`);return{fieldname:p.fieldname,originalname:p.filename,encoding:`7bit`,mimetype:p.mimetype,size:p.buffer.length,buffer:p.buffer}});if(config.mode===`single`)return{file:files[0]};let maxCount=config.maxCount??10;return{files:files.slice(0,maxCount)}}export{buildFileTypeFilter as n,resolveMimeTypes as r,applyUploadConfig as t};
-//# sourceMappingURL=upload-config-BhaBjCiB.mjs.map
+//# sourceMappingURL=upload-config-d0pisVsK.mjs.map