xypriss 9.11.13 → 9.12.0

package/dist/src/server/routing/modules/groups.js

@@ -0,0 +1,55 @@
+import { normalizePath, compileRoutePattern, joinPaths } from "./path";
+import { resolveCondition, createGuardMiddleware } from "./helpers";
+/**
+ * Handles router.group() logic.
+ */
+export function handleGroup(parentRouter, childRouter, options, callback, internalState) {
+    if (options.middleware) {
+        options.middleware.forEach((m) => childRouter.use(m));
+    }
+    callback(childRouter);
+    let prefix = options.prefix ?? "";
+    if (options.version) {
+        const ver = `v${options.version.replace(/^v/, "")}`;
+        prefix = prefix ? joinPaths(prefix, ver) : `/${ver}`;
+    }
+    prefix = prefix ? normalizePath(prefix) : "/";
+    childRouter.getRoutes().forEach((route) => {
+        const fullPath = joinPaths(prefix, route.originalPath);
+        const { pattern, paramNames, paramConstraints } = compileRoutePattern(fullPath, internalState.options);
+        const mergedMeta = {
+            ...(options.meta ?? {}),
+            ...(route.meta ?? {}),
+            version: route.meta?.version ?? options.version,
+        };
+        const groupGuards = options.guards;
+        let groupGuardMiddleware;
+        if (groupGuards) {
+            groupGuardMiddleware = createGuardMiddleware(groupGuards, internalState.logger);
+        }
+        const rateLimit = route.rateLimit ?? options.rateLimit;
+        const active = resolveCondition(options.active, internalState.featureResolver) &&
+            route.active;
+        const routeMiddleware = [...route.middleware];
+        if (groupGuardMiddleware) {
+            routeMiddleware.unshift({ handler: groupGuardMiddleware });
+        }
+        const mounted = {
+            ...route,
+            path: fullPath,
+            originalPath: fullPath,
+            pattern,
+            paramNames,
+            paramConstraints,
+            meta: Object.keys(mergedMeta).length ? mergedMeta : undefined,
+            guards: groupGuards ?? route.guards,
+            rateLimit,
+            active,
+            version: mergedMeta.version,
+            middleware: [...internalState.middleware, ...routeMiddleware],
+        };
+        internalState.routes.push(mounted);
+        internalState.logger.debug("router", `Group mounted: ${route.method} ${fullPath}`);
+    });
+}
+//# sourceMappingURL=groups.js.map

package/dist/src/server/routing/modules/groups.js.map

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

package/dist/src/server/routing/modules/helpers.d.ts

@@ -0,0 +1,19 @@
+import { RouteCondition, BuiltInGuards, RouteGuard } from "./types";
+import { MiddlewareFunction } from "../../../types/httpServer.type";
+/**
+ * Builds a regex pattern and constraint name for a typed parameter.
+ */
+export declare function buildParamPattern(typeExpr: string | undefined): {
+    pattern: string;
+    constraint: string;
+};
+/**
+ * Resolves a route condition (env or feature flag).
+ */
+export declare function resolveCondition(cond: RouteCondition | undefined, featureResolver: ((flag: string) => boolean) | null): boolean;
+export declare function nextRouteId(): string;
+/**
+ * Creates a middleware that executes all guards (built-in and custom).
+ */
+export declare function createGuardMiddleware(guards: BuiltInGuards | RouteGuard[], logger: any): MiddlewareFunction;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/src/server/routing/modules/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../../src/server/routing/modules/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EACH,cAAc,EACd,aAAa,EACb,UAAU,EAGb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGpE;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACtB,CAyCA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,cAAc,GAAG,SAAS,EAChC,eAAe,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,IAAI,GACpD,OAAO,CAeT;AAMD,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,aAAa,GAAG,UAAU,EAAE,EACpC,MAAM,EAAE,GAAG,GACZ,kBAAkB,CA+FpB"}

package/dist/src/server/routing/modules/helpers.js

