@znight/http 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/http",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Znight HTTP plugin: controllers, routing, guards, interceptors, validation with Fastify, Express or Hono",
   "license": "MIT",
   "author": "Ugho STEPHAN",
@@ -79,7 +79,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@znight/core": "0.1.3"
+    "@znight/core": "0.2.0"
   },
   "peerDependencies": {
     "@hono/node-server": "^2.1.5",
@@ -87,7 +87,7 @@
     "fastify": "^5.12.7",
     "hono": "^4.13.14",
     "light-my-request": "^6.8.0",
-    "@znight/compiler": "^0.1.3"
+    "@znight/compiler": "^0.2.0"
   },
   "peerDependenciesMeta": {
     "@hono/node-server": {
@@ -118,7 +118,7 @@
     "valibot": "1.5.0",
     "zod": "4.6.7",
     "light-my-request": "6.8.0",
-    "@znight/compiler": "0.1.3"
+    "@znight/compiler": "0.2.0"
   },
   "znight": {
     "apiVersion": 1,

package/src/compiler/analyze.ts

@@ -31,7 +31,7 @@ import { joinPaths, normalizePath } from '../path.ts'
 import { parseByteSize } from '../size.ts'
 import { acceptsUndefined, isRaw, parameterType, planCoercion } from './coercion.ts'
 import { Codes, HTTP_PACKAGE, Ids, PARAM_SOURCES, ROUTE_METHODS } from './model.ts'
-import { isRouteMetaDecorator, isValueRef, routeMeta } from './route-decorators.ts'
+import { isRouteMetaDecorator, isValueRef, readRouteMeta } from './route-decorators.ts'
 
 /** Name of the extension (owner of the decorators in `DecoratorInfo.owner`). */
 export const EXTENSION_NAME = 'http'
@@ -96,7 +96,7 @@ export function analyzeHttpClass(cls: ClassInfo, ctx: Context): void {
   const basePath = normalizePath(options.path)
   const guards = classRefs(ctx, cls, cls.decorators, Ids.UseGuard, 'guard')
   const interceptors = classRefs(ctx, cls, cls.decorators, Ids.UseInterceptor, 'interceptor')
-  const meta = routeMeta(ctx, cls, cls.decorators, cls.displayName)
+  const meta = readRouteMeta(ctx, cls)
   const bodyLimit = bodyLimitOf(ctx, cls.decorators)
   const routes: HttpRouteData[] = []
   for (const method of cls.methods) {
@@ -328,7 +328,7 @@ function analyzeMethod(
   let headers = responseHeaders(ctx, decorators)
   const guards = classRefs(ctx, cls, decorators, Ids.UseGuard, 'guard')
   const interceptors = classRefs(ctx, cls, decorators, Ids.UseInterceptor, 'interceptor')
-  const meta = routeMeta(ctx, cls, decorators, where)
+  const meta = readRouteMeta(ctx, cls, method)
   const bodySchema =
     bodyValidation !== undefined && !params.some(param => param.source === 'body') ? bodyValidation.schema : undefined
   let rawResponse = params.some(param => param.source === 'response')

package/src/compiler/index.ts

@@ -10,6 +10,9 @@
  * - `generate`: `metadata.extensions.http` with one `invoke` function per route (README,
  *   "Compiler contract").
  *
+ * It also exports the route decorator readers of other extensions: `readRouteMeta`,
+ * `effectiveRouteMeta` and `requiredRouteGroups`.
+ *
  * This entry only `import type`s from `@znight/compiler` and never loads the HTTP runtime.
  */
 import type { CompilerExtension, DecoratorSpec } from '@znight/compiler'
@@ -31,6 +34,16 @@ export type {
   SseRouteData,
   UploadData,
 } from './model.ts'
+export type { RequiredRouteGroup, RouteGroupMember } from './route-groups.ts'
+
+/**
+ * Route decorators for other extensions (RFC 0003 §6.4, RFC 0005 H3): read `createRouteDecorator`
+ * metadata on any class or method, and the required groups of the application, with the exact
+ * rules of controllers and routes. Stable API, see the README ("Route metadata in other
+ * extensions").
+ */
+export { effectiveRouteMeta, readRouteMeta } from './route-decorators.ts'
+export { requiredRouteGroups } from './route-groups.ts'
 
 const ROUTE: DecoratorSpec = { targets: ['method'], params: ['static'] }
 const NAME_OR_SCHEMA: DecoratorSpec = { targets: ['parameter'], params: ['value', 'value'] }

package/src/compiler/route-decorators.ts

@@ -6,6 +6,10 @@
  * (the options) are statically evaluable. Its argument is evaluated like a `value` decorator
  * argument (literals, `const` references, references to exported bindings); without argument the
  * value is `true`. Decorators of one group are alternatives: one per controller or route.
+ *
+ * Every helper takes the analysis context of **any** extension: other extensions read route
+ * decorators on their own targets (gateways, resolvers) with {@link readRouteMeta}, exported by
+ * `@znight/http/compiler`.
  */
 import type {
   AnalyzeContext,
@@ -13,15 +17,16 @@ import type {
   DecoratorInfo,
   Diagnostic,
   Location,
+  MethodInfo,
   StaticValue,
   ValueRef,
 } from '@znight/compiler'
-import type { HttpControllerData, MetaEntry } from './model.ts'
+import type { MetaEntry } from './model.ts'
 
 import { type AstNode, child, children, isNode, unwrap } from './ast.ts'
 import { Codes, GROUP_NAME, Ids } from './model.ts'
 
-type Context = AnalyzeContext<HttpControllerData>
+type Context = AnalyzeContext<unknown>
 type Project = Context['project']
 type ScopeInput = Parameters<Project['evaluate']>[0]
 type ExpressionInput = Parameters<Project['evaluate']>[1]
@@ -295,6 +300,44 @@ export function routeMeta(
   return entries
 }
 
+/**
+ * The route metadata entries of a class (`method` omitted) or of one of its methods: the route
+ * decorators (`createRouteDecorator` consts) applied to that target, in source order, read exactly
+ * as the http extension reads controllers and routes (keys, statically evaluated values, groups,
+ * `required`). Problems are reported as ZNIGHT005 through `ctx`, once per call: read each target
+ * once. Decorators that are not route decorators are ignored.
+ *
+ * Works with the analysis context of any extension. The entries of a target are its own: combine a
+ * class and a method with {@link effectiveRouteMeta}.
+ *
+ * ```ts
+ * analyzeClass(cls, ctx) {
+ *   const classMeta = readRouteMeta(ctx, cls)
+ *   for (const method of cls.methods) {
+ *     const meta = effectiveRouteMeta(classMeta, readRouteMeta(ctx, cls, method))
+ *   }
+ * }
+ * ```
+ */
+export function readRouteMeta(ctx: AnalyzeContext<unknown>, cls: ClassInfo, method?: MethodInfo): MetaEntry[] {
+  return method === undefined
+    ? routeMeta(ctx, cls, cls.decorators, cls.displayName)
+    : routeMeta(ctx, cls, method.decorators, `${cls.displayName}.${method.name}`)
+}
+
+/**
+ * The effective metadata of a method from the entries of its class and its own (RFC 0001 §5.1):
+ * the class entries, except those of a group the method decides itself, then the method entries.
+ * The same rule as `ctx.route.meta` at runtime.
+ */
+export function effectiveRouteMeta(classMeta: readonly MetaEntry[], methodMeta: readonly MetaEntry[]): MetaEntry[] {
+  if (methodMeta.length === 0) {
+    return [...classMeta]
+  }
+  const decided = new Set(methodMeta.map(entry => entry.group))
+  return [...classMeta.filter(entry => !decided.has(entry.group)), ...methodMeta]
+}
+
 /** `true` when the decorator is a route metadata decorator. */
 export function isRouteMetaDecorator(ctx: Context, decorator: DecoratorInfo): boolean {
   return (

package/src/compiler/route-groups.ts

@@ -0,0 +1,216 @@
+/**
+ * Route decorator groups of the application (RFC 0001 §5.1): every `createRouteDecorator`
+ * definition, applied or not, the consistency of their options and the **required** groups.
+ *
+ * The http extension reports the inconsistencies (ZNIGHT005) and checks every route against the
+ * required groups (ZNIGHT023). Other extensions whose targets carry route decorators (WebSocket
+ * gateways, GraphQL root fields) call {@link requiredRouteGroups} to check their own targets with
+ * exactly the same groups, without reporting the inconsistencies a second time.
+ */
+import type { Diagnostic, Location, ValidateContext } from '@znight/compiler'
+import type { MetaEntry } from './model.ts'
+
+import { compareStrings } from '../path.ts'
+import { Codes, Ids } from './model.ts'
+import { parseRouteDecoratorOptions } from './route-decorators.ts'
+
+/** A route decorator definition of the application (`export const Roles = createRouteDecorator(...)`). */
+export interface RouteGroupMember {
+  /** Canonical identity of the decorator `const` (`src/auth/access.ts#Roles`). */
+  readonly identity: string
+  /** Name of the `const` (`Roles`). */
+  readonly name: string
+  readonly key: string
+  /** Decision group (`options.group ?? key`). */
+  readonly group: string
+  readonly required: boolean
+  /** Location of the definition. */
+  readonly definition: Location
+  /**
+   * A flag (`@Public()`): created without type argument, and applied without argument wherever it
+   * was seen. Decides how the decorator is suggested: `@Public()` or `@Roles(...)`.
+   */
+  readonly flag: boolean
+}
+
+/** A required route decorator group: every route-like target must carry a decision of it. */
+export interface RequiredRouteGroup {
+  /** Group name (`access`). */
+  readonly group: string
+  /** The decorators of the group, in source order (file, then position). Never empty. */
+  readonly decorators: readonly RouteGroupMember[]
+  /** The decorators as a hint: `@Public(), @Authenticated() or @Roles(...)`. */
+  readonly suggestion: string
+}
+
+/** Result of {@link analyzeRouteGroups}. */
+export interface RouteGroupsAnalysis {
+  /** Inconsistent definitions (ZNIGHT005), at the second definition; not reported. */
+  readonly conflicts: readonly Diagnostic[]
+  /** The required groups, in the order of their first definition by identity. */
+  readonly required: readonly RequiredRouteGroup[]
+}
+
+/** A definition while flags are computed. */
+type MutableMember = { -readonly [K in keyof RouteGroupMember]: RouteGroupMember[K] }
+
+/**
+ * Every route decorator definition, sorted by identity: the applied ones (`applied`, first usage
+ * wins) and, when the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are
+ * left to the usages, which report them).
+ */
+function routeDecoratorDefinitions(
+  ctx: Pick<ValidateContext<unknown>, 'definitionsOf'>,
+  applied: Iterable<MetaEntry>,
+): MutableMember[] {
+  const definitions = new Map<string, MutableMember>()
+  for (const entry of applied) {
+    const known = definitions.get(entry.identity)
+    if (known === undefined) {
+      definitions.set(entry.identity, {
+        identity: entry.identity,
+        name: entry.decorator,
+        key: entry.key,
+        group: entry.group,
+        required: entry.required,
+        definition: entry.definition,
+        flag: entry.value === true,
+      })
+    } else if (entry.value !== true) {
+      known.flag = false
+    }
+  }
+  // compilers before RFC 0001 have no definitionsOf: only applied decorators are known then
+  const all = typeof ctx.definitionsOf === 'function' ? ctx.definitionsOf(Ids.createRouteDecorator) : []
+  for (const found of all) {
+    const [keyArg, optionsArg, ...extra] = found.args
+    const key = keyArg?.evaluated === true ? keyArg.value : undefined
+    if (
+      typeof key !== 'string' ||
+      key === '' ||
+      extra.length > 0 ||
+      (optionsArg !== undefined && !optionsArg.evaluated)
+    ) {
+      continue
+    }
+    const parsed = parseRouteDecoratorOptions(key, optionsArg?.value)
+    if ('error' in parsed) {
+      continue
+    }
+    const flag = found.typeArgs.length === 0
+    const known = definitions.get(found.identity)
+    if (known !== undefined) {
+      known.flag &&= flag
+      continue
+    }
+    definitions.set(found.identity, {
+      identity: found.identity,
+      name: found.name,
+      key,
+      ...parsed,
+      definition: found.location,
+      flag,
+    })
+  }
+  return [...definitions.values()].sort((a, b) => compareStrings(a.identity, b.identity))
+}
+
+/**
+ * The route decorator groups of the application (RFC 0001 §5.1): every definition of a key must use
+ * the same options and the decorators of a group must agree on `required` (a conflict is returned
+ * at the second definition, which is then ignored); the required groups with their decorators.
+ * `applied` are the entries of the targets the caller analysed (their first usage of a decorator
+ * wins over its `definitionsOf` entry).
+ */
+export function analyzeRouteGroups(
+  ctx: Pick<ValidateContext<unknown>, 'definitionsOf'>,
+  applied: Iterable<MetaEntry>,
+): RouteGroupsAnalysis {
+  const definitions = routeDecoratorDefinitions(ctx, applied)
+  if (definitions.length === 0) {
+    return { conflicts: [], required: [] }
+  }
+  const conflicts: Diagnostic[] = []
+  const byKey = new Map<string, RouteGroupMember>()
+  const byGroup = new Map<string, RouteGroupMember>()
+  const members = new Map<string, RouteGroupMember[]>()
+  for (const definition of definitions) {
+    const sameKey = byKey.get(definition.key)
+    if (sameKey !== undefined && (sameKey.group !== definition.group || sameKey.required !== definition.required)) {
+      conflicts.push({
+        code: Codes.InvalidDecorator,
+        severity: 'error',
+        message: `The route decorator ${definition.name} defines the key "${definition.key}" with ${describeOptions(definition)}, but ${sameKey.name} defines it with ${describeOptions(sameKey)}`,
+        location: definition.definition,
+        hints: ['Every definition of a key must use the same options: share one definition'],
+        related: [{ message: `${sameKey.name} is defined here`, location: sameKey.definition }],
+      })
+      continue
+    }
+    const sameGroup = byGroup.get(definition.group)
+    if (sameGroup !== undefined && sameGroup.required !== definition.required) {
+      conflicts.push({
+        code: Codes.InvalidDecorator,
+        severity: 'error',
+        message: `The "${definition.group}" group is ${definition.required ? '' : 'not '}required for ${definition.name} but ${sameGroup.required ? '' : 'not '}required for ${sameGroup.name}`,
+        location: definition.definition,
+        hints: [`All the decorators of the "${definition.group}" group must agree on required`],
+        related: [{ message: `${sameGroup.name} is defined here`, location: sameGroup.definition }],
+      })
+      continue
+    }
+    byKey.set(definition.key, sameKey ?? definition)
+    byGroup.set(definition.group, sameGroup ?? definition)
+    const list = members.get(definition.group) ?? []
+    list.push(definition)
+    members.set(definition.group, list)
+  }
+  const required: RequiredRouteGroup[] = []
+  for (const first of byGroup.values()) {
+    if (!first.required) {
+      continue
+    }
+    // the decorators of the group in source order: `@Public(), @Authenticated() or @Roles(...)`
+    const decorators = [...(members.get(first.group) ?? [first])]
+      .sort((a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start)
+      .map(member => Object.freeze({ ...member }))
+    const usages = decorators.map(member => `@${member.name}(${member.flag ? '' : '...'})`)
+    const suggestion =
+      usages.length === 1 ? (usages[0] as string) : `${usages.slice(0, -1).join(', ')} or ${usages.at(-1) as string}`
+    required.push(Object.freeze({ group: first.group, decorators: Object.freeze(decorators), suggestion }))
+  }
+  return { conflicts, required }
+}
+
+/**
+ * The required route decorator groups of the application (RFC 0001): what every route-like target
+ * of another extension (a gateway, a GraphQL root field) must decide, exactly as HTTP routes must.
+ * A target without a decision of a returned group is **ZNIGHT023**, reported by the caller.
+ *
+ * `applied` are the route metadata entries the caller read on its own targets
+ * ({@link readRouteMeta}): they make decorators known even when the compiler has no
+ * `definitionsOf`, and refine how flags are suggested. Inconsistent definitions are left out and
+ * not reported here: the http extension reports them (ZNIGHT005) once.
+ *
+ * ```ts
+ * validate(ctx) {
+ *   const required = requiredRouteGroups(ctx, ctx.stored.flatMap(gateway => gateway.meta))
+ *   for (const gateway of ctx.stored)
+ *     for (const group of required)
+ *       if (!gateway.meta.some(entry => entry.group === group.group))
+ *         ctx.report({ code: 'ZNIGHT023', severity: 'error', message: `${gateway.name} has no "${group.group}" decision`,
+ *           location: gateway.location, hints: [`Add ${group.suggestion} to ${gateway.name}`] })
+ * }
+ * ```
+ */
+export function requiredRouteGroups(
+  ctx: ValidateContext<unknown>,
+  applied: Iterable<MetaEntry> = [],
+): readonly RequiredRouteGroup[] {
+  return analyzeRouteGroups(ctx, applied).required
+}
+
+function describeOptions(entry: RouteGroupMember): string {
+  const group = entry.group === entry.key ? 'no group' : `group "${entry.group}"`
+  return entry.required ? `${group}, required` : group
+}

package/src/compiler/validate.ts

@@ -7,10 +7,11 @@
 import type { Location, ValidateContext } from '@znight/compiler'
 import type { RoutePath } from '../path.ts'
 import type { HttpControllerData, HttpRouteData, MetaEntry } from './model.ts'
+import type { RequiredRouteGroup, RouteGroupMember } from './route-groups.ts'
 
 import { checkRoutePath, compareStrings, parseRoutePath, WILDCARD_PARAM } from '../path.ts'
-import { Codes, Ids } from './model.ts'
-import { parseRouteDecoratorOptions } from './route-decorators.ts'
+import { Codes } from './model.ts'
+import { analyzeRouteGroups } from './route-groups.ts'
 
 type Context = ValidateContext<HttpControllerData>
 
@@ -69,80 +70,12 @@ export function validateHttp(ctx: Context): void {
   validateDecisions(ctx, controllers)
 }
 
-/** A route decorator definition seen during the compile (applied, or found by `definitionsOf`). */
-interface Definition {
-  readonly identity: string
-  readonly name: string
-  readonly key: string
-  readonly group: string
-  readonly required: boolean
-  readonly definition: Location
-  /** A flag (`@Public()`): no type argument, or every usage without argument. */
-  flag: boolean
-}
-
-/**
- * Every route decorator definition, sorted by identity: the applied ones (first usage) and, when
- * the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are left to the
- * usages, which report them).
- */
-function routeDecoratorDefinitions(ctx: Context, controllers: readonly HttpControllerData[]): Definition[] {
-  const definitions = new Map<string, Definition>()
-  const visit = (entries: readonly MetaEntry[]): void => {
-    for (const entry of entries) {
-      const known = definitions.get(entry.identity)
-      if (known === undefined) {
-        definitions.set(entry.identity, {
-          identity: entry.identity,
-          name: entry.decorator,
-          key: entry.key,
-          group: entry.group,
-          required: entry.required,
-          definition: entry.definition,
-          flag: entry.value === true,
-        })
-      } else if (entry.value !== true) {
-        known.flag = false
-      }
-    }
-  }
+/** Every route metadata entry of the controllers: controller entries, then route entries. */
+function* appliedEntries(controllers: readonly HttpControllerData[]): Generator<MetaEntry> {
   for (const controller of controllers) {
-    visit(controller.meta)
-    for (const route of controller.routes) visit(route.meta)
-  }
-  // compilers before RFC 0001 have no definitionsOf: only applied decorators are known then
-  const all = typeof ctx.definitionsOf === 'function' ? ctx.definitionsOf(Ids.createRouteDecorator) : []
-  for (const found of all) {
-    const [keyArg, optionsArg, ...extra] = found.args
-    const key = keyArg?.evaluated === true ? keyArg.value : undefined
-    if (
-      typeof key !== 'string' ||
-      key === '' ||
-      extra.length > 0 ||
-      (optionsArg !== undefined && !optionsArg.evaluated)
-    ) {
-      continue
-    }
-    const parsed = parseRouteDecoratorOptions(key, optionsArg?.value)
-    if ('error' in parsed) {
-      continue
-    }
-    const flag = found.typeArgs.length === 0
-    const known = definitions.get(found.identity)
-    if (known !== undefined) {
-      known.flag &&= flag
-      continue
-    }
-    definitions.set(found.identity, {
-      identity: found.identity,
-      name: found.name,
-      key,
-      ...parsed,
-      definition: found.location,
-      flag,
-    })
+    yield* controller.meta
+    for (const route of controller.routes) yield* route.meta
   }
-  return [...definitions.values()].sort((a, b) => compareStrings(a.identity, b.identity))
 }
 
 /**
@@ -151,45 +84,10 @@ function routeDecoratorDefinitions(ctx: Context, controllers: readonly HttpContr
  * a decision of every required group, its own or its controller's (ZNIGHT023).
  */
 function validateDecisions(ctx: Context, controllers: readonly HttpControllerData[]): void {
-  const definitions = routeDecoratorDefinitions(ctx, controllers)
-  if (definitions.length === 0) {
-    return
-  }
-  const byKey = new Map<string, Definition>()
-  const byGroup = new Map<string, Definition>()
-  const members = new Map<string, Definition[]>()
-  for (const definition of definitions) {
-    const sameKey = byKey.get(definition.key)
-    if (sameKey !== undefined && (sameKey.group !== definition.group || sameKey.required !== definition.required)) {
-      ctx.report({
-        code: Codes.InvalidDecorator,
-        severity: 'error',
-        message: `The route decorator ${definition.name} defines the key "${definition.key}" with ${describeOptions(definition)}, but ${sameKey.name} defines it with ${describeOptions(sameKey)}`,
-        location: definition.definition,
-        hints: ['Every definition of a key must use the same options: share one definition'],
-        related: [{ message: `${sameKey.name} is defined here`, location: sameKey.definition }],
-      })
-      continue
-    }
-    const sameGroup = byGroup.get(definition.group)
-    if (sameGroup !== undefined && sameGroup.required !== definition.required) {
-      ctx.report({
-        code: Codes.InvalidDecorator,
-        severity: 'error',
-        message: `The "${definition.group}" group is ${definition.required ? '' : 'not '}required for ${definition.name} but ${sameGroup.required ? '' : 'not '}required for ${sameGroup.name}`,
-        location: definition.definition,
-        hints: [`All the decorators of the "${definition.group}" group must agree on required`],
-        related: [{ message: `${sameGroup.name} is defined here`, location: sameGroup.definition }],
-      })
-      continue
-    }
-    byKey.set(definition.key, sameKey ?? definition)
-    byGroup.set(definition.group, sameGroup ?? definition)
-    const list = members.get(definition.group) ?? []
-    list.push(definition)
-    members.set(definition.group, list)
+  const { conflicts, required } = analyzeRouteGroups(ctx, appliedEntries(controllers))
+  for (const conflict of conflicts) {
+    ctx.report(conflict)
   }
-  const required = [...byGroup.values()].filter(definition => definition.required)
   if (required.length === 0) {
     return
   }
@@ -201,23 +99,14 @@ function validateDecisions(ctx: Context, controllers: readonly HttpControllerDat
         if (decided.has(group.group)) {
           continue
         }
-        // the decorators of the group in source order: `@Public(), @Authenticated() or @Roles(...)`
-        const inOrder = [...(members.get(group.group) ?? [group])].sort(
-          (a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start,
-        )
-        const decorators = inOrder.map(definition => `@${definition.name}(${definition.flag ? '' : '...'})`)
-        const listed =
-          decorators.length === 1
-            ? (decorators[0] as string)
-            : `${decorators.slice(0, -1).join(', ')} or ${decorators.at(-1) as string}`
         ctx.report({
           code: Codes.MissingRouteDecision,
           severity: 'error',
           message: `Route ${route.method} ${route.fullPath} (${controller.displayName}.${route.handler}) has no "${group.group}" decision`,
           location: route.location,
-          hints: [`Add ${listed} to the route or to ${controller.displayName}`],
+          hints: [`Add ${group.suggestion} to the route or to ${controller.displayName}`],
           related: [
-            { message: `The "${group.group}" group is required`, location: (inOrder[0] ?? group).definition },
+            { message: `The "${group.group}" group is required`, location: firstDefinition(group) },
             { message: `${controller.displayName} is declared here`, location: controller.location },
           ],
         })
@@ -226,9 +115,9 @@ function validateDecisions(ctx: Context, controllers: readonly HttpControllerDat
   }
 }
 
-function describeOptions(entry: Definition): string {
-  const group = entry.group === entry.key ? 'no group' : `group "${entry.group}"`
-  return entry.required ? `${group}, required` : group
+/** Where the first decorator of a group (source order) is defined. */
+function firstDefinition(group: RequiredRouteGroup): Location {
+  return (group.decorators[0] as RouteGroupMember).definition
 }
 
 const GRAMMAR_HINTS: readonly string[] = [

package/src/decorators.ts

@@ -398,14 +398,30 @@ export interface RouteMetaEntry<T = unknown> {
   readonly required?: boolean
 }
 
+/**
+ * Anything that carries effective route metadata: the {@link HttpContext} of a request, and the
+ * contexts of other transports that reuse route decorators (a GraphQL resolver context, a WebSocket
+ * gateway context). {@link RouteDecorator.get} reads `route.meta[key]`; nothing else is required.
+ *
+ * ```ts
+ * const carrier: RouteMetaCarrier = { route: { meta: { roles: ['admin'] } } }
+ * Roles.get(carrier) // ['admin']
+ * ```
+ */
+export interface RouteMetaCarrier {
+  /** The matched route (or field, or handler), `undefined` when there is none. */
+  readonly route?: { readonly meta: Readonly<Record<string, unknown>> } | undefined
+}
+
 /** A user-defined route metadata decorator created with {@link createRouteDecorator}. */
 export interface RouteDecorator<T> extends RouteDecoratorInfo {
   (...args: RouteDecoratorArgs<T>): ClassMarker & MethodMarker
   /**
    * The value of the current route, if set. Reads the effective metadata: the route's decision of
-   * a group wins over the controller's.
+   * a group wins over the controller's. Accepts any {@link RouteMetaCarrier}: an
+   * {@link HttpContext}, or the context of another transport exposing `route.meta`.
    */
-  get(ctx: HttpContext): T | undefined
+  get(ctx: RouteMetaCarrier): T | undefined
   /**
    * The same metadata as data (`{ key, value, group, required }`), for routes that are not compiled
    * controllers (plugin routes: `OpenApiPlugin.configure({ meta: [Public.meta()] })`). The value is
@@ -479,7 +495,7 @@ export function createRouteDecorator<T = true>(key: string, options?: RouteDecor
     key,
     group,
     required,
-    get: (ctx: HttpContext): T | undefined => ctx.route?.meta[key] as T | undefined,
+    get: (ctx: RouteMetaCarrier): T | undefined => ctx.route?.meta[key] as T | undefined,
     meta: (...args: RouteDecoratorArgs<T>): RouteMetaEntry<T> =>
       Object.freeze({ key, value: (args.length === 0 ? true : args[0]) as T, group, required }),
   })

package/src/index.ts

@@ -92,6 +92,7 @@ export {
   type RouteDecoratorArgs,
   type RouteDecoratorInfo,
   type RouteDecoratorOptions,
+  type RouteMetaCarrier,
   type RouteMetaEntry,
   SignedCookie,
   Sse,