@weconjs/core 0.2.0 → 1.1.0

package/dist/routing/ErrorCatcher.js

@@ -0,0 +1,50 @@
+import chalk from "chalk";
+/**
+ * Base class for configuration error tracking.
+ * Captures caller info from stack traces for precise error reporting.
+ */
+export class ErrorCatcher {
+    /**
+     * Extract caller file, line, column from the stack trace.
+     * Skips internal frames to point to the user's code.
+     */
+    static getCallerInfo() {
+        const err = new Error();
+        const stack = err.stack || "";
+        const stackLines = stack.split("\n").slice(1);
+        // Skip getCallerInfo and constructor frames
+        const callerLine = stackLines[2] || stackLines[1] || "";
+        // V8 format: "    at ClassName.method (file:///path/file.ts:15:23)"
+        let match = callerLine.match(/\((.+?):(\d+):(\d+)\)$/);
+        if (!match) {
+            // Format without parentheses: "    at file:///path/file.ts:15:23"
+            match = callerLine.match(/at\s+(.+?):(\d+):(\d+)$/);
+        }
+        if (match) {
+            const file = match[1].replace("file://", "");
+            const line = parseInt(match[2], 10);
+            const column = parseInt(match[3], 10);
+            const functionMatch = callerLine.match(/at\s+(?:async\s+)?(\S+?)\s+\(/);
+            const functionName = functionMatch ? functionMatch[1] : null;
+            return { file, line, column, function: functionName };
+        }
+        return { file: "unknown", line: 0, column: 0, function: null };
+    }
+    /**
+     * Log a formatted config error with location info, then exit.
+     */
+    static logError(error, tracedStackInfo) {
+        console.error(chalk.red.bold("\n-=>") +
+            chalk.white.bold(" Whoops! We caught an error for you.") +
+            chalk.red.bold(" <=-\n"));
+        console.error(chalk.red.bold("✖ Error:"), chalk.white(error.title));
+        console.error(chalk.gray("\n  Details:"), chalk.white(error.details));
+        console.error(chalk.gray("\n  Location:"), chalk.cyan(`${tracedStackInfo.file}:${tracedStackInfo.line}:${tracedStackInfo.column}`));
+        console.error(chalk.yellow.bold("\n  💡 How to fix:"));
+        console.error(chalk.yellow(`  ${error.fix.replace(/\n/g, "\n  ")}`));
+        console.error("");
+        process.exit(1);
+    }
+}
+export default ErrorCatcher;
+//# sourceMappingURL=ErrorCatcher.js.map

package/dist/routing/ErrorCatcher.js.map

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

package/dist/routing/RaiMatcher.d.ts

@@ -0,0 +1,27 @@
+import type Route from "./Route.js";
+export type RaiRoutesList = Array<Pick<Route, "path" | "method" | "rai">>;
+/**
+ * High-performance RAI lookup engine.
+ * Pre-compiles path matchers, uses exact + runtime caches for O(1) lookups.
+ */
+declare class RaiMatcher {
+    private cache;
+    private routesByMethod;
+    private exactRoutes;
+    constructor(raisList: RaiRoutesList);
+    /** Pre-compile all route matchers and organize by HTTP method */
+    private initialize;
+    /** Score route specificity: static=10, dynamic=1, wildcard=0.5 */
+    private getRouteSpecificity;
+    /** Normalize trailing slashes */
+    private normalizeRoute;
+    /** Find RAI for the given request path and method */
+    findRai(path: string, method: string): string;
+    clearCache(): void;
+    getCacheStats(): {
+        size: number;
+        methods: string[];
+    };
+}
+export default RaiMatcher;
+//# sourceMappingURL=RaiMatcher.d.ts.map

package/dist/routing/RaiMatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RaiMatcher.d.ts","sourceRoot":"","sources":["../../src/routing/RaiMatcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAEpC,MAAM,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC;AAS1E;;;GAGG;AACH,cAAM,UAAU;IACd,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,WAAW,CAAsB;gBAE7B,QAAQ,EAAE,aAAa;IAOnC,iEAAiE;IACjE,OAAO,CAAC,UAAU;IA2ClB,kEAAkE;IAClE,OAAO,CAAC,mBAAmB;IAmB3B,iCAAiC;IACjC,OAAO,CAAC,cAAc;IAQtB,qDAAqD;IAC9C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAsD7C,UAAU,IAAI,IAAI;IAIlB,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;CAM5D;AAED,eAAe,UAAU,CAAC"}

package/dist/routing/RaiMatcher.js

@@ -0,0 +1,127 @@
+import { match } from "path-to-regexp";
+import errors from "../errors/index.js";
+/**
+ * High-performance RAI lookup engine.
+ * Pre-compiles path matchers, uses exact + runtime caches for O(1) lookups.
+ */
+class RaiMatcher {
+    cache;
+    routesByMethod;
+    exactRoutes;
+    constructor(raisList) {
+        this.cache = new Map();
+        this.routesByMethod = new Map();
+        this.exactRoutes = new Map();
+        this.initialize(raisList);
+    }
+    /** Pre-compile all route matchers and organize by HTTP method */
+    initialize(raisList) {
+        for (const route of raisList) {
+            if (typeof route.path !== "string" || !route.method) {
+                console.warn(`Invalid route configuration:`, route);
+                continue;
+            }
+            const normalizedMethod = route.method.trim().toUpperCase();
+            // Cache exact routes (no params) for O(1) lookup
+            if (!route.path.includes(":") && !route.path.includes("*")) {
+                const exactKey = `${normalizedMethod}:${route.path}`;
+                this.exactRoutes.set(exactKey, route.rai);
+                // Also handle trailing slash variant
+                const withSlash = route.path.endsWith("/")
+                    ? route.path.slice(0, -1)
+                    : route.path + "/";
+                this.exactRoutes.set(`${normalizedMethod}:${withSlash}`, route.rai);
+            }
+            const cachedRoute = {
+                matcher: match(route.path, { decode: decodeURIComponent }),
+                rai: route.rai,
+                method: normalizedMethod,
+                path: route.path,
+            };
+            if (!this.routesByMethod.has(normalizedMethod)) {
+                this.routesByMethod.set(normalizedMethod, []);
+            }
+            this.routesByMethod.get(normalizedMethod).push(cachedRoute);
+        }
+        // Sort by specificity (static segments score higher)
+        for (const [, routes] of this.routesByMethod) {
+            routes.sort((a, b) => this.getRouteSpecificity(b.path) - this.getRouteSpecificity(a.path));
+        }
+    }
+    /** Score route specificity: static=10, dynamic=1, wildcard=0.5 */
+    getRouteSpecificity(path) {
+        let score = 0;
+        const segments = path.split("/").filter(Boolean);
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            if (segment.startsWith(":")) {
+                score += 1;
+            }
+            else if (segment === "*") {
+                score += 0.5;
+            }
+            else {
+                score += 10;
+            }
+            score += (segments.length - i) * 0.1;
+        }
+        return score;
+    }
+    /** Normalize trailing slashes */
+    normalizeRoute(route) {
+        const primary = route.endsWith("/") && route.length > 1 ? route.slice(0, -1) : route;
+        const alternate = primary === route ? (route === "/" ? route : route + "/") : route;
+        return { primary, alternate };
+    }
+    /** Find RAI for the given request path and method */
+    findRai(path, method) {
+        const normalizedMethod = method.trim().toUpperCase();
+        const { primary, alternate } = this.normalizeRoute(path);
+        // 1. Exact match (fastest)
+        const exactKey = `${normalizedMethod}:${primary}`;
+        if (this.exactRoutes.has(exactKey)) {
+            return this.exactRoutes.get(exactKey);
+        }
+        // 2. Runtime cache for previously matched dynamic routes
+        const cacheKey = `${normalizedMethod}:${primary}`;
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey).rai;
+        }
+        // 3. Method-specific route matching
+        const methodRoutes = this.routesByMethod.get(normalizedMethod);
+        if (!methodRoutes) {
+            throw new errors.RequestError(`No RAI found for the request URL: ${path} with method: ${method}`, { code: "RAI_NOT_FOUND", route: path, method });
+        }
+        // 4. Pattern matching (sorted by specificity)
+        for (const route of methodRoutes) {
+            const matchResult = route.matcher(primary) || route.matcher(alternate);
+            if (matchResult) {
+                this.cache.set(cacheKey, route);
+                // Evict oldest entry if cache is too large
+                if (this.cache.size > 1000) {
+                    const firstKey = this.cache.keys().next().value;
+                    this.cache.delete(firstKey);
+                }
+                return route.rai;
+            }
+        }
+        // 5. No match
+        throw new errors.RequestError(`No RAI found for the request URL: ${path} with method: ${method}`, {
+            code: "RAI_NOT_FOUND",
+            route: path,
+            method,
+            availableRoutes: methodRoutes.map((r) => r.path),
+        });
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    getCacheStats() {
+        return {
+            size: this.cache.size,
+            methods: Array.from(this.routesByMethod.keys()),
+        };
+    }
+}
+export default RaiMatcher;
+//# sourceMappingURL=RaiMatcher.js.map

