@c9up/ream 0.1.25 → 0.1.26

package/dist/router/Router.js

@@ -4,7 +4,54 @@
  * @implements FR24, FR25, FR26, FR27, FR28
  */
 import { safeDecodeURIComponent } from '../http/urlDecode.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';
+/**
+ * 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) {
+    return !('prototype' in first);
+}
+/** Build a route definition from a method, path, and handler. */
+function makeDefinition(method, path, handler) {
+    const def = {
+        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;
+}
 // ─── Matchers ───────────────────────────────────────────────
 export const matchers = {
     /** Match numeric params only. */
@@ -20,47 +67,91 @@ export const matchers = {
         return { pattern: /^[a-z0-9]+(?:-[a-z0-9]+)*$/ };
     },
 };
+/**
+ * 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) {
+    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;
-    constructor(route) {
-        this.#route = route;
+/**
+ * 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;
+    constructor(routes) {
+        super();
+        this.#routes = Array.isArray(routes) ? routes : [routes];
+    }
+    /** Apply `fn` to every backing definition, returning `this` for chaining. */
+    #each(fn) {
+        for (const route of this.#routes)
+            fn(route);
+        return this;
+    }
+    /** The primary definition — accessors read from it (all verbs share pattern/name). */
+    #primary() {
+        return this.#routes[0];
     }
     /** Name this route (for URL generation and redirects). */
     as(name) {
-        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) {
+        return this.#each((route) => {
+            route.path = prefix + route.path;
+        });
     }
     /** Add named middleware. */
     middleware(...names) {
-        this.#route.middleware.push(...names);
-        return this;
+        return this.#each((route) => {
+            route.middleware.push(...names);
+        });
     }
     /** Add inline middleware functions. */
     use(...mw) {
-        this.#route.inlineMiddleware.push(...mw);
-        return this;
+        return this.#each((route) => {
+            route.inlineMiddleware.push(...mw);
+        });
     }
     /** Add authentication guards. */
     guard(...guards) {
-        this.#route.guards.push(...guards);
-        return this;
+        return this.#each((route) => {
+            route.guards.push(...guards);
+        });
     }
     /** Require specific roles. */
     role(...roles) {
-        this.#route.roles.push(...roles);
-        return this;
+        return this.#each((route) => {
+            route.roles.push(...roles);
+        });
     }
     /** Require specific permissions. */
     permission(...permissions) {
-        this.#route.permissions.push(...permissions);
-        return this;
+        return this.#each((route) => {
+            route.permissions.push(...permissions);
+        });
     }
-    /** Add a param constraint. */
+    /** Add a param constraint — RegExp, predefined matcher, or a string pattern. */
     where(param, matcher) {
-        this.#route.matchers[param] = matcher instanceof RegExp ? { pattern: matcher } : matcher;
-        return this;
+        const compiled = compileMatcher(matcher);
+        return this.#each((route) => {
+            route.matchers[param] = compiled;
+        });
     }
     /**
      * Validate the request body against a named validator. At request time the
@@ -78,34 +169,63 @@ export class RouteBuilder {
      * An unregistered name is a hard error — validation is never silently skipped.
      */
     validate(validator) {
-        this.#route.validators.push(validator);
-        return this;
+        return this.#each((route) => {
+            route.validators.push(validator);
+        });
     }
     /** Set API version. */
     version(v) {
-        this.#route.version = v;
-        return this;
+        return this.#each((route) => {
+            route.version = v;
+        });
     }
     /** Restrict to a specific domain. */
     domain(d) {
-        this.#route.domain = d;
-        return this;
+        return this.#each((route) => {
+            route.domain = d;
+        });
     }
     /** Mark as deprecated. */
     deprecates(version, options) {
-        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() {
+        return this.#primary().name;
+    }
+    /** The route's URL pattern (AdonisJS `route.getPattern`). */
+    getPattern() {
+        return this.#primary().path;
     }
-    /** @internal Get the underlying definition. */
+    /** Replace the route's URL pattern (AdonisJS `route.setPattern`). */
+    setPattern(pattern) {
+        return this.#each((route) => {
+            route.path = pattern;
+        });
+    }
+    /** Soft-delete this route so it stops matching (AdonisJS `route.markAsDeleted`). */
+    markAsDeleted() {
+        return this.#each((route) => {
+            route.deleted = true;
+        });
+    }
+    /** True when the route has been soft-deleted (AdonisJS `route.isDeleted`). */
+    isDeleted() {
+        return this.#primary().deleted === true;
+    }
+    /** @internal Get the underlying (primary) definition. */
     getDefinition() {
-        return this.#route;
+        return this.#primary();
     }
 }
 // ─── GroupBuilder ───────────────────────────────────────────
 /** Fluent group builder — returned by router.group(callback). */
