@c9up/ream 0.1.24 → 0.1.26

package/src/router/Router.ts

@@ -7,8 +7,21 @@
 import type { HttpContext } from '../http/HttpContext.js'
 import { safeDecodeURIComponent } from '../http/urlDecode.js'
 import type { MiddlewareFunction } from '../middleware/Pipeline.js'
+import type { SignedUrl } from '../security/SignedUrl.js'
 import type { MiddlewareEntry } from '../server/Server.js'
-import { resolveMiddlewareEntry } from '../server/Server.js'
+import { resolveMiddlewareEntry, resolveParametrizedMiddlewareEntry } from '../server/Server.js'
+import { singular, snakeCase } from '../utils/inflect.js'
+import { Macroable } from '../utils/Macroable.js'
+
+/** Options for {@link Router.makeSignedUrl}. */
+export interface SignedUrlOptions {
+  /** Extra query-string params folded into the signature. */
+  qs?: Record<string, string>
+  /** Lifetime before the link expires — seconds (number) or a `'30m'`/`'2h'`/`'1d'` string. */
+  expiresIn?: string | number
+  /** Namespaces the signature so a URL signed for one purpose can't be reused for another. */
+  purpose?: string
+}
 
 // ─── Types ──────────────────────────────────────────────────
 
@@ -22,8 +35,21 @@ export type RouteHandlerFunction = (ctx: HttpContext) => Promise<void> | void
 // biome-ignore lint/suspicious/noExplicitAny: required — TypeScript contravariance makes it impossible to type "any constructor" without `any`
 export type ControllerAction = [target: new (...args: any[]) => any, method: string]
 
-/** A route handler is either a closure or a controller tuple. */
-export type RouteHandler = RouteHandlerFunction | ControllerAction
+/** Any controller class (derived from {@link ControllerAction} — no fresh `any`). */
+export type ControllerConstructor = ControllerAction[0]
+
+/** A lazy controller import: `() => import('#controllers/users_controller')`. */
+export type LazyControllerImport = () => Promise<{ default: ControllerConstructor }>
+
+/** Lazy controller tuple: [() => import(...), 'methodName']. */
+export type LazyControllerAction = [loader: LazyControllerImport, method: string]
+
+/**
+ * A route handler is a closure, a controller tuple, a lazy-import tuple, or a
+ * magic string reference `'ControllerName.method'` resolved through the
+ * router's controller registry ({@link Router.controllers}).
+ */
+export type RouteHandler = RouteHandlerFunction | ControllerAction | LazyControllerAction | string
 
 /** Param matcher — regex or predefined matcher. */
 export type ParamMatcher = RegExp | { pattern: RegExp }
@@ -45,6 +71,77 @@ export interface RouteDefinition {
   domain?: string
   matchers: Record<string, ParamMatcher>
   deprecates?: { version: string; sunset?: string }
+  /**
+   * Soft-delete flag (AdonisJS `route.markAsDeleted()`). A resource's
+   * `.only()`/`.except()`/`.apiOnly()` mark filtered-out routes deleted rather
+   * than splicing them, so the builder chain stays intact. Deleted routes are
+   * skipped by the match index and `getRoutes()`.
+   */
+  deleted?: boolean
+  /**
+   * Lazily-imported controller (from a `[() => import(...), 'method']` tuple or
+   * a resolved string reference). The HttpKernel awaits the loader on first
+   * request and promotes it to {@link controller}, so @Guard metadata + DI
+   * resolution flow through the normal controller path.
+   */
+  lazyController?: { loader: LazyControllerImport; method: string }
+  /**
+   * Unresolved `'ControllerName.method'` string reference. Resolved to
+   * {@link lazyController} against the router's controller registry when the
+   * route index is (re)built — a reference to an unregistered controller is a
+   * hard error there.
+   */
+  stringRef?: { controller: string; method: string }
+}
+
+/**
+ * Distinguish a lazy-import loader from a controller class in a handler tuple.
+ * Arrow/plain function loaders (`() => import(...)`) have no own `prototype`
+ * property; class constructors do.
+ */
+function isLazyControllerLoader(
+  first: ControllerConstructor | LazyControllerImport,
+): first is LazyControllerImport {
+  return !('prototype' in first)
+}
+
+/** Build a route definition from a method, path, and handler. */
+function makeDefinition(method: string, path: string, handler: RouteHandler): RouteDefinition {
+  const def: RouteDefinition = {
+    method: method.toUpperCase(),
+    path,
+    handler: null,
+    middleware: [],
+    inlineMiddleware: [],
+    guards: [],
+    roles: [],
+    permissions: [],
+    validators: [],
+    matchers: {},
+  }
+
+  if (typeof handler === 'string') {
+    // Magic string reference 'ControllerName.method' — split on the LAST dot so
+    // controller names may themselves be dotted; resolved at #buildIndex time.
+    const dot = handler.lastIndexOf('.')
+    if (dot <= 0 || dot === handler.length - 1) {
+      throw new Error(
+        `Invalid controller reference "${handler}" — expected the form "ControllerName.method".`,
+      )
+    }
+    def.stringRef = { controller: handler.slice(0, dot), method: handler.slice(dot + 1) }
+  } else if (Array.isArray(handler)) {
+    const [first, methodName] = handler
+    if (isLazyControllerLoader(first)) {
+      def.lazyController = { loader: first, method: methodName }
+    } else {
+      def.controller = { target: first, method: methodName }
+    }
+  } else {
+    def.handler = handler
+  }
+
+  return def
 }
 
 export interface MatchResult {
@@ -69,56 +166,102 @@ export const matchers = {
   },
 }
 