package/dist/routing/RaiMatcher.js.map

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

package/dist/routing/Route.d.ts

@@ -0,0 +1,28 @@
+import type { Handler, RequestHandler } from "express";
+import type { RouteConfig, ErrorTraceType, RAI, DefaultRole } from "../types.js";
+import ErrorCatcher from "./ErrorCatcher.js";
+import type RoutesParam from "./RoutesParam.js";
+/**
+ * Single API endpoint definition.
+ * Carries method, path, RAI, roles, middlewares, and metadata.
+ */
+declare class Route<TRole extends string = DefaultRole> extends ErrorCatcher {
+    id: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    params?: Array<RoutesParam>;
+    middlewares: Handler[] | RequestHandler[] | any[];
+    name: string;
+    description: string;
+    rai: RAI;
+    roles: TRole[];
+    meta?: Record<string, unknown>;
+    debugInfo: ErrorTraceType;
+    constructor(r: RouteConfig<TRole>);
+    private validateRoute;
+    private handleConfigError;
+    /** Check if user roles are authorized to access this route */
+    isAuthorized(userRoles: string[]): boolean;
+}
+export default Route;
+//# sourceMappingURL=Route.d.ts.map

package/dist/routing/Route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Route.d.ts","sourceRoot":"","sources":["../../src/routing/Route.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EAEd,GAAG,EACH,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAE7C,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAEhD;;;GAGG;AACH,cAAM,KAAK,CAAC,KAAK,SAAS,MAAM,GAAG,WAAW,CAAE,SAAQ,YAAY;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,CAAM;IACjC,WAAW,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,GAAG,GAAG,EAAE,CAAC;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxB,SAAS,EAAE,cAAc,CAAC;gBAErB,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC;IAqBjC,OAAO,CAAC,aAAa;IAwBrB,OAAO,CAAC,iBAAiB;IAqDzB,8DAA8D;IAC9D,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO;CAS3C;AAED,eAAe,KAAK,CAAC"}

