@c9up/ream 0.1.3

package/dist/openapi/OpenApiMiddleware.d.ts

@@ -0,0 +1,24 @@
+/**
+ * OpenApiMiddleware — serves the OpenAPI spec and Swagger UI.
+ *
+ * GET /api-docs → JSON spec
+ * GET /docs → Swagger UI (HTML)
+ */
+import type { HttpContext } from '../http/HttpContext.js';
+export interface OpenApiMiddlewareConfig {
+    specPath?: string;
+    docsPath?: string;
+    /**
+     * The OpenAPI spec, or a factory that builds it lazily on first request.
+     * Pass a factory when the spec depends on routes registered AFTER this
+     * middleware is mounted (the common case — `OpenApiProvider` passes
+     * `() => generator.generate()`). The result is memoised after the first hit.
+     */
+    spec: Record<string, unknown> | (() => Record<string, unknown>);
+}
+export declare class OpenApiMiddleware {
+    #private;
+    constructor(config: OpenApiMiddlewareConfig);
+    handle(ctx: HttpContext, next: () => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=OpenApiMiddleware.d.ts.map

package/dist/openapi/OpenApiMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiMiddleware.d.ts","sourceRoot":"","sources":["../../src/openapi/OpenApiMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAEzD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAChE;AAUD,qBAAa,iBAAiB;;gBAQhB,MAAM,EAAE,uBAAuB;IAsBrC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAyCzE"}

package/dist/openapi/OpenApiMiddleware.js

@@ -0,0 +1,78 @@
+/**
+ * OpenApiMiddleware — serves the OpenAPI spec and Swagger UI.
+ *
+ * GET /api-docs → JSON spec
+ * GET /docs → Swagger UI (HTML)
+ */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+export class OpenApiMiddleware {
+    #specPath;
+    #docsPath;
+    #specSource;
+    #specJson;
+    #safeTitle;
+    #safeSpecPathJs;
+    constructor(config) {
+        this.#specPath = config.specPath ?? '/api-docs';
+        this.#docsPath = config.docsPath ?? '/docs';
+        this.#specSource = config.spec;
+        this.#safeSpecPathJs = JSON.stringify(this.#specPath); // JS string literal — safe in <script>
+    }
+    /** Resolve (and memoise) the spec JSON + escaped title on first use. */
+    #resolveSpec() {
+        if (this.#specJson === undefined || this.#safeTitle === undefined) {
+            const spec = typeof this.#specSource === 'function' ? this.#specSource() : this.#specSource;
+            this.#specJson = JSON.stringify(spec);
+            const specInfo = spec.info;
+            const rawTitle = typeof specInfo === 'object' && specInfo !== null && 'title' in specInfo
+                ? specInfo.title
+                : undefined;
+            this.#safeTitle = escapeHtml(typeof rawTitle === 'string' ? rawTitle : 'API Docs');
+        }
+        return { json: this.#specJson, safeTitle: this.#safeTitle };
+    }
+    async handle(ctx, next) {
+        const path = ctx.request.path();
+        if (path === this.#specPath && ctx.request.method() === 'GET') {
+            ctx.response.header('Content-Type', 'application/json');
+            ctx.response.status(200).send(this.#resolveSpec().json);
+            return;
+        }
+        if (path === this.#docsPath && ctx.request.method() === 'GET') {
+            ctx.response.header('Content-Type', 'text/html');
+            ctx.response.status(200).send(this.#renderSwaggerUi());
+            return;
+        }
+        return next();
+    }
+    #renderSwaggerUi() {
+        const { safeTitle } = this.#resolveSpec();
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>${safeTitle}</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: ${this.#safeSpecPathJs},
+      dom_id: '#swagger-ui',
+      presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+      layout: 'BaseLayout',
+    })
+  </script>
+</body>
+</html>`;
+    }
+}
+//# sourceMappingURL=OpenApiMiddleware.js.map

package/dist/openapi/OpenApiMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiMiddleware.js","sourceRoot":"","sources":["../../src/openapi/OpenApiMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/openapi/OpenApiProvider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `OpenApiProvider` — serves an auto-generated OpenAPI 3.1 spec + Swagger UI.
+ *
+ * `boot()` mounts a global middleware that, on the first GET to `/api-docs`
+ * (JSON) or `/docs` (Swagger UI), lazily generates the spec from the router's
+ * registered routes — so every route registered during boot/start is included
+ * (the spec must NOT be generated eagerly at boot, before other providers have
+ * registered their routes). Opt-out via `config.openapi.enabled = false`.
+ *
+ * @implements Story 24.4
+ */
+import type { AppContext } from '../Provider.js';
+import { Provider } from '../Provider.js';
+import { OpenApiGenerator } from './OpenApiGenerator.js';
+export interface OpenApiDocsConfig {
+    /** Disable the docs endpoints entirely. Default: enabled. */
+    enabled?: boolean;
+    /** Spec `info.title`. Default `'API'`. */
+    title?: string;
+    /** Spec `info.version`. Default `'1.0.0'`. */
+    version?: string;
+    /** Path serving the JSON spec. Default `/api-docs`. */
+    specPath?: string;
+    /** Path serving the Swagger UI. Default `/docs`. */
+    docsPath?: string;
+}
+export interface OpenApiProviderOptions {
+    /** Override the generator — used by tests. */
+    generator?: OpenApiGenerator;
+}
+export declare class OpenApiProvider extends Provider {
+    #private;
+    constructor(app: AppContext, options?: OpenApiProviderOptions);
+    boot(): Promise<void>;
+}
+//# sourceMappingURL=OpenApiProvider.d.ts.map

package/dist/openapi/OpenApiProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiProvider.d.ts","sourceRoot":"","sources":["../../src/openapi/OpenApiProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAGxD,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B;AAED,qBAAa,eAAgB,SAAQ,QAAQ;;gBAG/B,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B;IAKlD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAqBrC"}

package/dist/openapi/OpenApiProvider.js

@@ -0,0 +1,42 @@
+/**
+ * `OpenApiProvider` — serves an auto-generated OpenAPI 3.1 spec + Swagger UI.
+ *
+ * `boot()` mounts a global middleware that, on the first GET to `/api-docs`
+ * (JSON) or `/docs` (Swagger UI), lazily generates the spec from the router's
+ * registered routes — so every route registered during boot/start is included
+ * (the spec must NOT be generated eagerly at boot, before other providers have
+ * registered their routes). Opt-out via `config.openapi.enabled = false`.
+ *
+ * @implements Story 24.4
+ */
+import { Provider } from '../Provider.js';
+import { OpenApiGenerator } from './OpenApiGenerator.js';
+import { OpenApiMiddleware } from './OpenApiMiddleware.js';
+export class OpenApiProvider extends Provider {
+    #override;
+    constructor(app, options = {}) {
+        super(app);
+        this.#override = options.generator;
+    }
+    async boot() {
+        const config = this.app.config.get('openapi') ?? {};
+        if (config.enabled === false)
+            return;
+        const generator = this.#override ?? this.#buildGenerator(config);
+        const server = this.app.container.make('server');
+        const middleware = new OpenApiMiddleware({
+            specPath: config.specPath,
+            docsPath: config.docsPath,
+            spec: () => generator.generate(),
+        });
+        server.use([(ctx, next) => middleware.handle(ctx, next)]);
+    }
+    #buildGenerator(config) {
+        const router = this.app.container.make('router');
+        return new OpenApiGenerator(router, {
+            title: config.title ?? 'API',
+            version: config.version ?? '1.0.0',
+        });
+    }
+}
+//# sourceMappingURL=OpenApiProvider.js.map

package/dist/openapi/OpenApiProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiProvider.js","sourceRoot":"","sources":["../../src/openapi/OpenApiProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAoB1D,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAClC,SAAS,CAAmB;IAErC,YAAY,GAAe,EAAE,UAAkC,EAAE;QAC/D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;IACpC,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAoB,SAAS,CAAC,IAAI,EAAE,CAAA;QACtE,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK;YAAE,OAAM;QAEpC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAA;QAChE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QACxD,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC;YACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE;SACjC,CAAC,CAAA;QACF,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAC3D,CAAC;IAED,eAAe,CAAC,MAAyB;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QACxD,OAAO,IAAI,gBAAgB,CAAC,MAAM,EAAE;YAClC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;YAC5B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;SACnC,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/resources/ApiResource.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ApiResource — transform entities into API responses.
+ *
+ * Controls which fields are exposed, how relationships are serialized,
+ * and provides pagination metadata.
+ *
+ * Usage:
+ *   class UserResource extends ApiResource<User> {
+ *     serialize(user: User) {
+ *       return { id: user.id, email: user.email, name: user.name }
+ *     }
+ *   }
+ *
+ *   ctx.response.json(new UserResource().item(user))
+ *   ctx.response.json(new UserResource().collection(users, { page: 1, perPage: 20, total: 100 }))
+ *
+ * @implements MISS-23
+ */
+export interface PaginationMeta {
+    page: number;
+    perPage: number;
+    total: number;
+    lastPage: number;
+    hasMore: boolean;
+}
+export declare abstract class ApiResource<T> {
+    /** Transform a single entity into its API representation. */
+    abstract serialize(item: T): Record<string, unknown>;
+    /** Transform a single item with wrapper. */
+    item(entity: T): {
+        data: Record<string, unknown>;
+    };
+    /** Transform a collection with optional pagination. */
+    collection(entities: T[], pagination?: {
+        page: number;
+        perPage: number;
+        total: number;
+    }): {
+        data: Record<string, unknown>[];
+        meta?: PaginationMeta;
+    };
+    /** Transform with relationships loaded via a callback. */
+    with<R>(entity: T, relation: string, resourceClass: new () => ApiResource<R>, related: R | R[] | null): Record<string, unknown>;
+}
+//# sourceMappingURL=ApiResource.d.ts.map

package/dist/resources/ApiResource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiResource.d.ts","sourceRoot":"","sources":["../../src/resources/ApiResource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,8BAAsB,WAAW,CAAC,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEpD,4CAA4C;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE;IAIlD,uDAAuD;IACvD,UAAU,CACR,QAAQ,EAAE,CAAC,EAAE,EACb,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC5D;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,cAAc,CAAA;KAAE;IAoB7D,0DAA0D;IAC1D,IAAI,CAAC,CAAC,EACJ,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,UAAU,WAAW,CAAC,CAAC,CAAC,EACvC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,GACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAY3B"}

package/dist/resources/ApiResource.js

@@ -0,0 +1,58 @@
+/**
+ * ApiResource — transform entities into API responses.
+ *
+ * Controls which fields are exposed, how relationships are serialized,
+ * and provides pagination metadata.
+ *
+ * Usage:
+ *   class UserResource extends ApiResource<User> {
+ *     serialize(user: User) {
+ *       return { id: user.id, email: user.email, name: user.name }
+ *     }
+ *   }
+ *
+ *   ctx.response.json(new UserResource().item(user))
+ *   ctx.response.json(new UserResource().collection(users, { page: 1, perPage: 20, total: 100 }))
+ *
+ * @implements MISS-23
+ */
+export class ApiResource {
+    /** Transform a single item with wrapper. */
+    item(entity) {
+        return { data: this.serialize(entity) };
+    }
+    /** Transform a collection with optional pagination. */
+    collection(entities, pagination) {
+        const data = entities.map((e) => this.serialize(e));
+        if (pagination) {
+            const lastPage = Math.ceil(pagination.total / pagination.perPage);
+            return {
+                data,
+                meta: {
+                    page: pagination.page,
+                    perPage: pagination.perPage,
+                    total: pagination.total,
+                    lastPage,
+                    hasMore: pagination.page < lastPage,
+                },
+            };
+        }
+        return { data };
+    }
+    /** Transform with relationships loaded via a callback. */
+    with(entity, relation, resourceClass, related) {
+        const base = this.serialize(entity);
+        if (related === null) {
+            base[relation] = null;
+        }
+        else if (Array.isArray(related)) {
+            const res = new resourceClass();
+            base[relation] = related.map((r) => res.serialize(r));
+        }
+        else {
+            base[relation] = new resourceClass().serialize(related);
+        }
+        return base;
+    }
+}
+//# sourceMappingURL=ApiResource.js.map

package/dist/resources/ApiResource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiResource.js","sourceRoot":"","sources":["../../src/resources/ApiResource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,OAAgB,WAAW;IAI/B,4CAA4C;IAC5C,IAAI,CAAC,MAAS;QACZ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAA;IACzC,CAAC;IAED,uDAAuD;IACvD,UAAU,CACR,QAAa,EACb,UAA6D;QAE7D,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;QAEnD,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;YACjE,OAAO;gBACL,IAAI;gBACJ,IAAI,EAAE;oBACJ,IAAI,EAAE,UAAU,CAAC,IAAI;oBACrB,OAAO,EAAE,UAAU,CAAC,OAAO;oBAC3B,KAAK,EAAE,UAAU,CAAC,KAAK;oBACvB,QAAQ;oBACR,OAAO,EAAE,UAAU,CAAC,IAAI,GAAG,QAAQ;iBACpC;aACF,CAAA;QACH,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,CAAA;IACjB,CAAC;IAED,0DAA0D;IAC1D,IAAI,CACF,MAAS,EACT,QAAgB,EAChB,aAAuC,EACvC,OAAuB;QAEvB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;QACnC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAA;QACvB,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,IAAI,aAAa,EAAE,CAAA;YAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;QACvD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,aAAa,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QACzD,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}

package/dist/router/Router.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Fluent Router — AdonisJS v6 compatible routing with controllers, resources, and groups.
+ *
+ * @implements FR24, FR25, FR26, FR27, FR28
+ */
+import type { HttpContext } from '../http/HttpContext.js';
+import type { MiddlewareFunction } from '../middleware/Pipeline.js';
+import type { MiddlewareEntry } from '../server/Server.js';
+export type RouteHandlerFunction = (ctx: HttpContext) => Promise<void> | void;
+/**
+ * Controller tuple: [ControllerClass, 'methodName'].
+ * Constructor params are resolved by the IoC container, not by TypeScript —
+ * same pattern as AdonisJS (@poppinss/utils Constructor type).
+ */
+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;
+/** Param matcher — regex or predefined matcher. */
+export type ParamMatcher = RegExp | {
+    pattern: RegExp;
+};
+export interface RouteDefinition {
+    method: string;
+    path: string;
+    handler: RouteHandlerFunction | null;
+    controller?: {
+        target: new (...args: any[]) => any;
+        method: string;
+    };
+    middleware: string[];
+    inlineMiddleware: MiddlewareFunction[];
+    guards: string[];
+    roles: string[];
+    permissions: string[];
+    validators: string[];
+    name?: string;
+    version?: string;
+    domain?: string;
+    matchers: Record<string, ParamMatcher>;
+    deprecates?: {
+        version: string;
+        sunset?: string;
+    };
+}
+export interface MatchResult {
+    route: RouteDefinition;
+    params: Record<string, string>;
+}
+export declare const matchers: {
+    /** Match numeric params only. */
+    number(): ParamMatcher;
+    /** Match UUID v4 params only. */
+    uuid(): ParamMatcher;
+    /** Match slug params only (lowercase alphanumeric + hyphens). */
+    slug(): ParamMatcher;
+};
+/** Fluent route builder — mutates the already-registered route definition. */
+export declare class RouteBuilder {
+    #private;
+    constructor(route: RouteDefinition);
+    /** Name this route (for URL generation and redirects). */
+    as(name: string): this;
+    /** Add named middleware. */
+    middleware(...names: string[]): this;
+    /** Add inline middleware functions. */
+    use(...mw: MiddlewareFunction[]): this;
+    /** Add authentication guards. */
+    guard(...guards: string[]): this;
+    /** Require specific roles. */
+    role(...roles: string[]): this;
+    /** Require specific permissions. */
+    permission(...permissions: string[]): this;
+    /** Add a param constraint. */
+    where(param: string, matcher: ParamMatcher | RegExp): this;
+    /** Attach a validator. */
+    validate(validator: string): this;
+    /** Set API version. */
+    version(v: string): this;
+    /** Restrict to a specific domain. */
+    domain(d: string): this;
+    /** Mark as deprecated. */
+    deprecates(version: string, options?: {
+        sunset?: string;
+    }): this;
+    /** @internal Get the underlying definition. */
+    getDefinition(): RouteDefinition;
+}
+/** Fluent group builder — returned by router.group(callback). */
+export declare class GroupBuilder {
+    #private;
+    constructor(routes: RouteDefinition[]);
+    /** Set URL prefix for all routes in the group. */
+    prefix(p: string): this;
+    /** Add middleware to all routes in the group. */
+    middleware(...names: string[]): this;
+    /** Add inline middleware to all routes in the group. */
+    use(...mw: MiddlewareFunction[]): this;
+    /** Add guards to all routes in the group. */
+    guard(...guards: string[]): this;
+    /** Prefix route names for all routes in the group. */
+    as(namePrefix: string): this;
+    /** Set domain for all routes in the group. */
+    domain(d: string): this;
+    /** Add param matcher to all routes in the group. */
+    where(param: string, matcher: ParamMatcher | RegExp): this;
+}
+/** Builder for on(path).render(view) and on(path).redirect(target). */
+export declare class OnRouteBuilder {
+    #private;
+    constructor(router: Router, path: string);
+    /** Render a view (requires Photon/view provider). */
+    render(view: string, data?: Record<string, unknown>): RouteBuilder;
+    /** Redirect to a path. */
+    redirect(target: string, status?: number): RouteBuilder;
+    /** Redirect to a named route. */
+    redirectToRoute(name: string, params?: Record<string, string>, status?: number): RouteBuilder;
+}
+/** Main Router. */
+export declare class Router {
+    #private;
+    /** Predefined param matchers. */
+    readonly matchers: {
+        /** Match numeric params only. */
+        number(): ParamMatcher;
+        /** Match UUID v4 params only. */
+        uuid(): ParamMatcher;
+        /** Match slug params only (lowercase alphanumeric + hyphens). */
+        slug(): ParamMatcher;
+    };
+    /**
+     * Register router-level middleware (runs on requests with a matched route).
+     *   router.use([() => import('#middleware/auth_middleware')])
+     */
+    use(middleware: MiddlewareEntry[]): this;
+    /**
+     * Register named middleware collection.
+     *   export const middleware = router.named({
+     *     auth: () => import('#middleware/auth_middleware'),
+     *   })
+     */
+    named(collection: Record<string, MiddlewareEntry>): Record<string, MiddlewareFunction>;
+    /** Get the router-level middleware stack. */
+    getRouterMiddleware(): MiddlewareFunction[];
+    /** Get a named middleware by name. */
+    getNamedMiddleware(name: string): MiddlewareFunction | undefined;
+    /** Register a route with any HTTP method. */
+    route(method: string, path: string, handler: RouteHandler): RouteBuilder;
+    get(path: string, handler: RouteHandler): RouteBuilder;
+    post(path: string, handler: RouteHandler): RouteBuilder;
+    put(path: string, handler: RouteHandler): RouteBuilder;
+    patch(path: string, handler: RouteHandler): RouteBuilder;
+    delete(path: string, handler: RouteHandler): RouteBuilder;
+    head(path: string, handler: RouteHandler): RouteBuilder;
+    options(path: string, handler: RouteHandler): RouteBuilder;
+    /** Register a route for all HTTP methods. */
+    any(path: string, handler: RouteHandler): RouteBuilder;
+    /**
+     * Register resourceful routes for a controller.
+     * Generates: index, store, show, update, destroy
+     *
+     * 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
+     */
+    resource(path: string, controller: new (...args: any[]) => any): GroupBuilder;
+    /**
+     * Create a route group with shared configuration.
+     *
+     * AdonisJS-style (chainable):
+     *   router.group(() => {
+     *     router.get('/users', [UsersController, 'index'])
+     *   }).prefix('/api').middleware('auth')
+     *
+     * Legacy-style (config object):
+     *   router.group({ prefix: '/api', guards: ['jwt'] }, (r) => {
+     *     r.get('/users', handler)
+     *   })
+     */
+    group(callback: () => void): GroupBuilder;
+    group(config: {
+        prefix?: string;
+        middleware?: string[];
+        guards?: string[];
+        roles?: string[];
+        permissions?: string[];
+    }, callback: (router: Router) => void): void;
+    /** Create a view/redirect route shortcut. */
+    on(path: string): OnRouteBuilder;
+    /** Set a global param matcher (applied to all routes). */
+    where(param: string, matcher: ParamMatcher | RegExp): this;
+    /** Find a matching route, extracting :param values and validating matchers. */
+    match(method: string, path: string, host?: string): MatchResult | undefined;
+    /** Generate a URL from a named route. */
+    makeUrl(name: string, params?: Record<string, string>): string;
+    /** Get all registered routes (for OpenAPI generation, introspection). */
+    getRoutes(): RouteDefinition[];
+    /** Clear all registered routes (used by hot-reload). */
+    clear(): void;
+    get routeCount(): number;
+}
+//# sourceMappingURL=Router.d.ts.map

package/dist/router/Router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../src/router/Router.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAK1D,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;AAE7E;;;;GAIG;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAEpF,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,oBAAoB,GAAG,gBAAgB,CAAA;AAElE,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAA;IAEpC,UAAU,CAAC,EAAE;QAAE,MAAM,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACpE,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,gBAAgB,EAAE,kBAAkB,EAAE,CAAA;IACtC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACtC,UAAU,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,eAAe,CAAA;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAID,eAAO,MAAM,QAAQ;IACnB,iCAAiC;cACvB,YAAY;IAGtB,iCAAiC;YACzB,YAAY;IAGpB,iEAAiE;YACzD,YAAY;CAGrB,CAAA;AAID,8EAA8E;AAC9E,qBAAa,YAAY;;gBAGX,KAAK,EAAE,eAAe;IAIlC,0DAA0D;IAC1D,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKtB,4BAA4B;IAC5B,UAAU,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAKpC,uCAAuC;IACvC,GAAG,CAAC,GAAG,EAAE,EAAE,kBAAkB,EAAE,GAAG,IAAI;IAKtC,iCAAiC;IACjC,KAAK,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAKhC,8BAA8B;IAC9B,IAAI,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAK9B,oCAAoC;IACpC,UAAU,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI;IAK1C,8BAA8B;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI;IAK1D,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKjC,uBAAuB;IACvB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKxB,qCAAqC;IACrC,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKvB,0BAA0B;IAC1B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKhE,+CAA+C;IAC/C,aAAa,IAAI,eAAe;CAGjC;AAID,iEAAiE;AACjE,qBAAa,YAAY;;gBAGX,MAAM,EAAE,eAAe,EAAE;IAIrC,kDAAkD;IAClD,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAOvB,iDAAiD;IACjD,UAAU,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAOpC,wDAAwD;IACxD,GAAG,CAAC,GAAG,EAAE,EAAE,kBAAkB,EAAE,GAAG,IAAI;IAOtC,6CAA6C;IAC7C,KAAK,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAOhC,sDAAsD;IACtD,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAS5B,8CAA8C;IAC9C,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAOvB,oDAAoD;IACpD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI;CAS3D;AAmBD,uEAAuE;AACvE,qBAAa,cAAc;;gBAIb,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAKxC,qDAAqD;IACrD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;IAYlE,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,YAAY;IAMpD,iCAAiC;IACjC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,SAAM,GAAG,YAAY;CAK3F;AAID,mBAAmB;AACnB,qBAAa,MAAM;;IAejB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ;QAlPjB,iCAAiC;kBACvB,YAAY;QAGtB,iCAAiC;gBACzB,YAAY;QAGpB,iEAAiE;gBACzD,YAAY;MAyOQ;IAI5B;;;OAGG;IACH,GAAG,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,IAAI;IAOxC;;;;;OAKG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAUtF,6CAA6C;IAC7C,mBAAmB,IAAI,kBAAkB,EAAE;IAI3C,sCAAsC;IACtC,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAMhE,6CAA6C;IAC7C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAOxE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAItD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAIvD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAItD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAIxD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAIzD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAIvD,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAI1D,6CAA6C;IAC7C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAMtD;;;;;;;;;;;OAWG;IAEH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GAAG,YAAY;IA0B7E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,YAAY;IACzC,KAAK,CACH,MAAM,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;QACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;QACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KACvB,EACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GACjC,IAAI;IAyCP,6CAA6C;IAC7C,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAMhC,0DAA0D;IAC1D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI;IAyC1D,+EAA+E;IAC/E,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IA0C3E,yCAAyC;IACzC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM;IAkC9D,yEAAyE;IACzE,SAAS,IAAI,eAAe,EAAE;IAI9B,wDAAwD;IACxD,KAAK,IAAI,IAAI;IAKb,IAAI,UAAU,IAAI,MAAM,CAEvB;CAuCF"}