TrieRouter

Kind: Class

Source: src/router/trie-router/router.ts

Part of: Router

TrieRouter stores route patterns and their handlers in a trie-based route tree. Use add() to register a method and path, then call match() to resolve an incoming method and path to a Result<T>.

Implements: Router

Methods

Properties

Diagram

mermaid
graph LR
  Route[Route registration] --> Add[add()]
  Add --> Trie[Trie route tree]
  Request[Incoming method and path] --> Match[match()]
  Match --> Trie
  Trie --> Result[Result<T>]

Usage

ts
const router = new TrieRouter<string>()

router.add('GET', '/articles/:slug', 'getArticle')
router.add('POST', '/articles', 'createArticle')

const result = router.match('GET', '/articles/intro')

// Pass result to the request dispatcher.
console.log(result)

AI Coding Instructions

• Keep the handler type consistent for every route registered in the same TrieRouter instance.
• Register routes through add() before matching requests through match().
• Pass the HTTP method and request path to match() using the same format used during registration.
• Handle the returned Result<T> in the caller that dispatches matched handlers and processes route parameters.

How it works

• TrieRouter<T> is an exported generic router class implementing Router<T>. Its public name field is "TrieRouter", and each instance initializes one private Node<T> as its route storage and matcher. src/router/trie-router/router.ts:5-11

• add(method, path, handler) registers handler for the supplied method and path by inserting it into that private node structure. This mutates the router’s stored routes and has no returned value. src/router/trie-router/router.ts:13-23 The underlying insertion splits routing paths into segments, creates child nodes as needed, and appends a method/handler entry at the terminal node. src/router/trie-router/node.ts:44-84

• Before insertion, add checks for an optional named parameter. When path ends in ? and contains :, the helper returns expanded path variants; TrieRouter inserts the same handler for every variant. src/router/trie-router/router.ts:13-20 For example, /api/animals/:type? expands to /api/animals and /api/animals/:type; a root optional parameter expands to / and its parameterized form. src/utils/url.ts:171-205 src/utils/url.test.ts:235-255

• match(method, path) delegates directly to the node search and returns Result<T>, whose concrete form here is a one-element tuple containing an array of [handler, params] pairs. src/router/trie-router/router.ts:25-27 src/router/trie-router/node.ts:114-115 src/router/trie-router/node.ts:237-244 A non-match returns that same shape with an empty handler array. src/router/trie-router/node.test.ts:14-20

• Paths support literal segments, named segments such as :id, wildcard segments (*), and named segments constrained by a regular expression such as :id{[0-9]+}. Pattern recognition is performed while adding routes. src/utils/url.ts:50-77 Named and constrained captures are returned in the parameter record. src/router/trie-router/node.ts:165-229 src/router/trie-router/node.test.ts:74-108 src/router/trie-router/node.test.ts:216-234

• A registered method is matched exactly; if no exact method entry exists at a matched route node, an entry registered as ALL is selected. src/router/trie-router/node.ts:94-110 src/router.ts:6-13 Wildcards can match the remainder of a path and also match when no further segment follows, such as /hello/* matching /hello. src/router/trie-router/node.ts:136-146 src/router/trie-router/node.ts:153-163

• Matching can return more than one handler when multiple registered routes match. Returned matches are sorted by their route insertion score, which is incremented for each insertion. src/router/trie-router/node.ts:44-46 src/router/trie-router/node.ts:237-244 For example, a literal route and a wildcard route can both be returned. src/router/trie-router/node.test.ts:125-134

• TrieRouter itself contains no explicit argument validation or explicit error handling. src/router/trie-router/router.ts:9-27 Route patterns with {...} are passed to new RegExp(...) during insertion, without a catch in the shown code. src/utils/url.ts:60-74

Relationships

• IMPORTS → checkOptionalParameter
• IMPORTS → Node