package/dist/routing/Route.js

@@ -0,0 +1,125 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { randomUUID } from "crypto";
+import ErrorCatcher from "./ErrorCatcher.js";
+import errors from "../errors/index.js";
+/**
+ * Single API endpoint definition.
+ * Carries method, path, RAI, roles, middlewares, and metadata.
+ */
+class Route extends ErrorCatcher {
+    id;
+    method;
+    path;
+    params = [];
+    middlewares;
+    name;
+    description;
+    rai;
+    roles;
+    meta;
+    debugInfo;
+    constructor(r) {
+        super();
+        this.id = randomUUID();
+        this.method = r.method;
+        this.path = r.path;
+        this.middlewares = r.middlewares;
+        this.name = r.name ? r.name : `[${this.method}] ${this.path}`;
+        this.description = r.description ? r.description : "";
+        this.rai = r.rai;
+        this.roles = r.roles;
+        this.meta = r.meta;
+        this.debugInfo = Route.getCallerInfo();
+        try {
+            this.validateRoute();
+        }
+        catch (err) {
+            this.handleConfigError(err, this.debugInfo);
+        }
+    }
+    validateRoute() {
+        if (!this.method) {
+            throw new errors.ConfigError("ROUTE_CONFIG:MISSING_METHOD");
+        }
+        if (!this.path) {
+            throw new errors.ConfigError("ROUTE_CONFIG:MISSING_PATH");
+        }
+        if (!this.rai) {
+            throw new errors.ConfigError("ROUTE_CONFIG:MISSING_RAI");
+        }
+        if (typeof this.rai !== "string") {
+            throw new errors.ConfigError("ROUTE_CONFIG:INVALID_RAI_TYPE");
+        }
+        if (!this.roles) {
+            throw new errors.ConfigError("ROUTE_CONFIG:MISSING_ROLES");
+        }
+        if (!Array.isArray(this.middlewares)) {
+            throw new errors.ConfigError("ROUTE_CONFIG:INVALID_MIDDLEWARES_TYPE");
+        }
+        if (this.middlewares.length === 0) {
+            throw new errors.ConfigError("ROUTE_CONFIG:EMPTY_MIDDLEWARES");
+        }
+    }
+    handleConfigError(err, errInfo) {
+        const POSSIBLE_ERRORS = {
+            "ROUTE_CONFIG:MISSING_METHOD": {
+                title: "Missing required 'method' property",
+                details: "The Route instance requires a 'method' to be defined",
+                fix: "Add a method to your route configuration:\n    method: 'GET' | 'POST' | 'PUT' | 'DELETE'",
+            },
+            "ROUTE_CONFIG:MISSING_PATH": {
+                title: "Missing required 'path' property",
+                details: "The Route instance requires a 'path' to be defined",
+                fix: "Add a path to your route configuration:\n    path: '/users/:id'",
+            },
+            "ROUTE_CONFIG:MISSING_RAI": {
+                title: "Missing required 'rai' property",
+                details: "The Route instance requires a unique 'rai' (Route Access Identifier)",
+                fix: "Add a rai to your route configuration:\n    rai: 'users:read' // Must be unique across all routes",
+            },
+            "ROUTE_CONFIG:INVALID_RAI_TYPE": {
+                title: "Invalid 'rai' property type",
+                details: "The 'rai' property must be a string, but received: " + typeof this.rai,
+                fix: "Ensure rai is a string:\n    rai: 'users:read'",
+            },
+            "ROUTE_CONFIG:DUPLICATE_RAI": {
+                title: "Duplicate 'rai' detected",
+                details: "The 'rai' provided is already registered: " + this.rai,
+                fix: "Ensure each route has a unique rai:\n    rai: 'users:create'",
+            },
+            "ROUTE_CONFIG:MISSING_ROLES": {
+                title: "Missing required 'roles' property",
+                details: "The Route instance requires a 'roles' array",
+                fix: "Add roles to your route configuration:\n    roles: ['admin', 'user']",
+            },
+            "ROUTE_CONFIG:INVALID_MIDDLEWARES_TYPE": {
+                title: "Invalid 'middlewares' property type",
+                details: "The 'middlewares' property must be an array, but received: " + typeof this.middlewares,
+                fix: "Ensure middlewares is an array:\n    middlewares: [authMiddleware, validateMiddleware]",
+            },
+            "ROUTE_CONFIG:EMPTY_MIDDLEWARES": {
+                title: "Empty 'middlewares' array",
+                details: "The Route instance requires at least one middleware function",
+                fix: "Add at least one handler:\n    middlewares: [(req, res) => { res.json({ data: 'example' }) }]",
+            },
+        };
+        const errorConfig = POSSIBLE_ERRORS[err.message] || {
+            title: err.message,
+            details: "An unexpected error occurred",
+            fix: "Please check your Route configuration",
+        };
+        ErrorCatcher.logError(errorConfig, errInfo);
+    }
+    /** Check if user roles are authorized to access this route */
+    isAuthorized(userRoles) {
+        if (this.roles.length === 0)
+            return false;
+        for (const role of userRoles) {
+            if (this.roles.includes(role))
+                return true;
+        }
+        return false;
+    }
+}
+export default Route;
+//# sourceMappingURL=Route.js.map