+/**
+ * Normalise a param matcher into the internal `{ pattern }` shape.
+ *
+ * A string matcher (AdonisJS `.where('id', '[0-9]+')`) is compiled to an
+ * anchored RegExp. AdonisJS builds `new RegExp(matcher)` unanchored and relies
+ * on `matchit`'s per-segment anchoring; ream tests matchers per-segment without
+ * that implicit anchoring (and its predefined matchers are already `^…$`), so
+ * anchoring here reproduces AdonisJS's *effective* full-segment semantics.
+ */
+function compileMatcher(matcher: ParamMatcher | RegExp | string): ParamMatcher {
+  if (typeof matcher === 'string') return { pattern: new RegExp(`^(?:${matcher})$`) }
+  return matcher instanceof RegExp ? { pattern: matcher } : matcher
+}
+
 // ─── RouteBuilder ───────────────────────────────────────────
 
-/** Fluent route builder — mutates the already-registered route definition. */
-export class RouteBuilder {
-  #route: RouteDefinition
+/**
+ * Fluent route builder — mutates the already-registered route definition(s).
+ * Backed by an array so a multi-verb `router.route(['GET','POST'], …)` returns
+ * ONE builder that fans every mutation across all its verbs; the single-verb
+ * helpers (`get`/`post`/…) back it with a one-element array.
+ */
+export class RouteBuilder extends Macroable {
+  #routes: RouteDefinition[]
+
+  constructor(routes: RouteDefinition | RouteDefinition[]) {
+    super()
+    this.#routes = Array.isArray(routes) ? routes : [routes]
+  }
 
-  constructor(route: RouteDefinition) {
-    this.#route = route
+  /** Apply `fn` to every backing definition, returning `this` for chaining. */
+  #each(fn: (route: RouteDefinition) => void): this {
+    for (const route of this.#routes) fn(route)
+    return this
+  }
+
+  /** The primary definition — accessors read from it (all verbs share pattern/name). */
+  #primary(): RouteDefinition {
+    return this.#routes[0]
   }
 
   /** Name this route (for URL generation and redirects). */
   as(name: string): this {
-    this.#route.name = name
-    return this
+    return this.#each((route) => {
+      route.name = name
+    })
+  }
+
+  /** Prepend a URL prefix to this single route (AdonisJS route-level `prefix`). */
+  prefix(prefix: string): this {
+    return this.#each((route) => {
+      route.path = prefix + route.path
+    })
   }
 
   /** Add named middleware. */
   middleware(...names: string[]): this {
-    this.#route.middleware.push(...names)
-    return this
+    return this.#each((route) => {
+      route.middleware.push(...names)
+    })
   }
 
   /** Add inline middleware functions. */
   use(...mw: MiddlewareFunction[]): this {
-    this.#route.inlineMiddleware.push(...mw)
-    return this
+    return this.#each((route) => {
+      route.inlineMiddleware.push(...mw)
+    })
   }
 
   /** Add authentication guards. */
   guard(...guards: string[]): this {
-    this.#route.guards.push(...guards)
-    return this
+    return this.#each((route) => {
+      route.guards.push(...guards)
+    })
   }
 
   /** Require specific roles. */
   role(...roles: string[]): this {
-    this.#route.roles.push(...roles)
-    return this
+    return this.#each((route) => {
+      route.roles.push(...roles)
+    })
   }
 
   /** Require specific permissions. */
   permission(...permissions: string[]): this {
-    this.#route.permissions.push(...permissions)
-    return this
+    return this.#each((route) => {
+      route.permissions.push(...permissions)
+    })
   }
 
