@jsango/router 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JSango contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @jsango/router
+
+> High-performance Segment Radix Trie router (>7.7M ops/sec), typed constraints, route groups, and RFC 7231 compliance.
+
+Part of the **[jsango](https://github.com/jsango/jsango)** backend framework for TypeScript.
+
+## Installation
+
+```bash
+pnpm add @jsango/router
+```
+
+## Usage
+
+```typescript
+import { Router } from '@jsango/router';
+
+const router = new Router();
+router.get('/users/:id<number>', (ctx) => ({ id: ctx.request.params.id }));
+router.compile();
+```
+
+## Documentation
+
+For full architecture documentation and guides, visit the [jsango documentation](https://github.com/jsango/jsango/tree/main/docs).
+
+## License
+
+MIT © jsango contributors

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { RouterError, DuplicateRouteError, DuplicateRouteNameError, InvalidRoutePatternError, RouterLockedError, RouteNotFoundError, type BuiltinConstraint, type RouteConstraintDefinition, type CompiledConstraint, resolveConstraint, Route, type RouteHandler, type RouteOptions, type RouteMatch, type MethodNotAllowedMatch, type NotFoundMatch, type RouteMatchResult, isRouteMatch, isMethodNotAllowedMatch, isNotFoundMatch, RouteGroup, type RouteGroupConfig, type RouteGroupOptions, type IRouter, Router, type RouterState, } from './public/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAGlB,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,iBAAiB,EAGjB,KAAK,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EAGjB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,YAAY,EACZ,uBAAuB,EACvB,eAAe,EAGf,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAGtB,KAAK,OAAO,EACZ,MAAM,EACN,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { 
+// Errors
+RouterError, DuplicateRouteError, DuplicateRouteNameError, InvalidRoutePatternError, RouterLockedError, RouteNotFoundError, resolveConstraint, 
+// Route & Handlers
+Route, isRouteMatch, isMethodNotAllowedMatch, isNotFoundMatch, 
+// Groups
+RouteGroup, Router, } from './public/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO;AACL,SAAS;AACT,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAMlB,iBAAiB;AAEjB,mBAAmB;AACnB,KAAK,EASL,YAAY,EACZ,uBAAuB,EACvB,eAAe;AAEf,SAAS;AACT,UAAU,EAMV,MAAM,GAEP,MAAM,mBAAmB,CAAC"}

package/dist/internal/path-utils.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizePath(path: string): string;
+export declare function joinPaths(prefix: string, path: string): string;
+export declare function splitSegments(path: string): string[];
+export declare function safeDecodeParam(value: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/internal/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../src/internal/path-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBlD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ9D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMpD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/internal/path-utils.js

@@ -0,0 +1,40 @@
+export function normalizePath(path) {
+    if (!path || path === '/') {
+        return '/';
+    }
+    // Ensure leading slash
+    let normalized = path.startsWith('/') ? path : `/${path}`;
+    // Collapse multiple slashes (e.g. //a///b/ -> /a/b/)
+    normalized = normalized.replace(/\/+/g, '/');
+    // Strip trailing slash if length > 1
+    if (normalized.length > 1 && normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+export function joinPaths(prefix, path) {
+    const normPrefix = normalizePath(prefix);
+    const normPath = normalizePath(path);
+    if (normPrefix === '/')
+        return normPath;
+    if (normPath === '/')
+        return normPrefix;
+    return `${normPrefix}${normPath}`;
+}
+export function splitSegments(path) {
+    const normalized = normalizePath(path);
+    if (normalized === '/') {
+        return [];
+    }
+    return normalized.slice(1).split('/');
+}
+export function safeDecodeParam(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        // If malformed percent encoding occurs, return raw string gracefully
+        return value;
+    }
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/internal/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../src/internal/path-utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QAC1B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,uBAAuB;IACvB,IAAI,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAE1D,qDAAqD;IACrD,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE7C,qCAAqC;IACrC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,IAAY;IACpD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAErC,IAAI,UAAU,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC;IACxC,IAAI,QAAQ,KAAK,GAAG;QAAE,OAAO,UAAU,CAAC;IAExC,OAAO,GAAG,UAAU,GAAG,QAAQ,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/internal/radix-node.d.ts

@@ -0,0 +1,20 @@
+import type { HttpMethod } from '@jsango/http';
+import type { Route } from '../public/route.js';
+import type { CompiledConstraint } from '../public/constraints.js';
+export interface ParamChild {
+    readonly paramName: string;
+    readonly constraintDef?: string | undefined;
+    readonly constraint?: CompiledConstraint | undefined;
+    readonly node: RadixNode;
+}
+export interface WildcardChild {
+    readonly paramName: string;
+    readonly node: RadixNode;
+}
+export declare class RadixNode {
+    readonly staticChildren: Map<string, RadixNode>;
+    readonly paramChildren: ParamChild[];
+    wildcardChild: WildcardChild | null;
+    readonly routes: Map<HttpMethod, Route>;
+}
+//# sourceMappingURL=radix-node.d.ts.map

package/dist/internal/radix-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"radix-node.d.ts","sourceRoot":"","sources":["../../src/internal/radix-node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED,qBAAa,SAAS;IAEpB,SAAgB,cAAc,yBAAgC;IAG9D,SAAgB,aAAa,EAAE,UAAU,EAAE,CAAM;IAG1C,aAAa,EAAE,aAAa,GAAG,IAAI,CAAQ;IAGlD,SAAgB,MAAM,yBAAgC;CACvD"}

package/dist/internal/radix-node.js

@@ -0,0 +1,11 @@
+export class RadixNode {
+    // O(1) hash map for static string segments
+    staticChildren = new Map();
+    // Prioritized array: constrained params evaluated before unconstrained params
+    paramChildren = [];
+    // Terminal wildcard capturing the remainder of the path
+    wildcardChild = null;
+    // Registered HTTP routes at this node
+    routes = new Map();
+}
+//# sourceMappingURL=radix-node.js.map

package/dist/internal/radix-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"radix-node.js","sourceRoot":"","sources":["../../src/internal/radix-node.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAO,SAAS;IACpB,2CAA2C;IAC3B,cAAc,GAAG,IAAI,GAAG,EAAqB,CAAC;IAE9D,8EAA8E;IAC9D,aAAa,GAAiB,EAAE,CAAC;IAEjD,wDAAwD;IACjD,aAAa,GAAyB,IAAI,CAAC;IAElD,sCAAsC;IACtB,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAC;CACvD"}

package/dist/internal/radix-tree.d.ts

@@ -0,0 +1,14 @@
+import type { HttpMethod } from '@jsango/http';
+import type { Route } from '../public/route.js';
+import type { RouteMatchResult } from '../public/result.js';
+export declare class RadixTree {
+    private readonly root;
+    private readonly staticRouteMap;
+    private _isLocked;
+    get isLocked(): boolean;
+    lock(): void;
+    insert(route: Route): void;
+    private insertSegments;
+    search(method: HttpMethod, rawPath: string): RouteMatchResult;
+}
+//# sourceMappingURL=radix-tree.d.ts.map

package/dist/internal/radix-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"radix-tree.d.ts","sourceRoot":"","sources":["../../src/internal/radix-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAW5D,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6C;IAC5E,OAAO,CAAC,SAAS,CAAS;IAE1B,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAEM,IAAI,IAAI,IAAI;IAIZ,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAgDjC,OAAO,CAAC,cAAc;IAkGf,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB;CAgKrE"}

package/dist/internal/radix-tree.js

@@ -0,0 +1,272 @@
+import { RadixNode } from './radix-node.js';
+import { resolveConstraint } from '../public/constraints.js';
+import { DuplicateRouteError, InvalidRoutePatternError, RouterLockedError, } from '../public/errors.js';
+import { normalizePath, splitSegments, safeDecodeParam } from './path-utils.js';
+const EMPTY_PARAMS = Object.freeze({});
+export class RadixTree {
+    root = new RadixNode();
+    staticRouteMap = new Map();
+    _isLocked = false;
+    get isLocked() {
+        return this._isLocked;
+    }
+    lock() {
+        this._isLocked = true;
+    }
+    insert(route) {
+        if (this._isLocked) {
+            throw new RouterLockedError();
+        }
+        const path = normalizePath(route.path);
+        // Track pure static routes for O(1) matching fast path
+        if (!path.includes(':') && !path.includes('*') && !path.includes('?')) {
+            let methodMap = this.staticRouteMap.get(path);
+            if (!methodMap) {
+                methodMap = new Map();
+                this.staticRouteMap.set(path, methodMap);
+            }
+            if (methodMap.has(route.method)) {
+                throw new DuplicateRouteError(route.method, route.path);
+            }
+            methodMap.set(route.method, route);
+        }
+        // Check for optional parameter at the end (e.g. /users/:id? or /users/:id<number>? or /:id?)
+        if (path.includes('?')) {
+            const match = path.match(/^(.*?)\/:([a-zA-Z0-9_]+)(?:<(.+?)>)?\?$/);
+            if (match) {
+                const basePath = match[1] || '/';
+                const paramName = match[2];
+                const constraintPart = match[3] ? `<${match[3]}>` : '';
+                // Insert branch without optional param
+                this.insertSegments(splitSegments(basePath), route, []);
+                // Insert branch with optional param
+                const fullChildPath = basePath === '/'
+                    ? `/:${paramName}${constraintPart}`
+                    : `${basePath}/:${paramName}${constraintPart}`;
+                this.insertSegments(splitSegments(fullChildPath), route, [paramName]);
+                return;
+            }
+            throw new InvalidRoutePatternError(path, 'Optional parameters are only supported as the trailing segment (e.g. /path/:id?).');
+        }
+        const segments = splitSegments(path);
+        const paramNames = [];
+        this.insertSegments(segments, route, paramNames);
+    }
+    insertSegments(segments, route, extractedParamNames) {
+        let current = this.root;
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            // Wildcard segment (*path)
+            if (segment.startsWith('*')) {
+                if (i !== segments.length - 1) {
+                    throw new InvalidRoutePatternError(route.path, 'Wildcard segments must appear at the end of the route path.');
+                }
+                const wildcardName = segment.slice(1) || 'wildcard';
+                extractedParamNames.push(wildcardName);
+                if (!current.wildcardChild) {
+                    current.wildcardChild = {
+                        paramName: wildcardName,
+                        node: new RadixNode(),
+                    };
+                }
+                current = current.wildcardChild.node;
+                continue;
+            }
+            // Parameter segment (:param or :param<constraint>)
+            if (segment.startsWith(':')) {
+                let paramName = segment.slice(1);
+                let constraint;
+                let constraintKey;
+                // Check for inline constraint syntax :id<number>
+                const constraintMatch = paramName.match(/^([a-zA-Z0-9_]+)<(.+)>$/);
+                if (constraintMatch) {
+                    paramName = constraintMatch[1];
+                    const constraintDef = constraintMatch[2];
+                    constraint = resolveConstraint(constraintDef);
+                    constraintKey = constraintDef;
+                }
+                else if (route.constraints[paramName]) {
+                    const rawConstraint = route.constraints[paramName];
+                    constraint = resolveConstraint(rawConstraint);
+                    constraintKey = typeof rawConstraint === 'string' ? rawConstraint : 'custom';
+                }
+                extractedParamNames.push(paramName);
+                // Check existing param child with same name and constraint
+                const existingChild = current.paramChildren.find((c) => c.paramName === paramName && c.constraintDef === constraintKey);
+                if (!existingChild) {
+                    const newNode = new RadixNode();
+                    const newChild = {
+                        paramName,
+                        constraintDef: constraintKey,
+                        constraint,
+                        node: newNode,
+                    };
+                    // Prioritize: constrained parameters come before unconstrained ones
+                    if (constraint) {
+                        const firstUnconstrainedIdx = current.paramChildren.findIndex((c) => !c.constraint);
+                        if (firstUnconstrainedIdx === -1) {
+                            current.paramChildren.push(newChild);
+                        }
+                        else {
+                            current.paramChildren.splice(firstUnconstrainedIdx, 0, newChild);
+                        }
+                    }
+                    else {
+                        current.paramChildren.push(newChild);
+                    }
+                    current = newNode;
+                }
+                else {
+                    current = existingChild.node;
+                }
+                continue;
+            }
+            // Static segment
+            let nextNode = current.staticChildren.get(segment);
+            if (!nextNode) {
+                nextNode = new RadixNode();
+                current.staticChildren.set(segment, nextNode);
+            }
+            current = nextNode;
+        }
+        // Terminal node
+        if (current.routes.has(route.method)) {
+            throw new DuplicateRouteError(route.method, route.path);
+        }
+        current.routes.set(route.method, route);
+    }
+    search(method, rawPath) {
+        const pathname = normalizePath(rawPath);
+        // O(1) Fast path for pure static routes
+        const staticRoutes = this.staticRouteMap.get(pathname);
+        if (staticRoutes) {
+            const exactRoute = staticRoutes.get(method);
+            if (exactRoute) {
+                return {
+                    type: 'MATCHED',
+                    route: exactRoute,
+                    handler: exactRoute.handler,
+                    params: EMPTY_PARAMS,
+                    metadata: exactRoute.metadata,
+                };
+            }
+            if (method === 'HEAD') {
+                const getRoute = staticRoutes.get('GET');
+                if (getRoute) {
+                    return {
+                        type: 'MATCHED',
+                        route: getRoute,
+                        handler: getRoute.handler,
+                        params: EMPTY_PARAMS,
+                        metadata: getRoute.metadata,
+                        isHeadFallback: true,
+                    };
+                }
+            }
+            const allowed = new Set(staticRoutes.keys());
+            if (staticRoutes.has('GET')) {
+                allowed.add('HEAD');
+            }
+            return {
+                type: 'METHOD_NOT_ALLOWED',
+                allowedMethods: Object.freeze(Array.from(allowed)),
+                pathname,
+            };
+        }
+        const segments = splitSegments(pathname);
+        // Search algorithm with strict deterministic precedence:
+        // Static > Constrained Param > Generic Param > Wildcard
+        function findNode(node, index, collectedParams) {
+            // If all segments consumed
+            if (index === segments.length) {
+                // Must have at least one route registered or wildcard
+                if (node.routes.size > 0) {
+                    return { node, params: collectedParams };
+                }
+                // If node has wildcard child with empty match
+                if (node.wildcardChild && node.wildcardChild.node.routes.size > 0) {
+                    return {
+                        node: node.wildcardChild.node,
+                        params: { ...collectedParams, [node.wildcardChild.paramName]: '' },
+                    };
+                }
+                return null;
+            }
+            const segment = segments[index];
+            // 1. Static match (Highest Priority)
+            const staticChild = node.staticChildren.get(segment);
+            if (staticChild) {
+                const res = findNode(staticChild, index + 1, collectedParams);
+                if (res)
+                    return res;
+            }
+            // 2. Parameter match (Constrained params are ordered before generic params)
+            for (const paramChild of node.paramChildren) {
+                if (paramChild.constraint && !paramChild.constraint(segment)) {
+                    continue;
+                }
+                const decoded = safeDecodeParam(segment);
+                const nextParams = { ...collectedParams, [paramChild.paramName]: decoded };
+                const res = findNode(paramChild.node, index + 1, nextParams);
+                if (res)
+                    return res;
+            }
+            // 3. Wildcard match (Lowest Priority)
+            if (node.wildcardChild) {
+                const remainder = segments.slice(index).map(safeDecodeParam).join('/');
+                const nextParams = {
+                    ...collectedParams,
+                    [node.wildcardChild.paramName]: remainder,
+                };
+                if (node.wildcardChild.node.routes.size > 0) {
+                    return { node: node.wildcardChild.node, params: nextParams };
+                }
+            }
+            return null;
+        }
+        const candidate = findNode(this.root, 0, {});
+        if (!candidate) {
+            return {
+                type: 'NOT_FOUND',
+                pathname,
+            };
+        }
+        const { node, params } = candidate;
+        // 1. Exact HTTP method match
+        const exactRoute = node.routes.get(method);
+        if (exactRoute) {
+            return {
+                type: 'MATCHED',
+                route: exactRoute,
+                handler: exactRoute.handler,
+                params: Object.freeze(params),
+                metadata: exactRoute.metadata,
+            };
+        }
+        // 2. HEAD fallback: RFC 7231 allows automatic fallback to GET handler
+        if (method === 'HEAD') {
+            const getRoute = node.routes.get('GET');
+            if (getRoute) {
+                return {
+                    type: 'MATCHED',
+                    route: getRoute,
+                    handler: getRoute.handler,
+                    params: Object.freeze(params),
+                    metadata: getRoute.metadata,
+                    isHeadFallback: true,
+                };
+            }
+        }
+        // 3. Method Not Allowed (405)
+        const allowed = new Set(node.routes.keys());
+        if (node.routes.has('GET')) {
+            allowed.add('HEAD');
+        }
+        return {
+            type: 'METHOD_NOT_ALLOWED',
+            allowedMethods: Object.freeze(Array.from(allowed)),
+            pathname,
+        };
+    }
+}
+//# sourceMappingURL=radix-tree.js.map

package/dist/internal/radix-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"radix-tree.js","sourceRoot":"","sources":["../../src/internal/radix-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAA2B,MAAM,0BAA0B,CAAC;AACtF,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEhF,MAAM,YAAY,GAAqC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAEzE,MAAM,OAAO,SAAS;IACH,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;IACvB,cAAc,GAAG,IAAI,GAAG,EAAkC,CAAC;IACpE,SAAS,GAAG,KAAK,CAAC;IAE1B,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAEM,IAAI;QACT,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAEM,MAAM,CAAC,KAAY;QACxB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,iBAAiB,EAAE,CAAC;QAChC,CAAC;QAED,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEvC,uDAAuD;QACvD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACtE,IAAI,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,SAAS,GAAG,IAAI,GAAG,EAAqB,CAAC;gBACzC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAC3C,CAAC;YACD,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBAChC,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1D,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QAED,6FAA6F;QAC7F,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;YACpE,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;gBACjC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;gBAC5B,MAAM,cAAc,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,uCAAuC;gBACvC,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;gBACxD,oCAAoC;gBACpC,MAAM,aAAa,GACjB,QAAQ,KAAK,GAAG;oBACd,CAAC,CAAC,KAAK,SAAS,GAAG,cAAc,EAAE;oBACnC,CAAC,CAAC,GAAG,QAAQ,KAAK,SAAS,GAAG,cAAc,EAAE,CAAC;gBACnD,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;gBACtE,OAAO;YACT,CAAC;YACD,MAAM,IAAI,wBAAwB,CAChC,IAAI,EACJ,mFAAmF,CACpF,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IACnD,CAAC;IAEO,cAAc,CAAC,QAAkB,EAAE,KAAY,EAAE,mBAA6B;QACpF,IAAI,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;QAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;YAE7B,2BAA2B;YAC3B,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC9B,MAAM,IAAI,wBAAwB,CAChC,KAAK,CAAC,IAAI,EACV,6DAA6D,CAC9D,CAAC;gBACJ,CAAC;gBAED,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC;gBACpD,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;gBAEvC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;oBAC3B,OAAO,CAAC,aAAa,GAAG;wBACtB,SAAS,EAAE,YAAY;wBACvB,IAAI,EAAE,IAAI,SAAS,EAAE;qBACtB,CAAC;gBACJ,CAAC;gBACD,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC;gBACrC,SAAS;YACX,CAAC;YAED,mDAAmD;YACnD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,IAAI,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBACjC,IAAI,UAA0C,CAAC;gBAC/C,IAAI,aAAiC,CAAC;gBAEtC,iDAAiD;gBACjD,MAAM,eAAe,GAAG,SAAS,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;gBACnE,IAAI,eAAe,EAAE,CAAC;oBACpB,SAAS,GAAG,eAAe,CAAC,CAAC,CAAE,CAAC;oBAChC,MAAM,aAAa,GAAG,eAAe,CAAC,CAAC,CAAE,CAAC;oBAC1C,UAAU,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;oBAC9C,aAAa,GAAG,aAAa,CAAC;gBAChC,CAAC;qBAAM,IAAI,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;oBACxC,MAAM,aAAa,GAAG,KAAK,CAAC,WAAW,CAAC,SAAS,CAAE,CAAC;oBACpD,UAAU,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;oBAC9C,aAAa,GAAG,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAC/E,CAAC;gBAED,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAEpC,2DAA2D;gBAC3D,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAC9C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,aAAa,KAAK,aAAa,CACtE,CAAC;gBAEF,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnB,MAAM,OAAO,GAAG,IAAI,SAAS,EAAE,CAAC;oBAChC,MAAM,QAAQ,GAAG;wBACf,SAAS;wBACT,aAAa,EAAE,aAAa;wBAC5B,UAAU;wBACV,IAAI,EAAE,OAAO;qBACd,CAAC;oBAEF,oEAAoE;oBACpE,IAAI,UAAU,EAAE,CAAC;wBACf,MAAM,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;wBACpF,IAAI,qBAAqB,KAAK,CAAC,CAAC,EAAE,CAAC;4BACjC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;wBACvC,CAAC;6BAAM,CAAC;4BACN,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;wBACnE,CAAC;oBACH,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACvC,CAAC;oBACD,OAAO,GAAG,OAAO,CAAC;gBACpB,CAAC;qBAAM,CAAC;oBACN,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC;gBAC/B,CAAC;gBACD,SAAS;YACX,CAAC;YAED,iBAAiB;YACjB,IAAI,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACnD,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,SAAS,EAAE,CAAC;gBAC3B,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAChD,CAAC;YACD,OAAO,GAAG,QAAQ,CAAC;QACrB,CAAC;QAED,gBAAgB;QAChB,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1D,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAEM,MAAM,CAAC,MAAkB,EAAE,OAAe;QAC/C,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QAExC,wCAAwC;QACxC,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC5C,IAAI,UAAU,EAAE,CAAC;gBACf,OAAO;oBACL,IAAI,EAAE,SAAS;oBACf,KAAK,EAAE,UAAU;oBACjB,OAAO,EAAE,UAAU,CAAC,OAAO;oBAC3B,MAAM,EAAE,YAAY;oBACpB,QAAQ,EAAE,UAAU,CAAC,QAAQ;iBAC9B,CAAC;YACJ,CAAC;YAED,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACtB,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACzC,IAAI,QAAQ,EAAE,CAAC;oBACb,OAAO;wBACL,IAAI,EAAE,SAAS;wBACf,KAAK,EAAE,QAAQ;wBACf,OAAO,EAAE,QAAQ,CAAC,OAAO;wBACzB,MAAM,EAAE,YAAY;wBACpB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;wBAC3B,cAAc,EAAE,IAAI;qBACrB,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAa,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;YACzD,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;YAED,OAAO;gBACL,IAAI,EAAE,oBAAoB;gBAC1B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAClD,QAAQ;aACT,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QAOzC,yDAAyD;QACzD,wDAAwD;QACxD,SAAS,QAAQ,CACf,IAAe,EACf,KAAa,EACb,eAAuC;YAEvC,2BAA2B;YAC3B,IAAI,KAAK,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAC9B,sDAAsD;gBACtD,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;oBACzB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;gBAC3C,CAAC;gBACD,8CAA8C;gBAC9C,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;oBAClE,OAAO;wBACL,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI;wBAC7B,MAAM,EAAE,EAAE,GAAG,eAAe,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE;qBACnE,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAE,CAAC;YAEjC,qCAAqC;YACrC,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrD,IAAI,WAAW,EAAE,CAAC;gBAChB,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC,EAAE,eAAe,CAAC,CAAC;gBAC9D,IAAI,GAAG;oBAAE,OAAO,GAAG,CAAC;YACtB,CAAC;YAED,4EAA4E;YAC5E,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBAC5C,IAAI,UAAU,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC7D,SAAS;gBACX,CAAC;gBACD,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;gBACzC,MAAM,UAAU,GAAG,EAAE,GAAG,eAAe,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;gBAC3E,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;gBAC7D,IAAI,GAAG;oBAAE,OAAO,GAAG,CAAC;YACtB,CAAC;YAED,sCAAsC;YACtC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAEvE,MAAM,UAAU,GAAG;oBACjB,GAAG,eAAe;oBAClB,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,SAAS;iBAC1C,CAAC;gBAEF,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;oBAC5C,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;gBAC/D,CAAC;YACH,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAE7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO;gBACL,IAAI,EAAE,WAAW;gBACjB,QAAQ;aACT,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QAEnC,6BAA6B;QAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,UAAU,EAAE,CAAC;YACf,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,KAAK,EAAE,UAAU;gBACjB,OAAO,EAAE,UAAU,CAAC,OAAO;gBAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC7B,QAAQ,EAAE,UAAU,CAAC,QAAQ;aAC9B,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO;oBACL,IAAI,EAAE,SAAS;oBACf,KAAK,EAAE,QAAQ;oBACf,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;oBAC7B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;oBAC3B,cAAc,EAAE,IAAI;iBACrB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,8BAA8B;QAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAa,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtB,CAAC;QAED,OAAO;YACL,IAAI,EAAE,oBAAoB;YAC1B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClD,QAAQ;SACT,CAAC;IACJ,CAAC;CACF"}

package/dist/public/constraints.d.ts

@@ -0,0 +1,5 @@
+export type BuiltinConstraint = 'number' | 'uuid' | 'slug' | 'alpha' | 'alphanumeric';
+export type RouteConstraintDefinition = BuiltinConstraint | string | RegExp | ((value: string) => boolean);
+export type CompiledConstraint = (value: string) => boolean;
+export declare function resolveConstraint(def: RouteConstraintDefinition): CompiledConstraint;
+//# sourceMappingURL=constraints.d.ts.map

package/dist/public/constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../../src/public/constraints.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;AAEtF,MAAM,MAAM,yBAAyB,GACnC,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAUrE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE5D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,yBAAyB,GAAG,kBAAkB,CA4BpF"}

package/dist/public/constraints.js

@@ -0,0 +1,35 @@
+import { InvalidRoutePatternError } from './errors.js';
+const BUILTIN_REGEXPS = {
+    number: /^\d+$/,
+    uuid: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/,
+    slug: /^[a-z0-9_-]+$/,
+    alpha: /^[a-zA-Z]+$/,
+    alphanumeric: /^[a-zA-Z0-9]+$/,
+};
+export function resolveConstraint(def) {
+    if (typeof def === 'function') {
+        return def;
+    }
+    if (def instanceof RegExp) {
+        return (val) => {
+            def.lastIndex = 0;
+            return def.test(val);
+        };
+    }
+    if (typeof def === 'string') {
+        const builtin = BUILTIN_REGEXPS[def.toLowerCase()];
+        if (builtin) {
+            return (val) => builtin.test(val);
+        }
+        // Try custom regex string (e.g. [0-9]+ or [a-z]{2,4})
+        try {
+            const customRegex = new RegExp(`^${def}$`);
+            return (val) => customRegex.test(val);
+        }
+        catch {
+            throw new InvalidRoutePatternError(def, `Invalid constraint pattern: "${def}"`);
+        }
+    }
+    throw new InvalidRoutePatternError(String(def), 'Invalid constraint definition type.');
+}
+//# sourceMappingURL=constraints.js.map

package/dist/public/constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.js","sourceRoot":"","sources":["../../src/public/constraints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAOvD,MAAM,eAAe,GAAsC;IACzD,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,+EAA+E;IACrF,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,aAAa;IACpB,YAAY,EAAE,gBAAgB;CAC/B,CAAC;AAIF,MAAM,UAAU,iBAAiB,CAAC,GAA8B;IAC9D,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;QAC9B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,GAAG,YAAY,MAAM,EAAE,CAAC;QAC1B,OAAO,CAAC,GAAW,EAAE,EAAE;YACrB,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC;YAClB,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,WAAW,EAAuB,CAAC,CAAC;QACxE,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC;QAED,sDAAsD;QACtD,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;YAC3C,OAAO,CAAC,GAAW,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,wBAAwB,CAAC,GAAG,EAAE,gCAAgC,GAAG,GAAG,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IAED,MAAM,IAAI,wBAAwB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,qCAAqC,CAAC,CAAC;AACzF,CAAC"}

package/dist/public/errors.d.ts

@@ -0,0 +1,20 @@
+import { JsangoError, type ErrorMetadata } from '@jsango/core';
+export declare class RouterError extends JsangoError {
+    constructor(code: string, message: string, metadata?: ErrorMetadata);
+}
+export declare class DuplicateRouteError extends RouterError {
+    constructor(method: string, path: string);
+}
+export declare class DuplicateRouteNameError extends RouterError {
+    constructor(name: string, existingPath: string, newPath: string);
+}
+export declare class InvalidRoutePatternError extends RouterError {
+    constructor(path: string, reason: string);
+}
+export declare class RouterLockedError extends RouterError {
+    constructor(action?: string);
+}
+export declare class RouteNotFoundError extends RouterError {
+    constructor(name: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/public/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/public/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAE/D,qBAAa,WAAY,SAAQ,WAAW;gBAC9B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa;CASpE;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQzC;AAED,qBAAa,uBAAwB,SAAQ,WAAW;gBAC1C,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAQhE;AAED,qBAAa,wBAAyB,SAAQ,WAAW;gBAC3C,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAOzC;AAED,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,MAAM,SAAwB;CAM3C;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,IAAI,EAAE,MAAM;CAIzB"}

package/dist/public/errors.js

@@ -0,0 +1,48 @@
+import { JsangoError } from '@jsango/core';
+export class RouterError extends JsangoError {
+    constructor(code, message, metadata) {
+        super({
+            code,
+            message,
+            metadata,
+            statusCode: 500,
+        });
+        this.name = 'RouterError';
+    }
+}
+export class DuplicateRouteError extends RouterError {
+    constructor(method, path) {
+        super('ERR_ROUTER_DUPLICATE_ROUTE', `Duplicate route definition: [${method}] "${path}" is already registered.`, { method, path });
+        this.name = 'DuplicateRouteError';
+    }
+}
+export class DuplicateRouteNameError extends RouterError {
+    constructor(name, existingPath, newPath) {
+        super('ERR_ROUTER_DUPLICATE_NAME', `Duplicate route name: "${name}" is already assigned to "${existingPath}", cannot assign to "${newPath}".`, { name, existingPath, newPath });
+        this.name = 'DuplicateRouteNameError';
+    }
+}
+export class InvalidRoutePatternError extends RouterError {
+    constructor(path, reason) {
+        super('ERR_ROUTER_INVALID_PATTERN', `Invalid route pattern "${path}": ${reason}`, {
+            path,
+            reason,
+        });
+        this.name = 'InvalidRoutePatternError';
+    }
+}
+export class RouterLockedError extends RouterError {
+    constructor(action = 'register new routes') {
+        super('ERR_ROUTER_LOCKED', `Router is locked/compiled. Cannot ${action} after compilation.`, {
+            action,
+        });
+        this.name = 'RouterLockedError';
+    }
+}
+export class RouteNotFoundError extends RouterError {
+    constructor(name) {
+        super('ERR_ROUTER_NOT_FOUND', `Route with name "${name}" was not found.`, { name });
+        this.name = 'RouteNotFoundError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/public/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/public/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAsB,MAAM,cAAc,CAAC;AAE/D,MAAM,OAAO,WAAY,SAAQ,WAAW;IAC1C,YAAY,IAAY,EAAE,OAAe,EAAE,QAAwB;QACjE,KAAK,CAAC;YACJ,IAAI;YACJ,OAAO;YACP,QAAQ;YACR,UAAU,EAAE,GAAG;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IAClD,YAAY,MAAc,EAAE,IAAY;QACtC,KAAK,CACH,4BAA4B,EAC5B,gCAAgC,MAAM,MAAM,IAAI,0BAA0B,EAC1E,EAAE,MAAM,EAAE,IAAI,EAAE,CACjB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,WAAW;IACtD,YAAY,IAAY,EAAE,YAAoB,EAAE,OAAe;QAC7D,KAAK,CACH,2BAA2B,EAC3B,0BAA0B,IAAI,6BAA6B,YAAY,wBAAwB,OAAO,IAAI,EAC1G,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAChC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACvD,YAAY,IAAY,EAAE,MAAc;QACtC,KAAK,CAAC,4BAA4B,EAAE,0BAA0B,IAAI,MAAM,MAAM,EAAE,EAAE;YAChF,IAAI;YACJ,MAAM;SACP,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IAChD,YAAY,MAAM,GAAG,qBAAqB;QACxC,KAAK,CAAC,mBAAmB,EAAE,qCAAqC,MAAM,qBAAqB,EAAE;YAC3F,MAAM;SACP,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACjD,YAAY,IAAY;QACtB,KAAK,CAAC,sBAAsB,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QACpF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/public/group.d.ts

@@ -0,0 +1,29 @@
+import type { HttpMethod } from '@jsango/http';
+import { Route, type RouteHandler, type RouteOptions } from './route.js';
+import type { IRouter } from './router-interface.js';
+export interface RouteGroupConfig {
+    readonly prefix: string;
+    readonly metadata?: Record<string, unknown> | undefined;
+    readonly middleware?: readonly unknown[] | undefined;
+}
+export interface RouteGroupOptions {
+    readonly metadata?: Record<string, unknown> | undefined;
+    readonly middleware?: readonly unknown[] | undefined;
+}
+export declare class RouteGroup {
+    private readonly router;
+    readonly prefix: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly middleware: readonly unknown[];
+    constructor(router: IRouter, prefix: string, options?: RouteGroupOptions);
+    route(method: HttpMethod, path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    get(path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    post(path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    put(path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    patch(path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    delete(path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    head(path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    options(path: string, handler: RouteHandler, options?: RouteOptions): Route;
+    group(prefixOrConfig: string | RouteGroupConfig, callback: (group: RouteGroup) => void, options?: RouteGroupOptions): this;
+}
+//# sourceMappingURL=group.d.ts.map