package/dist/routing/Route.js.map

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

package/dist/routing/Routes.d.ts

@@ -0,0 +1,31 @@
+import type { Handler } from "express";
+import Route from "./Route.js";
+import type { RoutesConfig, DefaultRole } from "../types.js";
+import RoutesParam from "./RoutesParam.js";
+import ErrorCatcher from "./ErrorCatcher.js";
+/**
+ * Hierarchical route group with shared prefix, middleware, and params.
+ * Contains Route (endpoints) and/or nested Routes (sub-groups).
+ */
+declare class Routes<TRole extends string = DefaultRole> extends ErrorCatcher {
+    prefix: string;
+    routes: Array<Route<TRole> | Routes<TRole>>;
+    params?: RoutesParam[];
+    middlewares?: Handler[];
+    mergeParams?: boolean;
+    meta?: Record<string, unknown>;
+    constructor(r: RoutesConfig<TRole>);
+    private validateRoutes;
+    private handleConfigError;
+    /**
+     * Flatten the route tree into a Map<RAI, enriched Route>.
+     * Accumulates paths, middlewares, and params from parent groups.
+     */
+    groupRoutesByRai(): Map<string, Route<TRole> & {
+        params: RoutesParam[];
+        middlewares: Handler[];
+    }>;
+    private deduplicateParams;
+}
+export default Routes;
+//# sourceMappingURL=Routes.d.ts.map