-  /** Add a param constraint. */
-  where(param: string, matcher: ParamMatcher | RegExp): this {
-    this.#route.matchers[param] = matcher instanceof RegExp ? { pattern: matcher } : matcher
-    return this
+  /** Add a param constraint — RegExp, predefined matcher, or a string pattern. */
+  where(param: string, matcher: ParamMatcher | RegExp | string): this {
+    const compiled = compileMatcher(matcher)
+    return this.#each((route) => {
+      route.matchers[param] = compiled
+    })
   }
 
   /**
@@ -137,41 +280,75 @@ export class RouteBuilder {
    * An unregistered name is a hard error — validation is never silently skipped.
    */
   validate(validator: string): this {
-    this.#route.validators.push(validator)
-    return this
+    return this.#each((route) => {
+      route.validators.push(validator)
+    })
   }
 
   /** Set API version. */
   version(v: string): this {
-    this.#route.version = v
-    return this
+    return this.#each((route) => {
+      route.version = v
+    })
   }
 
   /** Restrict to a specific domain. */
   domain(d: string): this {
-    this.#route.domain = d
-    return this
+    return this.#each((route) => {
+      route.domain = d
+    })
   }
 
   /** Mark as deprecated. */
   deprecates(version: string, options?: { sunset?: string }): this {
-    this.#route.deprecates = { version, sunset: options?.sunset }
-    return this
+    return this.#each((route) => {
+      route.deprecates = { version, sunset: options?.sunset }
+    })
+  }
+
+  /** The route's name, or undefined when unnamed (AdonisJS `route.getName`). */
+  getName(): string | undefined {
+    return this.#primary().name
   }
 
-  /** @internal Get the underlying definition. */
+  /** The route's URL pattern (AdonisJS `route.getPattern`). */
+  getPattern(): string {
+    return this.#primary().path
+  }
+
+  /** Replace the route's URL pattern (AdonisJS `route.setPattern`). */
+  setPattern(pattern: string): this {
+    return this.#each((route) => {
+      route.path = pattern
+    })
+  }
+
+  /** Soft-delete this route so it stops matching (AdonisJS `route.markAsDeleted`). */
+  markAsDeleted(): this {
+    return this.#each((route) => {
+      route.deleted = true
+    })
+  }
+
+  /** True when the route has been soft-deleted (AdonisJS `route.isDeleted`). */
+  isDeleted(): boolean {
+    return this.#primary().deleted === true
+  }
+
+  /** @internal Get the underlying (primary) definition. */
   getDefinition(): RouteDefinition {
-    return this.#route
+    return this.#primary()
   }
 }
 
 // ─── GroupBuilder ───────────────────────────────────────────
 
 /** Fluent group builder — returned by router.group(callback). */