@@ -0,0 +1,164 @@
+import { BUILTIN_PARAM_PATTERNS } from "./constants";
+import { XyGuard } from "./XyGuard";
+/**
+ * Builds a regex pattern and constraint name for a typed parameter.
+ */
+export function buildParamPattern(typeExpr) {
+    if (!typeExpr)
+        return { pattern: "[^/]+", constraint: "string" };
+    const lower = typeExpr.trim().toLowerCase();
+    if (BUILTIN_PARAM_PATTERNS[lower]) {
+        return { pattern: BUILTIN_PARAM_PATTERNS[lower], constraint: lower };
+    }
+    // string(min,max)
+    const strRange = lower.match(/^string\((\d+),(\d+)\)$/);
+    if (strRange) {
+        return {
+            pattern: `[^/]{${strRange[1]},${strRange[2]}}`,
+            constraint: lower,
+        };
+    }
+    // number(min,max)
+    const numRange = lower.match(/^number\((-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)\)$/);
+    if (numRange) {
+        return {
+            pattern: "-?\\d+(?:\\.\\d+)?",
+            constraint: lower,
+        };
+    }
+    // enum(a,b,c)
+    const enumMatch = lower.match(/^enum\((.+)\)$/);
+    if (enumMatch) {
+        const values = enumMatch[1]
+            .split(",")
+            .map((v) => v.trim().replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+            .join("|");
+        return { pattern: `(?:${values})`, constraint: lower };
+    }
+    // Fallback — treat as raw regex pattern
+    return { pattern: typeExpr, constraint: typeExpr };
+}
+/**
+ * Resolves a route condition (env or feature flag).
+ */
+export function resolveCondition(cond, featureResolver) {
+    if (cond === undefined)
+        return true;
+    if (typeof cond === "boolean")
+        return cond;
+    if (typeof cond === "function")
+        return cond();
+    if (typeof cond === "object") {
+        if (cond.env) {
+            const envs = Array.isArray(cond.env) ? cond.env : [cond.env];
+            const current = process.env.NODE_ENV ?? "development";
+            return envs.includes(current);
+        }
+        if (cond.feature) {
+            return featureResolver?.(cond.feature) ?? true;
+        }
+    }
+    return true;
+}
+/**
+ * Generates a unique route ID.
+ */
+let _routeIdCounter = 0;
+export function nextRouteId() {
+    return `route_${(++_routeIdCounter).toString(36)}`;
+}
+/**
+ * Creates a middleware that executes all guards (built-in and custom).
+ */
+export function createGuardMiddleware(guards, logger) {
+    return async (req, res, next) => {
+        const isBuiltIn = !Array.isArray(guards);
+        const customGuards = Array.isArray(guards)
+            ? guards
+            : guards.custom || [];
+        // 1. Built-in Guards via XyGuard resolvers
+        if (isBuiltIn) {
+            const b = guards;
+            // Check Authentication
+            if (b.authenticated) {
+                const resolver = XyGuard.get("authenticated");
+                if (resolver) {
+                    const result = await resolver(req);
+                    if (result === false) {
+                        return res.status(401).json({
+                            success: false,
+                            error: "Unauthorized: Authentication required",
+                        });
+                    }
+                    if (typeof result === "string") {
+                        return res
+                            .status(401)
+                            .json({ success: false, error: result });
+                    }
+                }
+            }
+            // Check Roles
+            if (b.roles && b.roles.length > 0) {
+                const resolver = XyGuard.get("roles");
+                if (resolver) {
+                    const result = await resolver(req, b.roles);
+                    if (result === false) {
+                        return res.status(403).json({
+                            success: false,
+                            error: "Forbidden: Insufficient roles",
+                        });
+                    }
+                    if (typeof result === "string") {
+                        return res
+                            .status(403)
+                            .json({ success: false, error: result });
+                    }
+                }
+            }
+            // Check Permissions
+            if (b.permissions && b.permissions.length > 0) {
+                const resolver = XyGuard.get("permissions");
+                if (resolver) {
+                    const result = await resolver(req, b.permissions);
+                    if (result === false) {
+                        return res.status(403).json({
+                            success: false,
+                            error: "Forbidden: Insufficient permissions",
+                        });
+                    }
+                    if (typeof result === "string") {
+                        return res
+                            .status(403)
+                            .json({ success: false, error: result });
+                    }
+                }
+            }
+        }
+        // 2. Custom Guard functions
+        for (const guard of customGuards) {
+            try {
+                const result = await guard(req, res);
+                if (result === false) {
+                    return res.status(403).json({
+                        success: false,
+                        error: "Forbidden: Guard rejection",
+                    });
+                }
+                if (typeof result === "string") {
+                    return res
+                        .status(401)
+                        .json({ success: false, error: result });
+                }
+            }
+            catch (err) {
+                logger.error("router", `Guard execution error: ${err}`);
+                return res.status(500).json({
+                    success: false,
+                    error: "Internal Server Error during guard check",
+                });
+            }
+        }
+        next?.();
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/src/server/routing/modules/helpers.js.map

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

package/dist/src/server/routing/modules/middleware.d.ts

@@ -0,0 +1,20 @@
+import { RoutRateLimit, RouteCache, RouteLifecycle, MiddlewareFunction } from "./types";
+/**
+ * Creates a rate limiting middleware for a specific route.
+ */
+export declare function createRateLimitMiddleware(options: RoutRateLimit): MiddlewareFunction;
+/**
+ * Creates a caching middleware for a specific route.
+ */
+export declare function createCacheMiddleware(options: RouteCache): MiddlewareFunction;
+/**
+ * Injects lifecycle hooks into the request-response cycle.
+ */
+export declare function wrapWithLifecycle(handler: Function, lifecycle: RouteLifecycle): MiddlewareFunction;
+/**
+ * Scans the handler function's source code for res.status() calls.
+ */
+export declare function detectStatusCodes(handler: Function): Record<string, {
+    description: string;
+}>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/src/server/routing/modules/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../../../src/server/routing/modules/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,aAAa,EACb,UAAU,EACV,cAAc,EACd,kBAAkB,EACrB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,yBAAyB,CACrC,OAAO,EAAE,aAAa,GACvB,kBAAkB,CAoCpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,GAAG,kBAAkB,CAmC7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC7B,OAAO,EAAE,QAAQ,EACjB,SAAS,EAAE,cAAc,GAC1B,kBAAkB,CAgDpB;AAoBD;;GAEG;AACH,wBAAgB,iBAAiB,CAC7B,OAAO,EAAE,QAAQ,GAClB,MAAM,CAAC,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAmCzC"}

package/dist/src/server/routing/modules/middleware.js

@@ -0,0 +1,185 @@
+/**
+ * Creates a rate limiting middleware for a specific route.
+ */
+export function createRateLimitMiddleware(options) {
+    const hits = new Map();
+    const windowMs = options.windowMs ||
+        (options.window ? parseDuration(options.window) : 60000); // Default 1m
+    return (req, res, next) => {
+        const key = typeof options.keyBy === "function"
+            ? options.keyBy(req)
+            : (options.keyBy === "user" ? req.user?.id : req.ip) ||
+                "anonymous";
+        const now = Date.now();
+        const hit = hits.get(key) || { count: 0, reset: now + windowMs };
+        if (now > hit.reset) {
+            hit.count = 0;
+            hit.reset = now + windowMs;
+        }
+        hit.count++;
+        hits.set(key, hit);
+        if (hit.count > options.max) {
+            return res.status(429).json({
+                success: false,
+                error: options.message ||
+                    "Too many requests, please try again later.",
+                retryAfter: Math.ceil((hit.reset - now) / 1000),
+            });
+        }
+        next();
+    };
+}
+/**
+ * Creates a caching middleware for a specific route.
+ */
+export function createCacheMiddleware(options) {
+    const ttl = typeof options === "string"
+        ? parseDuration(options) / 1000
+        : options.ttl;
+    return async (req, res, next) => {
+        if (req.method !== "GET")
+            return next();
+        const cache = req.app?.getCache?.();
+        if (!cache)
+            return next();
+        const key = typeof options === "object" && options.key
+            ? options.key(req)
+            : `route_cache:${req.path}:${JSON.stringify(req.query)}`;
+        try {
+            const cached = await cache.get(key);
+            if (cached) {
+                return res.json(cached);
+            }
+            // Intercept res.json to cache the response
+            const originalJson = res.json;
+            res.json = (data) => {
+                cache.set(key, data, { ttl }).catch(() => { });
+                return originalJson.call(res, data);
+            };
+        }
+        catch (err) {
+            // Ignore cache errors and proceed
+        }
+        next();
+    };
+}
+/**
+ * Injects lifecycle hooks into the request-response cycle.
+ */
+export function wrapWithLifecycle(handler, lifecycle) {
+    return async (req, res, nextArg) => {
+        const next = typeof nextArg === "function" ? nextArg : () => { };
+        const start = Date.now();
+        let errorCaught = false;
+        try {
+            // 1. beforeEnter
+            if (lifecycle.beforeEnter) {
+                let proceed = false;
+                await lifecycle.beforeEnter(req, res, () => {
+                    proceed = true;
+                });
+                // If the hook ended the response or explicitly didn't call next (if we want to be strict)
+                // but for hooks, we usually continue unless res is ended.
+                if (res.writableEnded)
+                    return;
+            }
+            // 2. Main Handler
+            await handler(req, res, next);
+            // 3. afterLeave (Normal flow)
+            // Note: If res.json is called, it might close the response before we reach here.
+            // But we still want to trigger the hook if it hasn't crashed.
+        }
+        catch (err) {
+            errorCaught = true;
+            if (lifecycle.onError) {
+                try {
+                    return await lifecycle.onError(err, req, res, next);
+                }
+                catch (innerErr) {
+                    console.error("Critical error in lifecycle.onError:", innerErr);
+                }
+            }
+            throw err;
+        }
+        finally {
+            if (lifecycle.afterLeave) {
+                const duration = Date.now() - start;
+                try {
+                    await lifecycle.afterLeave(req, res, duration);
+                }
+                catch (err) {
+                    console.error("[LIFECYCLE] Error in afterLeave hook:", err);
+                }
+            }
+        }
+    };
+}
+/**
+ * Internal duration parser (s, m, h, d)
+ */
+function parseDuration(val) {
+    if (!val)
+        return 0;
+    const match = val.match(/^(\d+)([smhd])$/);
+    if (!match)
+        return 0;
+    const num = parseInt(match[1]);
+    const unit = match[2];
+    const map = {
+        s: 1000,
+        m: 60000,
+        h: 3600000,
+        d: 86400000,
+    };
+    return num * map[unit || "s"];
+}
+/**
+ * Scans the handler function's source code for res.status() calls.
+ */
+export function detectStatusCodes(handler) {
+    const originalHandler = handler.__original || handler;
+    const code = originalHandler.toString();
+    const codes = {};
+    // Find res.status(XXX)
+    const statusMatches = code.matchAll(/res\.status\((\d+)\)/g);
+    for (const match of statusMatches) {
+        const statusCode = match[1];
+        codes[statusCode] = { description: getStatusDescription(statusCode) };
+    }
+    // Find res.redirect(...) -> usually 302
+    if (code.includes("res.redirect(")) {
+        codes["302"] = { description: "Found (Redirect)" };
+    }
+    // Find res.success(...) -> 200
+    if (code.includes("res.success(")) {
+        codes["200"] = { description: "Successful response" };
+    }
+    // Fallback: if it looks like there's a response but no status was found
+    if (Object.keys(codes).length === 0 &&
+        (code.includes("res.json") ||
+            code.includes("res.send") ||
+            code.includes("res.html") ||
+            code.includes("res.xJson"))) {
+        codes["200"] = { description: "Successful response" };
+    }
+    return codes;
+}
+function getStatusDescription(code) {
+    const map = {
+        "200": "OK",
+        "201": "Created",
+        "204": "No Content",
+        "301": "Moved Permanently",
+        "302": "Found",
+        "400": "Bad Request",
+        "401": "Unauthorized",
+        "403": "Forbidden",
+        "404": "Not Found",
+        "409": "Conflict",
+        "422": "Unprocessable Entity",
+        "429": "Too Many Requests",
+        "500": "Internal Server Error",
+    };
+    return map[code] || `Response status ${code}`;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/src/server/routing/modules/middleware.js.map

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

package/dist/src/server/routing/modules/path.d.ts

@@ -0,0 +1,33 @@
+import { ParamConstraint } from "./types";
+/** Path validation and normalization regexes */
+export declare const PATH_PATTERNS: {
+    leadingSlash: RegExp;
+    trailingSlash: RegExp;
+    multipleSlashes: RegExp;
+    wildcardPattern: RegExp;
+    pathValidation: RegExp;
+};
+/** Normalize a path string */
+export declare function normalizePath(path: string): string;
+/** Join two paths safely */
+export declare function joinPaths(basePath: string, subPath: string): string;
+/** Validate path format */
+export declare function isValidPath(path: string): boolean;
+/**
+ * Compile a route pattern.
+ * Supports:
+ *  - :param           → standard param
+ *  - :param<type>     → typed param (number, uuid, enum, …)
+ *  - :param(regex)    → inline regex constraint
+ *  - *                → single segment wildcard
+ *  - **               → multi-segment wildcard
+ */
+export declare function compileRoutePattern(path: string, options: {
+    strict?: boolean;
+    caseSensitive?: boolean;
+}): {
+    pattern: RegExp;
+    paramNames: string[];
+    paramConstraints: Record<string, ParamConstraint>;
+};
+//# sourceMappingURL=path.d.ts.map

package/dist/src/server/routing/modules/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../../../src/server/routing/modules/path.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,gDAAgD;AAChD,eAAO,MAAM,aAAa;;;;;;CAOzB,CAAC;AAEF,8BAA8B;AAC9B,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAclD;AAED,4BAA4B;AAC5B,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOnE;AAED,2BAA2B;AAC3B,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IACL,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B,GACF;IACC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACrD,CAoFA"}

package/dist/src/server/routing/modules/path.js

@@ -0,0 +1,125 @@
+import { buildParamPattern } from "./helpers";
+import { TYPED_PARAM_REGEX } from "./constants";
+/** Path validation and normalization regexes */
+export const PATH_PATTERNS = {
+    leadingSlash: /^\/+/,
+    trailingSlash: /\/+$/,
+    multipleSlashes: /\/+/g,
+    wildcardPattern: /\*+$/,
+    pathValidation: /^\/(?:[a-zA-Z0-9\-._~:/?#[\]@!$&'()*+,;=\\<>{}|^]|%[0-9A-Fa-f]{2})*$/,
+};
+/** Normalize a path string */
+export function normalizePath(path) {
+    if (path === "")
+        return "/";
+    if (path === undefined || path === null || typeof path !== "string") {
+        throw new Error("Path must be a non-empty string");
+    }
+    let normalized = path.trim();
+    if (!PATH_PATTERNS.leadingSlash.test(normalized)) {
+        normalized = "/" + normalized;
+    }
+    if (normalized.length > 1) {
+        normalized = normalized.replace(PATH_PATTERNS.trailingSlash, "");
+    }
+    normalized = normalized.replace(PATH_PATTERNS.multipleSlashes, "/");
+    return normalized || "/";
+}
+/** Join two paths safely */
+export function joinPaths(basePath, subPath) {
+    const normalizedBase = normalizePath(basePath);
+    const normalizedSub = normalizePath(subPath);
+    if (normalizedSub === "/")
+        return normalizedBase;
+    return normalizedBase === "/"
+        ? normalizedSub
+        : normalizedBase + normalizedSub;
+}
+/** Validate path format */
+export function isValidPath(path) {
+    return PATH_PATTERNS.pathValidation.test(path);
+}
+/**
+ * Compile a route pattern.
+ * Supports:
+ *  - :param           → standard param
+ *  - :param<type>     → typed param (number, uuid, enum, …)
+ *  - :param(regex)    → inline regex constraint
+ *  - *                → single segment wildcard
+ *  - **               → multi-segment wildcard
+ */
+export function compileRoutePattern(path, options) {
+    const paramNames = [];
+    const paramConstraints = {};
+    const parts = [];
+    let lastIndex = 0;
+    let match;
+    TYPED_PARAM_REGEX.lastIndex = 0;
+    while ((match = TYPED_PARAM_REGEX.exec(path)) !== null) {
+        if (match.index > lastIndex) {
+            parts.push({
+                type: "static",
+                value: path.substring(lastIndex, match.index),
+            });
+        }
+        const [full, paramName, typeExpr, inlineRegex] = match;
+        paramNames.push(paramName);
+        let pattern = "([^/]+)";
+        if (inlineRegex) {
+            paramConstraints[paramName] = {
+                name: paramName,
+                type: "regex",
+                options: inlineRegex,
+            };
+            pattern = `(${inlineRegex})`;
+        }
+        else if (typeExpr) {
+            const { pattern: p, constraint } = buildParamPattern(typeExpr);
+            paramConstraints[paramName] = {
+                name: paramName,
+                type: constraint,
+            };
+            pattern = `(${p})`;
+        }
+        parts.push({ type: "param", value: pattern });
+        lastIndex = match.index + full.length;
+    }
+    if (lastIndex < path.length) {
+        parts.push({
+            type: "static",
+            value: path.substring(lastIndex),
+        });
+    }
+    let patternStr = parts
+        .map((p) => {
+        if (p.type === "static") {
+            let s = p.value;
+            if (PATH_PATTERNS.wildcardPattern.test(s)) {
+                const wildcardMatch = s.match(/\*+$/);
+                if (wildcardMatch) {
+                    const wc = wildcardMatch[0].length;
+                    const base = s.slice(0, -wc);
+                    const escapedBase = base.replace(/[*+?^${}()|[\]\\]/g, "\\$&");
+                    if (wc === 1) {
+                        paramNames.push("*");
+                        return escapedBase + "([^/]+)";
+                    }
+                    else {
+                        paramNames.push("**");
+                        return escapedBase + "(.*)";
+                    }
+                }
+            }
+            return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+        return p.value;
+    })
+        .join("");
+    if (!options.strict && !patternStr.endsWith("/?")) {
+        patternStr += "/?";
+    }
+    const flags = options.caseSensitive ? "" : "i";
+    const pattern = new RegExp(`^${patternStr}$`, flags);
+    return { pattern, paramNames, paramConstraints };
+}
+//# sourceMappingURL=path.js.map

package/dist/src/server/routing/modules/path.js.map

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