-export class GroupBuilder {
+export class GroupBuilder extends Macroable {
     #routes;
     constructor(routes) {
+        super();
         this.#routes = routes;
     }
     /** Set URL prefix for all routes in the group. */
@@ -136,12 +256,17 @@ 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) {
         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;
     }
@@ -154,7 +279,7 @@ export class GroupBuilder {
     }
     /** Add param matcher to all routes in the group. */
     where(param, matcher) {
-        const m = matcher instanceof RegExp ? { pattern: matcher } : matcher;
+        const m = compileMatcher(matcher);
         for (const route of this.#routes) {
             if (!(param in route.matchers)) {
                 route.matchers[param] = m;
@@ -163,6 +288,172 @@ export class GroupBuilder {
         return this;
     }
 }
+/**
+ * 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;
+    #controller;
+    #shallow;
+    #register;
+    #markDirty;
+    /** Resource name → param placeholder (`comments` → `:id`, `posts` → `:post_id`). */
+    #params = {};
+    #baseName;
+    /** The generated routes, in declaration order (AdonisJS `resource.routes`). */
+    routes = [];
+    constructor(options) {
+        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, method, action) {
+        const def = makeDefinition(method, `/${pattern}`, [this.#controller, action]);
+        def.name = `${this.#baseName}.${action}`;
+        this.#register(def);
+        this.routes.push(new RouteBuilder(def));
+    }
+    #buildRoutes() {
+        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) {
+        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) {
+        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) {
+        for (const route of this.#matching(names))
+            route.markAsDeleted();
+        this.#markDirty();
+        return this;
+    }
+    /** Drop the form-rendering `create` + `edit` actions (AdonisJS `apiOnly`). */
+    apiOnly() {
+        return this.except(['create', 'edit']);
+    }
+    /** Constrain a param across every action route (AdonisJS `resource.where`). */
+    where(key, matcher) {
+        for (const route of this.routes)
+            route.where(key, matcher);
+        return this;
+    }
+    tap(actionsOrCallback, callback) {
+        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) {
+        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, middleware) {
+        const list = Array.isArray(middleware) ? middleware : [middleware];
+        const apply = (route) => {
+            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, middleware) {
+        return this.use(actions, middleware);
+    }
+    /**
+     * Rename the base of every route name (AdonisJS `as`). `normalizeName`
+     * snake_cases the new base by default.
+     */
+    as(name, normalizeName = true) {
+        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;
+    }
+}
 function isViewEngine(value) {
     return (value !== null &&
         typeof value === 'object' &&
@@ -170,7 +461,7 @@ function isViewEngine(value) {
         typeof value.render === 'function');
 }
 // ─── 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;
     #path;
@@ -190,26 +481,34 @@ export class OnRouteBuilder {
             ctx.response.type('text/html; charset=utf-8').send(html);
         });
     }
-    /** Redirect to a path. */
-    redirect(target, status = 302) {
+    /**
+     * 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, params, status = 302) {
         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, params, status = 302) {
+    /** Redirect to a fixed path/URL (AdonisJS brisk `redirectToPath`). */
+    redirectToPath(target, status = 302) {
         return this.#router.get(this.#path, async (ctx) => {
-            ctx.response.redirect().status(status).toRoute(name, params);
+            ctx.response.redirect().status(status).toPath(target);
         });
     }
 }
 // ─── Router ─────────────────────────────────────────────────
 /** Main Router. */
-export class Router {
+export class Router extends Macroable {
     #routes = [];
     #globalMatchers = {};
     #routerMiddleware = [];
     #namedMiddleware = new Map();
+    /** Controller registry: name → lazy import, for string handler references. */
+    #controllers = new Map();
+    /** APP_KEY-backed signed-URL helper (injected by the Ignitor when set). */
+    #signedUrl;
     /** Index: static routes by "METHOD:path" for O(1) exact match. */
     #staticIndex = new Map();
     /** Index: parametric routes grouped by method. */
@@ -232,19 +531,46 @@ export class Router {
         return this;
     }
     /**
-     * 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) {
-        const resolved = {};
+        const factories = {};
         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 resolved;
+        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) {
+        for (const [name, loader] of Object.entries(map)) {
+            this.#controllers.set(name, loader);
+        }
+        this.#indexDirty = true;
+        return this;
     }
     /** Get the router-level middleware stack. */
     getRouterMiddleware() {
@@ -255,12 +581,20 @@ export class Router {
         return this.#namedMiddleware.get(name);
     }
     // ─── Route registration ───────────────────────────────────
-    /** Register a route with any HTTP method. */
+    /**
+     * 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, path, handler) {
-        const def = this.#createDefinition(method, path, handler);
-        this.#routes.push(def);
+        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, handler) {
         return this.route('GET', path, handler);
@@ -289,37 +623,53 @@ 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, controller) {
-        const baseName = path.replace(/\//g, '.');
-        const routes = [];
-        const actions = [
-            { 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;
-        return new GroupBuilder(routes);
+        return new RouteResource({
+            resource: path,
+            controller,
+            shallow: false,
+            register: (def) => {
+                this.#routes.push(def);
+                this.#indexDirty = true;
+            },
+            markDirty: () => {
+                this.#indexDirty = true;
+            },
+        });
+    }
+    /**
+     * 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, controller) {
+        return new RouteResource({
+            resource: path,
+            controller,
+            shallow: true,
+            register: (def) => {
+                this.#routes.push(def);
+                this.#indexDirty = true;
+            },
+            markDirty: () => {
+                this.#indexDirty = true;
+            },
+        });
     }
     group(callbackOrConfig, legacyCallback) {
         if (typeof callbackOrConfig === 'function') {
@@ -353,7 +703,7 @@ export class Router {
     // ─── Global matchers ──────────────────────────────────────
     /** Set a global param matcher (applied to all routes). */
     where(param, matcher) {
-        this.#globalMatchers[param] = matcher instanceof RegExp ? { pattern: matcher } : matcher;
+        this.#globalMatchers[param] = compileMatcher(matcher);
         return this;
     }
     // ─── Route matching ───────────────────────────────────────
@@ -363,6 +713,19 @@ export class Router {
         this.#paramIndex.clear();
         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);
@@ -474,6 +837,29 @@ export class Router {
     makeUrl(name, params) {
         return this.urlFor(name, params);
     }
+    /** @internal Inject the APP_KEY-backed signed-URL helper (wired by the Ignitor). */
+    setSignedUrl(signedUrl) {
+        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, params, options) {
+        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
@@ -490,10 +876,59 @@ 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() {
+        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) {
+        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) {
+        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) {
+        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() {
-        return [...this.#routes];
+        return this.#routes.filter((route) => !route.deleted);
     }
     /**
      * Clear all registered routes AND registries (used by hot-reload). Router
@@ -505,6 +940,7 @@ export class Router {
         this.#routes = [];
         this.#routerMiddleware = [];
         this.#namedMiddleware.clear();
+        this.#controllers.clear();
         this.#globalMatchers = {};
         this.#indexDirty = true;
     }
@@ -513,25 +949,7 @@ export class Router {
     }
     // ─── Internals ────────────────────────────────────────────
     #createDefinition(method, path, handler) {
-        const def = {
-            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(params, matcherMap) {
         for (const [param, value] of Object.entries(params)) {