-export class GroupBuilder {
+export class GroupBuilder extends Macroable {
   #routes: RouteDefinition[]
 
   constructor(routes: RouteDefinition[]) {
+    super()
     this.#routes = routes
   }
 
@@ -207,12 +384,19 @@ export class GroupBuilder {
     return this
   }
 
-  /** Prefix route names for all routes in the group. */
+  /**
+   * Prefix route names for all routes in the group (AdonisJS `group.as`).
+   * Every route MUST already be named — prefixing an unnamed route is
+   * meaningless, so it throws rather than silently skipping (AdonisJS parity).
+   */
   as(namePrefix: string): this {
     for (const route of this.#routes) {
-      if (route.name) {
-        route.name = `${namePrefix}.${route.name}`
+      if (!route.name) {
+        throw new Error(
+          `[E_MISSING_ROUTE_NAME] Cannot apply group name "${namePrefix}": route ${route.method} ${route.path} has no name. Name every route in a named group (\`.as(...)\`), or move the unnamed route out of the group.`,
+        )
       }
+      route.name = `${namePrefix}.${route.name}`
     }
     return this
   }
@@ -226,8 +410,8 @@ export class GroupBuilder {
   }
 
   /** Add param matcher to all routes in the group. */
-  where(param: string, matcher: ParamMatcher | RegExp): this {
-    const m = matcher instanceof RegExp ? { pattern: matcher } : matcher
+  where(param: string, matcher: ParamMatcher | RegExp | string): this {
+    const m = compileMatcher(matcher)
     for (const route of this.#routes) {
       if (!(param in route.matchers)) {
         route.matchers[param] = m
@@ -237,6 +421,206 @@ export class GroupBuilder {
   }
 }
 
+// ─── RouteResource ──────────────────────────────────────────
+
+/** Resourceful action names (AdonisJS resource). */
+export type ResourceAction = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy'
+
+/** Middleware accepted per-action on a resource: a named string or an inline fn. */
+type ResourceMiddleware = string | MiddlewareFunction
+
+/**
+ * Resourceful route builder — returned by `router.resource()` /
+ * `router.shallowResource()` (AdonisJS `RouteResource` parity).
+ *
+ * Generates the seven RESTful routes (index, create, store, show, edit,
+ * update, destroy — `update` registered for both PUT and PATCH) and exposes
+ * the fluent filtering/config API: `only`/`except`/`apiOnly`/`params`/`tap`/
+ * `where`/`use`/`middleware`/`as`. Nested resources use dot-notation
+ * (`posts.comments` → `/posts/:post_id/comments/:id`).
+ */
+export class RouteResource extends Macroable {
+  #resource: string
+  #controller: ControllerAction[0]
+  #shallow: boolean
+  #register: (def: RouteDefinition) => void
+  #markDirty: () => void
+  /** Resource name → param placeholder (`comments` → `:id`, `posts` → `:post_id`). */
+  #params: Record<string, string> = {}
+  #baseName: string
+
+  /** The generated routes, in declaration order (AdonisJS `resource.routes`). */
+  readonly routes: RouteBuilder[] = []
+
+  constructor(options: {
+    resource: string
+    controller: ControllerAction[0]
+    shallow: boolean
+    register: (def: RouteDefinition) => void
+    markDirty: () => void
+  }) {
+    super()
+    const resource = options.resource.replace(/^\//, '').replace(/\/$/, '')
+    if (!resource) throw new Error(`Invalid resource name "${options.resource}"`)
+    this.#resource = resource
+    this.#controller = options.controller
+    this.#shallow = options.shallow
+    this.#register = options.register
+    this.#markDirty = options.markDirty
+    this.#baseName = resource.split('.').map(snakeCase).join('.')
+    this.#buildRoutes()
+  }
+
+  #createRoute(pattern: string, method: string, action: ResourceAction): void {
+    const def = makeDefinition(method, `/${pattern}`, [this.#controller, action])
+    def.name = `${this.#baseName}.${action}`
+    this.#register(def)
+    this.routes.push(new RouteBuilder(def))
+  }
+
+  #buildRoutes(): void {
+    const segments = this.#resource.split('.')
+    const main = segments.pop() ?? this.#resource
+    this.#params[main] = ':id'
+
+    const parentPath = segments
+      .map((parent) => {
+        const param = `:${snakeCase(singular(parent))}_id`
+        this.#params[parent] = param
+        return `${parent}/${param}`
+      })
+      .join('/')
+
+    const baseURI = parentPath ? `${parentPath}/${main}` : main
+    // Shallow member routes drop the parent prefix — the id alone identifies
+    // the record (AdonisJS shallow resources).
+    const memberBase = this.#shallow ? main : baseURI
+
+    this.#createRoute(baseURI, 'GET', 'index')
+    this.#createRoute(`${baseURI}/create`, 'GET', 'create')
+    this.#createRoute(baseURI, 'POST', 'store')
+    this.#createRoute(`${memberBase}/:id`, 'GET', 'show')
+    this.#createRoute(`${memberBase}/:id/edit`, 'GET', 'edit')
+    this.#createRoute(`${memberBase}/:id`, 'PUT', 'update')
+    this.#createRoute(`${memberBase}/:id`, 'PATCH', 'update')
+    this.#createRoute(`${memberBase}/:id`, 'DELETE', 'destroy')
+  }
+
+  /** Routes whose name ends with one of `names` (the action suffix). */
+  #matching(names: string[]): RouteBuilder[] {
+    return this.routes.filter((route) => {
+      const name = route.getName()
+      return name !== undefined && names.some((action) => name.endsWith(action))
+    })
+  }
+
+  /** Keep only the given actions; soft-delete the rest (AdonisJS `only`). */
+  only(names: ResourceAction[]): this {
+    const keep = new Set(this.#matching(names))
+    for (const route of this.routes) if (!keep.has(route)) route.markAsDeleted()
+    this.#markDirty()
+    return this
+  }
+
+  /** Register all actions except the given ones (AdonisJS `except`). */
+  except(names: ResourceAction[]): this {
+    for (const route of this.#matching(names)) route.markAsDeleted()
+    this.#markDirty()
+    return this
+  }
+
+  /** Drop the form-rendering `create` + `edit` actions (AdonisJS `apiOnly`). */
+  apiOnly(): this {
+    return this.except(['create', 'edit'])
+  }
+
+  /** Constrain a param across every action route (AdonisJS `resource.where`). */
+  where(key: string, matcher: ParamMatcher | RegExp | string): this {
+    for (const route of this.routes) route.where(key, matcher)
+    return this
+  }
+
+  /**
+   * Configure the resource's routes. `tap(cb)` runs `cb` for every non-deleted
+   * route; `tap(actions, cb)` only for routes matching `actions` (AdonisJS `tap`).
+   */
+  tap(callback: (route: RouteBuilder) => void): this
+  tap(actions: ResourceAction | ResourceAction[], callback: (route: RouteBuilder) => void): this
+  tap(
+    actionsOrCallback: ResourceAction | ResourceAction[] | ((route: RouteBuilder) => void),
+    callback?: (route: RouteBuilder) => void,
+  ): this {
+    if (typeof actionsOrCallback === 'function') {
+      for (const route of this.routes) if (!route.isDeleted()) actionsOrCallback(route)
+      return this
+    }
+    const names = Array.isArray(actionsOrCallback) ? actionsOrCallback : [actionsOrCallback]
+    if (callback) {
+      for (const route of this.#matching(names)) if (!route.isDeleted()) callback(route)
+    }
+    return this
+  }
+
+  /** Rename the `:id` param of one or more resources (AdonisJS `params`). */
+  params(resources: Record<string, string>): this {
+    for (const [resource, param] of Object.entries(resources)) {
+      const existing = this.#params[resource]
+      if (!existing) continue
+      this.#params[resource] = `:${param}`
+      for (const route of this.routes) {
+        route.setPattern(
+          route.getPattern().replace(`${resource}/${existing}`, `${resource}/:${param}`),
+        )
+      }
+    }
+    this.#markDirty()
+    return this
+  }
+
+  /**
+   * Attach middleware to specific actions (or `'*'` for all) — AdonisJS `use`.
+   * Named middleware are strings; inline middleware are functions.
+   */
+  use(
+    actions: ResourceAction | ResourceAction[] | '*',
+    middleware: ResourceMiddleware | ResourceMiddleware[],
+  ): this {
+    const list = Array.isArray(middleware) ? middleware : [middleware]
+    const apply = (route: RouteBuilder): void => {
+      for (const mw of list) {
+        if (typeof mw === 'string') route.middleware(mw)
+        else route.use(mw)
+      }
+    }
+    if (actions === '*') this.tap(apply)
+    else this.tap(actions, apply)
+    return this
+  }
+
+  /** Alias for {@link RouteResource.use} (AdonisJS `middleware`). */
+  middleware(
+    actions: ResourceAction | ResourceAction[] | '*',
+    middleware: ResourceMiddleware | ResourceMiddleware[],
+  ): this {
+    return this.use(actions, middleware)
+  }
+
+  /**
+   * Rename the base of every route name (AdonisJS `as`). `normalizeName`
+   * snake_cases the new base by default.
+   */
+  as(name: string, normalizeName = true): this {
+    const newBase = normalizeName ? snakeCase(name) : name
+    for (const route of this.routes) {
+      const current = route.getName()
+      if (current) route.as(current.replace(this.#baseName, newBase))
+    }
+    this.#baseName = newBase
+    this.#markDirty()
+    return this
+  }
+}
+
 // ─── View engine helper ───────────────────────────────────────
 
 interface ViewEngine {
@@ -254,7 +638,7 @@ function isViewEngine(value: unknown): value is ViewEngine {
 
 // ─── OnRouteBuilder ─────────────────────────────────────────
 
-/** Builder for on(path).render(view) and on(path).redirect(target). */
+/** Builder for on(path).render(view) and on(path).redirect(namedRoute). */
 export class OnRouteBuilder {
   #router: Router
   #path: string
@@ -277,17 +661,21 @@ export class OnRouteBuilder {
     })
   }
 
-  /** Redirect to a path. */
-  redirect(target: string, status = 302): RouteBuilder {
+  /**
+   * Redirect to a NAMED route (AdonisJS brisk `redirect`). Mirrors AdonisJS:
+   * the first argument is a route name, not a path — use {@link redirectToPath}
+   * for a fixed URL.
+   */
+  redirect(name: string, params?: Record<string, string>, status = 302): RouteBuilder {
     return this.#router.get(this.#path, async (ctx) => {
-      ctx.response.redirect().status(status).toPath(target)
+      ctx.response.redirect().status(status).toRoute(name, params)
     })
   }
 
-  /** Redirect to a named route. */
-  redirectToRoute(name: string, params?: Record<string, string>, status = 302): RouteBuilder {
+  /** Redirect to a fixed path/URL (AdonisJS brisk `redirectToPath`). */
+  redirectToPath(target: string, status = 302): RouteBuilder {
     return this.#router.get(this.#path, async (ctx) => {
-      ctx.response.redirect().status(status).toRoute(name, params)
+      ctx.response.redirect().status(status).toPath(target)
     })
   }
 }
@@ -295,11 +683,15 @@ export class OnRouteBuilder {
 // ─── Router ─────────────────────────────────────────────────
 
 /** Main Router. */
-export class Router {
+export class Router extends Macroable {
   #routes: RouteDefinition[] = []
   #globalMatchers: Record<string, ParamMatcher> = {}
   #routerMiddleware: MiddlewareFunction[] = []
   #namedMiddleware: Map<string, MiddlewareFunction> = new Map()
+  /** Controller registry: name → lazy import, for string handler references. */
+  #controllers: Map<string, LazyControllerImport> = new Map()
+  /** APP_KEY-backed signed-URL helper (injected by the Ignitor when set). */
+  #signedUrl?: SignedUrl
 
   /** Index: static routes by "METHOD:path" for O(1) exact match. */
   #staticIndex: Map<string, RouteDefinition> = new Map()
@@ -327,19 +719,49 @@ export class Router {
   }
 
   /**
-   * Register named middleware collection.
+   * Register a named middleware collection and return per-name FACTORIES
+   * (AdonisJS `defineNamedMiddleware`). Call a factory to bind per-route
+   * arguments, then attach the result inline:
+   *
    *   export const middleware = router.named({
    *     auth: () => import('#middleware/auth_middleware'),
    *   })
+   *   router.get('/admin', [AdminController, 'index']).use([middleware.auth({ guards: ['web'] })])
+   *
+   * By-name usage (`route.middleware('auth')`) still runs the middleware with
+   * no arguments — the factory form is only needed to pass `args` to `handle`.
    */
-  named(collection: Record<string, MiddlewareEntry>): Record<string, MiddlewareFunction> {
-    const resolved: Record<string, MiddlewareFunction> = {}
+  named(
+    collection: Record<string, MiddlewareEntry>,
+  ): Record<string, (args?: unknown) => MiddlewareFunction> {
+    const factories: Record<string, (args?: unknown) => MiddlewareFunction> = {}
     for (const [name, mw] of Object.entries(collection)) {
-      const fn = resolveMiddlewareEntry(mw)
-      this.#namedMiddleware.set(name, fn)
-      resolved[name] = fn
+      // By-name resolution (`route.middleware('auth')`) uses the no-arg form.
+      this.#namedMiddleware.set(name, resolveMiddlewareEntry(mw))
+      // The returned factory bakes in per-route args for inline `.use()`.
+      factories[name] = resolveParametrizedMiddlewareEntry(mw)
+    }
+    return factories
+  }
+
+  /**
+   * Register controllers for magic string handler references (AdonisJS lazy
+   * controller pattern). Each entry maps a controller name to a lazy import:
+   *
+   *   router.controllers({ UsersController: () => import('#controllers/users_controller') })
+   *   router.get('/users', 'UsersController.index')
+   *
+   * The class is imported on first request and resolved through the IoC
+   * container (so @inject + @Guard/@Role decorators work). A string reference
+   * to a name that was never registered fails loudly when the route index is
+   * built.
+   */
+  controllers(map: Record<string, LazyControllerImport>): this {
+    for (const [name, loader] of Object.entries(map)) {
+      this.#controllers.set(name, loader)
     }
-    return resolved
+    this.#indexDirty = true
+    return this
   }
 
   /** Get the router-level middleware stack. */
@@ -354,12 +776,20 @@ export class Router {
 
   // ─── Route registration ───────────────────────────────────
 
-  /** Register a route with any HTTP method. */
-  route(method: string, path: string, handler: RouteHandler): RouteBuilder {
-    const def = this.#createDefinition(method, path, handler)
-    this.#routes.push(def)
+  /**
+   * Register a route for one verb or several (AdonisJS `route(pattern, methods)`
+   * accepts an array). A multi-verb call returns a single builder that
+   * configures every verb at once.
+   */
+  route(method: string | string[], path: string, handler: RouteHandler): RouteBuilder {
+    const methods = Array.isArray(method) ? method : [method]
+    const defs = methods.map((verb) => {
+      const def = this.#createDefinition(verb, path, handler)
+      this.#routes.push(def)
+      return def
+    })
     this.#indexDirty = true
-    return new RouteBuilder(def)
+    return new RouteBuilder(defs)
   }
 
   get(path: string, handler: RouteHandler): RouteBuilder {
@@ -398,40 +828,54 @@ export class Router {
   // ─── Resource routes ──────────────────────────────────────
 
   /**
-   * Register resourceful routes for a controller.
-   * Generates: index, store, show, update, destroy
+   * Register resourceful routes for a controller (AdonisJS `resource`).
+   *
+   * Generates index / create / store / show / edit / update / destroy —
+   * `update` for both PUT and PATCH. Returns a {@link RouteResource} for
+   * fluent filtering: `.only()`, `.except()`, `.apiOnly()`, `.params()`,
+   * `.tap()`, `.where()`, `.use()`, `.as()`.
+   *
+   * Nested resources use dot-notation (`posts.comments` →
+   * `/posts/:post_id/comments/:id`).
    *
    * Usage:
    *   router.resource('posts', PostsController)
-   *   // GET    /posts          → PostsController.index
-   *   // POST   /posts          → PostsController.store
-   *   // GET    /posts/:id      → PostsController.show
-   *   // PUT    /posts/:id      → PostsController.update
-   *   // DELETE /posts/:id      → PostsController.destroy
+   *   router.resource('posts', PostsController).apiOnly()
    */
-  // biome-ignore lint/suspicious/noExplicitAny: see ControllerAction
-  resource(path: string, controller: new (...args: any[]) => any): GroupBuilder {
-    const baseName = path.replace(/\//g, '.')
-    const routes: RouteDefinition[] = []
-
-    const actions: Array<{ method: string; suffix: string; action: string; nameSuffix: string }> = [
-      { method: 'GET', suffix: '', action: 'index', nameSuffix: 'index' },
-      { method: 'POST', suffix: '', action: 'store', nameSuffix: 'store' },
-      { method: 'GET', suffix: '/:id', action: 'show', nameSuffix: 'show' },
-      { method: 'PUT', suffix: '/:id', action: 'update', nameSuffix: 'update' },
-      { method: 'PATCH', suffix: '/:id', action: 'update', nameSuffix: 'update' },
-      { method: 'DELETE', suffix: '/:id', action: 'destroy', nameSuffix: 'destroy' },
-    ]
-
-    for (const { method, suffix, action, nameSuffix } of actions) {
-      const def = this.#createDefinition(method, `/${path}${suffix}`, [controller, action])
-      def.name = `${baseName}.${nameSuffix}`
-      routes.push(def)
-      this.#routes.push(def)
-    }
-    this.#indexDirty = true
+  resource(path: string, controller: ControllerAction[0]): RouteResource {
+    return new RouteResource({
+      resource: path,
+      controller,
+      shallow: false,
+      register: (def) => {
+        this.#routes.push(def)
+        this.#indexDirty = true
+      },
+      markDirty: () => {
+        this.#indexDirty = true
+      },
+    })
+  }
 
-    return new GroupBuilder(routes)
+  /**
+   * Register a shallow resource (AdonisJS `shallowResource`). Member routes
+   * (show/edit/update/destroy) drop the parent prefix, since the record id
+   * alone identifies it: `posts.comments` → `/comments/:id` for members but
+   * `/posts/:post_id/comments` for the collection.
+   */
+  shallowResource(path: string, controller: ControllerAction[0]): RouteResource {
+    return new RouteResource({
+      resource: path,
+      controller,
+      shallow: true,
+      register: (def) => {
+        this.#routes.push(def)
+        this.#indexDirty = true
+      },
+      markDirty: () => {
+        this.#indexDirty = true
+      },
+    })
   }
 
   // ─── Groups ───────────────────────────────────────────────
@@ -508,8 +952,8 @@ export class Router {
   // ─── Global matchers ──────────────────────────────────────
 
   /** Set a global param matcher (applied to all routes). */
-  where(param: string, matcher: ParamMatcher | RegExp): this {
-    this.#globalMatchers[param] = matcher instanceof RegExp ? { pattern: matcher } : matcher
+  where(param: string, matcher: ParamMatcher | RegExp | string): this {
+    this.#globalMatchers[param] = compileMatcher(matcher)
     return this
   }
 
@@ -522,6 +966,20 @@ export class Router {
     this.#nameIndex.clear()
 
     for (const route of this.#routes) {
+      // Soft-deleted routes (resource .only()/.except()/.apiOnly()) never match.
+      if (route.deleted) continue
+      // Resolve a string handler reference against the controller registry.
+      if (route.stringRef && !route.lazyController) {
+        const loader = this.#controllers.get(route.stringRef.controller)
+        if (!loader) {
+          throw new Error(
+            `[E_UNREGISTERED_CONTROLLER] Route ${route.method} ${route.path} references ` +
+              `controller '${route.stringRef.controller}', which is not registered. Register it ` +
+              `with router.controllers({ ${route.stringRef.controller}: () => import('...') }).`,
+          )
+        }
+        route.lazyController = { loader, method: route.stringRef.method }
+      }
       // Named route index
       if (route.name) {
         this.#nameIndex.set(route.name, route)
@@ -647,6 +1105,33 @@ export class Router {
     return this.urlFor(name, params)
   }
 
+  /** @internal Inject the APP_KEY-backed signed-URL helper (wired by the Ignitor). */
+  setSignedUrl(signedUrl: SignedUrl): void {
+    this.#signedUrl = signedUrl
+  }
+
+  /**
+   * Generate a tamper-proof signed URL for a named route (AdonisJS
+   * `makeSignedUrl`). Delegates to the {@link SignedUrl} helper: appends an HMAC
+   * `signature`, plus a signed `expires` timestamp when `expiresIn` is given.
+   * Verified on the request side by `request.hasValidSignature()`.
+   *
+   * Requires an APP_KEY-backed signer (registered when `APP_KEY` is set).
+   */
+  makeSignedUrl(name: string, params?: Record<string, string>, options?: SignedUrlOptions): string {
+    if (!this.#signedUrl) {
+      throw new Error(
+        '[E_NO_APP_KEY] makeSignedUrl() requires an APP_KEY-backed signer. Set APP_KEY (>= 16 chars) so the encryption service is registered.',
+      )
+    }
+    const path = this.urlFor(name, params)
+    const withQs = options?.qs ? `${path}?${new URLSearchParams(options.qs).toString()}` : path
+    return this.#signedUrl.make(withQs, {
+      expiresIn: options?.expiresIn,
+      purpose: options?.purpose,
+    })
+  }
+
   /**
    * Map of every NAMED route's `name` → path pattern, e.g.
    * `{ 'users.show': '/users/:id' }`. Serialize this into a page so a
@@ -663,11 +1148,62 @@ export class Router {
     return manifest
   }
 
+  /**
+   * Generate a TypeScript source string typing every named route and its
+   * params (AdonisJS `generateTypes`) — a `RouteName` union plus a
+   * `RouteParams` map inferred from each pattern's `:param` segments. Write it
+   * to a `.d.ts` so `urlFor(name, params)` is type-checked. Returns the source;
+   * the caller decides where to persist it.
+   */
+  generateTypes(): string {
+    if (this.#indexDirty) this.#buildIndex()
+    const names = [...this.#nameIndex.keys()].sort()
+    if (names.length === 0) {
+      return 'export type RouteName = never\nexport interface RouteParams {}\n'
+    }
+    const union = names.map((name) => `  | ${JSON.stringify(name)}`).join('\n')
+    const entries = names.map((name) => {
+      const pattern = this.#nameIndex.get(name)?.path ?? ''
+      const params = [...pattern.matchAll(/:([A-Za-z_]\w*)(\??)/g)]
+      const shape =
+        params.length === 0
+          ? 'Record<string, never>'
+          : `{ ${params.map((m) => `${JSON.stringify(m[1])}${m[2] === '?' ? '?' : ''}: string`).join('; ')} }`
+      return `  ${JSON.stringify(name)}: ${shape}`
+    })
+    return `export type RouteName =\n${union}\n\nexport interface RouteParams {\n${entries.join('\n')}\n}\n`
+  }
+
+  // ─── Lookup ───────────────────────────────────────────────
+
+  /**
+   * Find a registered route by name or exact pattern (AdonisJS `router.find`).
+   * Returns null when nothing matches. Soft-deleted routes are ignored.
+   */
+  find(identifier: string): RouteDefinition | null {
+    if (this.#indexDirty) this.#buildIndex()
+    const byName = this.#nameIndex.get(identifier)
+    if (byName) return byName
+    return this.#routes.find((route) => !route.deleted && route.path === identifier) ?? null
+  }
+
+  /** Like {@link find} but throws when the route is absent (AdonisJS `findOrFail`). */
+  findOrFail(identifier: string): RouteDefinition {
+    const route = this.find(identifier)
+    if (!route) throw new Error(`Cannot find route for '${identifier}'`)
+    return route
+  }
+
+  /** True when a route with the given name or pattern exists (AdonisJS `router.has`). */
+  has(identifier: string): boolean {
+    return this.find(identifier) !== null
+  }
+
   // ─── Accessors ────────────────────────────────────────────
 
-  /** Get all registered routes (for OpenAPI generation, introspection). */
+  /** Get all registered (non-deleted) routes (for OpenAPI generation, introspection). */
   getRoutes(): RouteDefinition[] {
-    return [...this.#routes]
+    return this.#routes.filter((route) => !route.deleted)
   }
 
   /**
@@ -680,6 +1216,7 @@ export class Router {
     this.#routes = []
     this.#routerMiddleware = []
     this.#namedMiddleware.clear()
+    this.#controllers.clear()
     this.#globalMatchers = {}
     this.#indexDirty = true
   }
@@ -691,26 +1228,7 @@ export class Router {
   // ─── Internals ────────────────────────────────────────────
 
   #createDefinition(method: string, path: string, handler: RouteHandler): RouteDefinition {
-    const def: RouteDefinition = {
-      method: method.toUpperCase(),
-      path,
-      handler: null,
-      middleware: [],
-      inlineMiddleware: [],
-      guards: [],
-      roles: [],
-      permissions: [],
-      validators: [],
-      matchers: {},
-    }
-
-    if (Array.isArray(handler)) {
-      def.controller = { target: handler[0], method: handler[1] }
-    } else {
-      def.handler = handler
-    }
-
-    return def
+    return makeDefinition(method, path, handler)
   }
 
   #validateMatchers(