package/dist/routing/Routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Routes.d.ts","sourceRoot":"","sources":["../../src/routing/Routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,KAAK,EAGV,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAC3C,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAG7C;;;GAGG;AACH,cAAM,MAAM,CAAC,KAAK,SAAS,MAAM,GAAG,WAAW,CAAE,SAAQ,YAAY;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5C,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAS;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEnB,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC;IAkBlC,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,iBAAiB;IA0CzB;;;OAGG;IACI,gBAAgB,IAAI,GAAG,CAC5B,MAAM,EACN,KAAK,CAAC,KAAK,CAAC,GAAG;QAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAAC,WAAW,EAAE,OAAO,EAAE,CAAA;KAAE,CACjE;IA6ED,OAAO,CAAC,iBAAiB;CAK1B;AAED,eAAe,MAAM,CAAC"}

package/dist/routing/Routes.js

@@ -0,0 +1,151 @@
+import Route from "./Route.js";
+import ErrorCatcher from "./ErrorCatcher.js";
+import errors from "../errors/index.js";
+/**
+ * Hierarchical route group with shared prefix, middleware, and params.
+ * Contains Route (endpoints) and/or nested Routes (sub-groups).
+ */
+class Routes extends ErrorCatcher {
+    prefix;
+    routes;
+    params;
+    middlewares;
+    mergeParams = false;
+    meta;
+    constructor(r) {
+        super();
+        this.prefix = r.prefix ? r.prefix : "";
+        this.routes = r.routes;
+        this.params = r.params ? r.params : [];
+        this.middlewares = r.middlewares ? r.middlewares : [];
+        this.mergeParams = r.mergeParams ? r.mergeParams : false;
+        this.meta = r.meta;
+        try {
+            this.validateRoutes();
+        }
+        catch (err) {
+            const errInfo = Routes.getCallerInfo();
+            this.handleConfigError(err, errInfo);
+        }
+    }
+    validateRoutes() {
+        if (this.prefix && typeof this.prefix !== "string") {
+            throw new errors.ConfigError("ROUTES_CONFIG:INVALID_PREFIX_TYPE");
+        }
+        if (!this.routes) {
+            throw new errors.ConfigError("ROUTES_CONFIG:MISSING_ROUTES");
+        }
+        if (!Array.isArray(this.routes)) {
+            throw new Error("ROUTES_CONFIG:INVALID_ROUTES_TYPE");
+        }
+        if (this.middlewares && !Array.isArray(this.middlewares)) {
+            throw new errors.ConfigError("ROUTES_CONFIG:INVALID_MIDDLEWARES_TYPE");
+        }
+        if (this.params && !Array.isArray(this.params)) {
+            throw new errors.ConfigError("ROUTES_CONFIG:INVALID_PARAMS_TYPE");
+        }
+        if (this.mergeParams && typeof this.mergeParams !== "boolean") {
+            throw new errors.ConfigError("ROUTES_CONFIG:INVALID_MERGE_PARAMS_TYPE");
+        }
+    }
+    handleConfigError(err, errInfo) {
+        const POSSIBLE_ERRORS = {
+            "ROUTES_CONFIG:INVALID_PREFIX_TYPE": {
+                title: "Invalid 'prefix' property type",
+                details: "The 'prefix' must be a string, but received: " + typeof this.prefix,
+                fix: "Ensure prefix is a string:\n    prefix: '/api' or prefix: ''",
+            },
+            "ROUTES_CONFIG:MISSING_ROUTES": {
+                title: "Missing required 'routes' property",
+                details: "The Routes instance requires a 'routes' array",
+                fix: "Add a routes array:\n    routes: [new Routes(...), new Route(...)]",
+            },
+            "ROUTES_CONFIG:INVALID_ROUTES_TYPE": {
+                title: "Invalid 'routes' property type",
+                details: "The 'routes' must be an array, but received: " + typeof this.routes,
+                fix: "Ensure routes is an array:\n    routes: [...]",
+            },
+            "ROUTES_CONFIG:INVALID_MIDDLEWARES_TYPE": {
+                title: "Invalid 'middlewares' property type",
+                details: "The 'middlewares' must be an array of express handlers, but received: " + typeof this.middlewares,
+                fix: "Provide an array of middleware:\n    middlewares: [middleware1, middleware2]",
+            },
+            "ROUTES_CONFIG:INVALID_PARAMS_TYPE": {
+                title: "Invalid 'params' property type",
+                details: "The 'params' must be an array of RoutesParam instances, but received: " + typeof this.params,
+                fix: "Provide an array of RoutesParam:\n    params: [new RoutesParam(...)]",
+            },
+            "ROUTES_CONFIG:INVALID_MERGE_PARAMS_TYPE": {
+                title: "Invalid 'mergeParams' property type",
+                details: "The 'mergeParams' must be a boolean, but received: " + typeof this.mergeParams,
+                fix: "Set mergeParams to a boolean:\n    mergeParams: true",
+            },
+        };
+        const errorConfig = POSSIBLE_ERRORS[err.message] || {
+            title: err.message,
+            details: "An unexpected error occurred",
+            fix: "Please check your Routes configuration",
+        };
+        ErrorCatcher.logError(errorConfig, errInfo);
+    }
+    /**
+     * Flatten the route tree into a Map<RAI, enriched Route>.
+     * Accumulates paths, middlewares, and params from parent groups.
+     */
+    groupRoutesByRai() {
+        const raiMap = new Map();
+        const traverse = (current, accumulatedPath, accumulatedParams, accumulatedMiddlewares, parentsMergeParams) => {
+            // Handle endpoint
+            if (current instanceof Route) {
+                const fullPath = accumulatedPath + current.path;
+                const finalMiddlewares = [
+                    ...accumulatedMiddlewares,
+                    ...(current.middlewares || []),
+                ];
+                const finalParams = this.deduplicateParams(accumulatedParams);
+                if (raiMap.has(current.rai)) {
+                    const errorConfig = {
+                        title: "Duplicate 'rai' detected",
+                        details: "The 'rai' provided is already registered: " + current.rai,
+                        fix: "Ensure each route has a unique rai:\n    rai: 'users:create'",
+                    };
+                    ErrorCatcher.logError(errorConfig, current.debugInfo);
+                }
+                const extendedRoute = Object.assign(Object.create(Object.getPrototypeOf(current)), current, {
+                    path: fullPath,
+                    params: finalParams,
+                    middlewares: finalMiddlewares,
+                });
+                raiMap.set(current.rai, extendedRoute);
+                return;
+            }
+            // Handle group
+            if (current instanceof Routes) {
+                const nextPath = accumulatedPath + current.prefix;
+                const nextMiddlewares = [
+                    ...accumulatedMiddlewares,
+                    ...(current.middlewares || []),
+                ];
+                let nextParams = [];
+                if (parentsMergeParams) {
+                    nextParams = [...accumulatedParams, ...(current.params || [])];
+                }
+                else {
+                    nextParams = current.params || [];
+                }
+                current.routes.forEach((child) => {
+                    traverse(child, nextPath, nextParams, nextMiddlewares, current.mergeParams || false);
+                });
+            }
+        };
+        traverse(this, "", [], [], false);
+        return raiMap;
+    }
+    deduplicateParams(params) {
+        const unique = new Map();
+        params.forEach((p) => unique.set(p.path, p));
+        return Array.from(unique.values());
+    }
+}
+export default Routes;
+//# sourceMappingURL=Routes.js.map

