@shaferllc/keel 0.36.0 → 0.58.0

package/dist/core/database.js

@@ -65,10 +65,30 @@ export class QueryBuilder {
         this.wheres.push({ boolean: "AND", sql: `${column} IS NOT NULL`, bindings: [] });
         return this;
     }
+    whereNotIn(column, values) {
+        const marks = values.map(() => "?").join(", ");
+        this.wheres.push({ boolean: "AND", sql: `${column} NOT IN (${marks})`, bindings: values });
+        return this;
+    }
+    whereBetween(column, [min, max]) {
+        this.wheres.push({ boolean: "AND", sql: `${column} BETWEEN ? AND ?`, bindings: [min, max] });
+        return this;
+    }
+    whereLike(column, pattern) {
+        this.wheres.push({ boolean: "AND", sql: `${column} LIKE ?`, bindings: [pattern] });
+        return this;
+    }
     orderBy(column, direction = "asc") {
         this.orders.push(`${column} ${direction.toUpperCase()}`);
         return this;
     }
+    /** Newest-first / oldest-first by a timestamp column (default `created_at`). */
+    latest(column = "created_at") {
+        return this.orderBy(column, "desc");
+    }
+    oldest(column = "created_at") {
+        return this.orderBy(column, "asc");
+    }
     limit(n) {
         this._limit = n;
         return this;
@@ -94,7 +114,7 @@ export class QueryBuilder {
             sql += ` LIMIT ${this._limit}`;
         if (this._offset != null)
             sql += ` OFFSET ${this._offset}`;
-        return conn().select(placeholders(sql), where.bindings);
+        return (await conn().select(placeholders(sql), where.bindings));
     }
     async first() {
         this._limit = 1;
@@ -103,12 +123,55 @@ export class QueryBuilder {
     }
     async count() {
         const where = this.whereClause();
-        const rows = await conn().select(placeholders(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`), where.bindings);
+        const rows = (await conn().select(placeholders(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`), where.bindings));
         return Number(rows[0]?.count ?? 0);
     }
     async exists() {
         return (await this.count()) > 0;
     }
+    async aggregate(fn, column) {
+        const where = this.whereClause();
+        const rows = (await conn().select(placeholders(`SELECT ${fn}(${column}) AS agg FROM ${this.table}${where.sql}`), where.bindings));
+        return Number(rows[0]?.agg ?? 0);
+    }
+    sum(column) {
+        return this.aggregate("SUM", column);
+    }
+    avg(column) {
+        return this.aggregate("AVG", column);
+    }
+    min(column) {
+        return this.aggregate("MIN", column);
+    }
+    max(column) {
+        return this.aggregate("MAX", column);
+    }
+    /** The value of a single column from the first matching row (or null). */
+    async value(column) {
+        this.columns = column;
+        const row = await this.first();
+        return row ? row[column] : null;
+    }
+    /** An array of a single column across all matching rows. */
+    async pluck(column) {
+        this.columns = column;
+        const rows = await this.get();
+        return rows.map((row) => row[column]);
+    }
+    /** A page of results plus pagination metadata. */
+    async paginate(page = 1, perPage = 15) {
+        const total = await this.count();
+        this._limit = perPage;
+        this._offset = (Math.max(1, page) - 1) * perPage;
+        const data = await this.get();
+        return {
+            data,
+            total,
+            perPage,
+            currentPage: page,
+            lastPage: Math.max(1, Math.ceil(total / perPage)),
+        };
+    }
     /* ------------------------------- writes ------------------------------ */
     async insert(data) {
         const keys = Object.keys(data);

package/dist/core/decorators.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Request decorators — attach named, computed values to the current request,
+ * resolved lazily and memoized for the life of that request. Inspired by
+ * Fastify's `decorateRequest`, but without its footguns: you register a resolver
+ * once, and Keel computes it on first access and caches it per request (keyed off
+ * the Hono context via a WeakMap, so there's no shared-state leak between
+ * requests and no V8 shape deopt to design around).
+ *
+ *   decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
+ *
+ *   // anywhere in the request — computed once, then cached:
+ *   const user = await decorated<User>("user");
+ *
+ * (Decorating the *application* is already the service container's job —
+ * `bind` / `singleton` / `instance` / `make`, with `bound()` as `hasDecorator`.)
+ */
+import type { Context } from "hono";
+/** Resolves a decorator's value from the current request context. */
+export type RequestResolver<T = unknown> = (c: Context) => T | Promise<T>;
+/**
+ * Register a request decorator. Throws if `name` is already registered — a
+ * collision guard, like Fastify's.
+ */
+export declare function decorateRequest<T>(name: string, resolver: RequestResolver<T>): void;
+/** Whether a request decorator has been registered. */
+export declare function hasRequestDecorator(name: string): boolean;
+/**
+ * The value of a decorator for the current request — computed on first access
+ * via its resolver, then cached for the rest of the request. Always returns a
+ * promise (resolvers may be async).
+ */
+export declare function decorated<T = unknown>(name: string): Promise<T>;
+/**
+ * Imperatively set a decorator's value for the current request, overriding the
+ * resolver — e.g. from an auth middleware that already resolved the user.
+ */
+export declare function setRequestValue<T>(name: string, value: T): void;
+/** Clear all registered decorators (test helper). */
+export declare function clearRequestDecorators(): void;

package/dist/core/decorators.js

@@ -0,0 +1,72 @@
+/**
+ * Request decorators — attach named, computed values to the current request,
+ * resolved lazily and memoized for the life of that request. Inspired by
+ * Fastify's `decorateRequest`, but without its footguns: you register a resolver
+ * once, and Keel computes it on first access and caches it per request (keyed off
+ * the Hono context via a WeakMap, so there's no shared-state leak between
+ * requests and no V8 shape deopt to design around).
+ *
+ *   decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
+ *
+ *   // anywhere in the request — computed once, then cached:
+ *   const user = await decorated<User>("user");
+ *
+ * (Decorating the *application* is already the service container's job —
+ * `bind` / `singleton` / `instance` / `make`, with `bound()` as `hasDecorator`.)
+ */
+import { ctx } from "./request.js";
+const resolvers = new Map();
+// Per-request memo, keyed by the context object so it's GC'd with the request.
+const memo = new WeakMap();
+function bag(c) {
+    let b = memo.get(c);
+    if (!b) {
+        b = new Map();
+        memo.set(c, b);
+    }
+    return b;
+}
+/**
+ * Register a request decorator. Throws if `name` is already registered — a
+ * collision guard, like Fastify's.
+ */
+export function decorateRequest(name, resolver) {
+    if (resolvers.has(name)) {
+        throw new Error(`Request decorator "${name}" is already registered.`);
+    }
+    resolvers.set(name, resolver);
+}
+/** Whether a request decorator has been registered. */
+export function hasRequestDecorator(name) {
+    return resolvers.has(name);
+}
+/**
+ * The value of a decorator for the current request — computed on first access
+ * via its resolver, then cached for the rest of the request. Always returns a
+ * promise (resolvers may be async).
+ */
+export function decorated(name) {
+    const c = ctx();
+    const b = bag(c);
+    if (b.has(name))
+        return Promise.resolve(b.get(name));
+    const resolver = resolvers.get(name);
+    if (!resolver) {
+        throw new Error(`No request decorator "${name}". Register it with decorateRequest().`);
+    }
+    // Memoize the promise so concurrent access computes once.
+    const result = Promise.resolve(resolver(c));
+    b.set(name, result);
+    return result;
+}
+/**
+ * Imperatively set a decorator's value for the current request, overriding the
+ * resolver — e.g. from an auth middleware that already resolved the user.
+ */
+export function setRequestValue(name, value) {
+    bag(ctx()).set(name, value);
+}
+/** Clear all registered decorators (test helper). */
+export function clearRequestDecorators() {
+    resolvers.clear();
+}

package/dist/core/exceptions.d.ts

@@ -17,19 +17,90 @@ export declare class HttpException extends Error {
     readonly headers?: Record<string, string>;
     /** A machine-readable error code, e.g. "E_VALIDATION". */
     code?: string;
-    constructor(status: number, message?: string, headers?: Record<string, string>);
+    /** Structured context attached to the error; surfaced in the JSON body as `data`. */
+    data?: unknown;
+    constructor(status: number, message?: string, headers?: Record<string, string>, data?: unknown);
+    /**
+     * The error as a plain object, matching the JSON body the HTTP kernel renders:
+     * `{ error, status }` plus `code` and `data` when present. Subclasses that add
+     * fields (e.g. `ValidationException.errors`) override this to include them.
+     */
+    toJSON(): Record<string, unknown>;
 }
-export declare class NotFoundException extends HttpException {
-    constructor(message?: string);
+/** 400 — the request was malformed or failed validation. */
+export declare class BadRequestException extends HttpException {
+    constructor(message?: string, data?: unknown);
 }
 export declare class UnauthorizedException extends HttpException {
-    constructor(message?: string);
+    constructor(message?: string, data?: unknown);
+}
+/** 402 — payment is required to access the resource. */
+export declare class PaymentRequiredException extends HttpException {
+    constructor(message?: string, data?: unknown);
 }
 export declare class ForbiddenException extends HttpException {
-    constructor(message?: string);
+    constructor(message?: string, data?: unknown);
+}
+export declare class NotFoundException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 405 — the HTTP method isn't allowed for this resource. */
+export declare class MethodNotAllowedException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 406 — no representation matches the request's `Accept` header. */
+export declare class NotAcceptableException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 408 — the client took too long to send the request. */
+export declare class RequestTimeoutException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 409 — the request conflicts with the current state (e.g. a duplicate). */
+export declare class ConflictException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 411 — a `Content-Length` header is required and was missing. */
+export declare class LengthRequiredException extends HttpException {
+    constructor(message?: string, data?: unknown);
 }
-/** 422 with per-field messages. Pairs with a future validation layer. */
+/** 422 with per-field messages. Pairs with the validation layer. */
 export declare class ValidationException extends HttpException {
     readonly errors: Record<string, string[]>;
     constructor(errors: Record<string, string[]>, message?: string);
+    toJSON(): Record<string, unknown>;
 }
+/** 429 — the client has sent too many requests in a given window. */
+export declare class TooManyRequestsException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 500 — a catch-all server error you want to raise deliberately. */
+export declare class ServerErrorException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 501 — the requested functionality isn't implemented. */
+export declare class NotImplementedException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 502 — an upstream server returned an invalid response. */
+export declare class BadGatewayException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/** 503 — the service is temporarily unavailable (down, overloaded). */
+export declare class ServiceUnavailableException extends HttpException {
+    constructor(message?: string, data?: unknown);
+}
+/**
+ * Mint a reusable, coded `HttpException` subclass — the ergonomic way to define
+ * app-specific errors with a stable, machine-readable `code`. Inspired by
+ * `@fastify/error`. The `message` may carry `%s` placeholders, filled in order
+ * from the constructor arguments.
+ *
+ *   const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
+ *   throw new InsufficientFunds("$40");
+ *   // → 402  { error: "Balance too low: need $40", status: 402, code: "E_FUNDS" }
+ *
+ * The returned class extends `HttpException`, so it renders through the same
+ * path — `code` lands in the JSON body — and passes `instanceof HttpException`.
+ */
+export declare function createError(code: string, message: string, status?: number): new (...args: (string | number)[]) => HttpException;

package/dist/core/exceptions.js

@@ -6,14 +6,20 @@
 export const STATUS_TEXT = {
     400: "Bad Request",
     401: "Unauthorized",
+    402: "Payment Required",
     403: "Forbidden",
     404: "Not Found",
     405: "Method Not Allowed",
+    406: "Not Acceptable",
+    408: "Request Timeout",
     409: "Conflict",
+    411: "Length Required",
     419: "Page Expired",
     422: "Unprocessable Entity",
     429: "Too Many Requests",
     500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
     503: "Service Unavailable",
 };
 /**
@@ -29,37 +35,189 @@ export class HttpException extends Error {
     headers;
     /** A machine-readable error code, e.g. "E_VALIDATION". */
     code;
-    constructor(status, message, headers) {
+    /** Structured context attached to the error; surfaced in the JSON body as `data`. */
+    data;
+    constructor(status, message, headers, data) {
         super(message ?? STATUS_TEXT[status] ?? "Error");
         this.name = "HttpException";
         this.status = status;
         this.headers = headers;
+        this.data = data;
+    }
+    /**
+     * The error as a plain object, matching the JSON body the HTTP kernel renders:
+     * `{ error, status }` plus `code` and `data` when present. Subclasses that add
+     * fields (e.g. `ValidationException.errors`) override this to include them.
+     */
+    toJSON() {
+        const body = { error: this.message, status: this.status };
+        if (this.code)
+            body.code = this.code;
+        if (this.data !== undefined)
+            body.data = this.data;
+        return body;
     }
 }
-export class NotFoundException extends HttpException {
-    constructor(message = "Not Found") {
-        super(404, message);
-        this.name = "NotFoundException";
+/*
+ * The standard HTTP error family. Each carries a fixed status and a stable
+ * `code`, and takes an optional `data` bag that lands in the JSON body. Throw
+ * any of them from a handler, middleware, or service to short-circuit with the
+ * right status. Ordered by status code.
+ */
+/** 400 — the request was malformed or failed validation. */
+export class BadRequestException extends HttpException {
+    constructor(message = "Bad Request", data) {
+        super(400, message, undefined, data);
+        this.name = "BadRequestException";
+        this.code = "E_BAD_REQUEST";
     }
 }
 export class UnauthorizedException extends HttpException {
-    constructor(message = "Unauthorized") {
-        super(401, message);
+    constructor(message = "Unauthorized", data) {
+        super(401, message, undefined, data);
         this.name = "UnauthorizedException";
+        this.code = "E_UNAUTHORIZED";
+    }
+}
+/** 402 — payment is required to access the resource. */
+export class PaymentRequiredException extends HttpException {
+    constructor(message = "Payment Required", data) {
+        super(402, message, undefined, data);
+        this.name = "PaymentRequiredException";
+        this.code = "E_PAYMENT_REQUIRED";
     }
 }
 export class ForbiddenException extends HttpException {
-    constructor(message = "Forbidden") {
-        super(403, message);
+    constructor(message = "Forbidden", data) {
+        super(403, message, undefined, data);
         this.name = "ForbiddenException";
+        this.code = "E_FORBIDDEN";
+    }
+}
+export class NotFoundException extends HttpException {
+    constructor(message = "Not Found", data) {
+        super(404, message, undefined, data);
+        this.name = "NotFoundException";
+        this.code = "E_NOT_FOUND";
     }
 }
-/** 422 with per-field messages. Pairs with a future validation layer. */
+/** 405 — the HTTP method isn't allowed for this resource. */
+export class MethodNotAllowedException extends HttpException {
+    constructor(message = "Method Not Allowed", data) {
+        super(405, message, undefined, data);
+        this.name = "MethodNotAllowedException";
+        this.code = "E_METHOD_NOT_ALLOWED";
+    }
+}
+/** 406 — no representation matches the request's `Accept` header. */
+export class NotAcceptableException extends HttpException {
+    constructor(message = "Not Acceptable", data) {
+        super(406, message, undefined, data);
+        this.name = "NotAcceptableException";
+        this.code = "E_NOT_ACCEPTABLE";
+    }
+}
+/** 408 — the client took too long to send the request. */
+export class RequestTimeoutException extends HttpException {
+    constructor(message = "Request Timeout", data) {
+        super(408, message, undefined, data);
+        this.name = "RequestTimeoutException";
+        this.code = "E_REQUEST_TIMEOUT";
+    }
+}
+/** 409 — the request conflicts with the current state (e.g. a duplicate). */
+export class ConflictException extends HttpException {
+    constructor(message = "Conflict", data) {
+        super(409, message, undefined, data);
+        this.name = "ConflictException";
+        this.code = "E_CONFLICT";
+    }
+}
+/** 411 — a `Content-Length` header is required and was missing. */
+export class LengthRequiredException extends HttpException {
+    constructor(message = "Length Required", data) {
+        super(411, message, undefined, data);
+        this.name = "LengthRequiredException";
+        this.code = "E_LENGTH_REQUIRED";
+    }
+}
+/** 422 with per-field messages. Pairs with the validation layer. */
 export class ValidationException extends HttpException {
     errors;
     constructor(errors, message = "The given data was invalid.") {
         super(422, message);
         this.name = "ValidationException";
+        this.code = "E_VALIDATION";
         this.errors = errors;
     }
+    toJSON() {
+        return { ...super.toJSON(), errors: this.errors };
+    }
+}
+/** 429 — the client has sent too many requests in a given window. */
+export class TooManyRequestsException extends HttpException {
+    constructor(message = "Too Many Requests", data) {
+        super(429, message, undefined, data);
+        this.name = "TooManyRequestsException";
+        this.code = "E_TOO_MANY_REQUESTS";
+    }
+}
+/** 500 — a catch-all server error you want to raise deliberately. */
+export class ServerErrorException extends HttpException {
+    constructor(message = "Internal Server Error", data) {
+        super(500, message, undefined, data);
+        this.name = "ServerErrorException";
+        this.code = "E_SERVER_ERROR";
+    }
+}
+/** 501 — the requested functionality isn't implemented. */
+export class NotImplementedException extends HttpException {
+    constructor(message = "Not Implemented", data) {
+        super(501, message, undefined, data);
+        this.name = "NotImplementedException";
+        this.code = "E_NOT_IMPLEMENTED";
+    }
+}
+/** 502 — an upstream server returned an invalid response. */
+export class BadGatewayException extends HttpException {
+    constructor(message = "Bad Gateway", data) {
+        super(502, message, undefined, data);
+        this.name = "BadGatewayException";
+        this.code = "E_BAD_GATEWAY";
+    }
+}
+/** 503 — the service is temporarily unavailable (down, overloaded). */
+export class ServiceUnavailableException extends HttpException {
+    constructor(message = "Service Unavailable", data) {
+        super(503, message, undefined, data);
+        this.name = "ServiceUnavailableException";
+        this.code = "E_SERVICE_UNAVAILABLE";
+    }
+}
+/**
+ * Mint a reusable, coded `HttpException` subclass — the ergonomic way to define
+ * app-specific errors with a stable, machine-readable `code`. Inspired by
+ * `@fastify/error`. The `message` may carry `%s` placeholders, filled in order
+ * from the constructor arguments.
+ *
+ *   const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
+ *   throw new InsufficientFunds("$40");
+ *   // → 402  { error: "Balance too low: need $40", status: 402, code: "E_FUNDS" }
+ *
+ * The returned class extends `HttpException`, so it renders through the same
+ * path — `code` lands in the JSON body — and passes `instanceof HttpException`.
+ */
+export function createError(code, message, status = 500) {
+    return class extends HttpException {
+        constructor(...args) {
+            super(status, formatMessage(message, args));
+            this.name = code;
+            this.code = code;
+        }
+    };
+}
+/** printf-lite: replace each `%s` with the next argument, in order. */
+function formatMessage(template, args) {
+    let index = 0;
+    return template.replace(/%s/g, () => (index < args.length ? String(args[index++]) : "%s"));
 }

package/dist/core/helpers.d.ts

@@ -17,6 +17,12 @@ import { Logger } from "./logger.js";
 export declare function setApplication(app: Application): void;
 /** The active application container. Throws if none has been created. */
 export declare function app(): Application;
+/** Run a callback once the active application has booted (see `Application.onReady`). */
+export declare function onReady(hook: (app: Application) => void | Promise<void>): void;
+/** Register a graceful-shutdown hook on the active application (see `Application.onShutdown`). */
+export declare function onShutdown(hook: (app: Application) => void | Promise<void>): void;
+/** Gracefully terminate the active application, running its shutdown hooks. */
+export declare function terminate(): Promise<void>;
 /**
  * Read configuration with dot notation: `config('app.name')`, or with a
  * fallback: `config('app.port', 3000)`.

package/dist/core/helpers.js

@@ -24,6 +24,18 @@ export function app() {
     }
     return current;
 }
+/** Run a callback once the active application has booted (see `Application.onReady`). */
+export function onReady(hook) {
+    app().onReady(hook);
+}
+/** Register a graceful-shutdown hook on the active application (see `Application.onShutdown`). */
+export function onShutdown(hook) {
+    app().onShutdown(hook);
+}
+/** Gracefully terminate the active application, running its shutdown hooks. */
+export function terminate() {
+    return app().terminate();
+}
 /**
  * Read configuration with dot notation: `config('app.name')`, or with a
  * fallback: `config('app.port', 3000)`.

package/dist/core/http/kernel.js

@@ -101,8 +101,18 @@ export class HttpKernel {
         }
         for (const route of routes) {
             const fn = router.resolve(route.handler);
+            // Set the matched-route context *before* this route's middleware, so both
+            // route middleware and the handler can read `request.route` (incl. config).
+            const setRoute = async (c, next) => {
+                c.set("route", {
+                    name: route.name,
+                    pattern: route.path,
+                    methods: route.methods,
+                    config: route.config,
+                });
+                await next();
+            };
             const honoHandler = async (c) => {
-                c.set("route", { name: route.name, pattern: route.path, methods: route.methods });
                 const result = await fn(c);
                 return typeof result === "string" ? c.html(result) : result;
             };
@@ -111,7 +121,7 @@ export class HttpKernel {
             for (const [param, rgx] of Object.entries(route.wheres)) {
                 path = path.replace(new RegExp(`:${param}(\\??)`), `:${param}{${rgx}}$1`);
             }
-            const middleware = route.middleware.map((m) => router.resolveMiddleware(m));
+            const middleware = [setRoute, ...route.middleware.map((m) => router.resolveMiddleware(m))];
             hono.on(route.methods, [path], ...middleware, honoHandler);
         }
         hono.notFound((c) => this.handle(new NotFoundException(`No route for ${c.req.method} ${c.req.path}`), c));
@@ -159,6 +169,8 @@ export class HttpKernel {
         const body = { error: message, status };
         if (isHttp && err.code)
             body.code = err.code;
+        if (isHttp && err.data !== undefined)
+            body.data = err.data;
         if (err instanceof ValidationException)
             body.errors = err.errors;
         if (debug && !isHttp && err instanceof Error) {

package/dist/core/http/router.d.ts

@@ -53,6 +53,8 @@ export interface RouteDefinition {
     wheres: Record<string, string>;
     /** Host pattern this route is bound to, e.g. ":tenant.example.com". */
     domain?: string;
+    /** Arbitrary per-route metadata, readable in the handler via `request.route.config`. */
+    config: Record<string, unknown>;
 }
 /** A single registered route — chain to name it, guard it, or constrain params. */
 export declare class Route {
@@ -70,6 +72,8 @@ export declare class Route {
     where(param: string, matcher: Matcher): this;
     /** Bind this route to a host pattern (supports `:subdomain` segments). */
     domain(pattern: string): this;
+    /** Attach arbitrary metadata to the route — read it via `request.route.config`. */
+    config(data: Record<string, unknown>): this;
 }
 /** A group of routes sharing a prefix, middleware, and/or name prefix. */
 export declare class RouteGroup {
@@ -79,6 +83,8 @@ export declare class RouteGroup {
     middleware(mw: MiddlewareRef | MiddlewareRef[]): this;
     /** Alias for middleware(), matching AdonisJS. */
     use(mw: MiddlewareRef | MiddlewareRef[]): this;
+    /** Attach metadata to every route in the group (a route's own config wins). */
+    config(data: Record<string, unknown>): this;
     /** Constrain a parameter across every route in the group. */
     where(param: string, matcher: Matcher): this;
     as(namePrefix: string): this;
@@ -165,6 +171,14 @@ export declare class Router {
      */
     resource(name: string, controller: ControllerRef): RouteResource;
     private add;
+    private routeHooks;
+    /**
+     * Observe route registration — called with each route's definition as it's
+     * added (and replayed for routes already registered). Handy for logging or
+     * building an API map. The `def` is live, so reading it later reflects fluent
+     * config (`.name()`, `.middleware()`) applied after registration.
+     */
+    onRoute(hook: (def: RouteDefinition) => void): this;
     /** Register a global parameter constraint, applied to every matching route. */
     where(param: string, matcher: Matcher): this;
     /** All registered routes (excluding those trimmed to zero methods). */