Orientation Arc
Routing Algorithms
Rendering and JSX
Runtime Adapters
Middleware Ecosystem
Developer Helpers
System Utilities
The following files were used as context for generating this wiki page:
The RegExpRouter is a high-performance routing engine designed for speed by converting standard URL routing patterns into a single, optimized regular expression. Unlike naive routers that perform linear scans or depth-first tree traversals for every incoming request, RegExpRouter compiles the entire routing table into a regex-based matcher. This design minimizes the per-request overhead, making it particularly effective in environments where routing performance is a critical path.
The architecture relies on a Trie data structure to preprocess route definitions. During the registration phase, the router tracks path structures and converts variables (like ) and wildcards () into corresponding capturing groups. This structure is then serialized into a regular expression. When a request arrives, the router uses this single regex to identify the matching handler index in a single pass, significantly reducing the algorithmic complexity of route resolution.
:id*RegExpRouter is one of the foundational routers used within Hono. It is typically employed by the SmartRouter, which combines different routing strategies to provide the best balance of flexibility and performance. By implementing the Router interface, it remains drop-in compatible with other routing implementations, allowing developers to switch underlying engines without altering their business logic.
Before a regex can be generated, the router must organize the input paths into a Trie structure. This ensures that hierarchical path segments are handled correctly and that potential routing ambiguities are resolved. The Trie insertion logic acts as the primary registry for path segments.
When add(method, path, handler) is called:
Trie structure is updated by calling trie.insert(path, j, pathErrorCheckOnly).:id), it is handled by the trie nodes to facilitate correct index generation for the final regex output.Once all routes are registered, the RegExpRouter invokes buildMatcherFromPreprocessedRoutes. This function performs the transformation from a structured Trie to an executable RegExp instance.
The compilation process:
trie.buildRegExp() to generate a path-matching regex.match operation.The RegExpRouter separates path matching into logic for static paths and patterns. During the build process, routes are flagged via a boolean as !/\*|\/:/.test(route[0]). Routes without parameters are stored as static entries. During the match operation, these are evaluated to ensure optimal performance for standard, non-parameterized routes.
Tip
Placing frequently accessed static routes, such as /health, before dynamic routes can improve performance in high-throughput applications, as the router optimizes for these constant paths during the trie construction.
When multiple handlers might match a single path (e.g., via middleware or overlapping patterns), the router must determine the order of evaluation. The RegExpRouter uses a sorting mechanism during the build process:
.sort(([isStaticA, pathA], [isStaticB, pathB]) =>
isStaticA ? 1 : isStaticB ? -1 : pathA.length - pathB.length
)This logic ensures that routes are ordered such that static routes are favored and dynamic paths are ordered by their path length, establishing a consistent priority for pattern matching.
For static-heavy applications, RegExpRouter offers a PreparedRegExpRouter. This variant allows the matcher to be pre-built and serialized into a string. This is useful for environments (like cold-start serverless functions) where compiling the router at runtime would be too slow.
buildInitParams: Collects path data and generates the matcher.serializeInitParams: Converts the internal matcher data into a JSON string that can be safely embedded in a source file.The router enforces strict path invariants during construction. If a path is malformed (e.g., illegal segments), it throws an UnsupportedPathError.
Warning
The RegExpRouter expects well-formed paths. If you add a path that the Trie cannot represent due to internal limitations, PATH_ERROR will be thrown, causing the router to abort the build process.