package/dist/routing/Routes.js.map

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

package/dist/routing/RoutesParam.d.ts

@@ -0,0 +1,29 @@
+import type { RequestParamHandler } from "express";
+import ErrorCatcher from "./ErrorCatcher.js";
+/**
+ * Parameter handler with optional validation rules.
+ * Attached to Routes to validate and process URL params (e.g. :userId).
+ */
+declare class RoutesParam extends ErrorCatcher {
+    readonly uuid: string;
+    path: string;
+    middleware: RequestParamHandler;
+    validate?: {
+        pattern?: RegExp;
+        minLength?: number;
+        maxLength?: number;
+        validatorFn?: (value: string) => boolean;
+    };
+    constructor(path: string, middleware: RequestParamHandler, validate?: {
+        pattern?: RegExp;
+        minLength?: number;
+        maxLength?: number;
+        validatorFn?: (value: string) => boolean;
+    });
+    private validateParam;
+    private handleConfigError;
+    /** Run all validation rules against a param value */
+    validateValue(value: string): boolean;
+}
+export default RoutesParam;
+//# sourceMappingURL=RoutesParam.d.ts.map

package/dist/routing/RoutesParam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutesParam.d.ts","sourceRoot":"","sources":["../../src/routing/RoutesParam.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,YAAY,MAAM,mBAAmB,CAAC;AAI7C;;;GAGG;AACH,cAAM,WAAY,SAAQ,YAAY;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;KAC1C,CAAC;gBAGA,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;KAC1C;IAiBH,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,iBAAiB;IAgDzB,qDAAqD;IACrD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAUtC;AAED,eAAe,WAAW,CAAC"}