\n\n# Fast and Robust URI-router for NodeJS. [](https://github.com/prostojs/router/actions/workflows/ci.yml)\n\nThis is framework agnostic router that is [extremely fast](https://github.com/prostojs/router-benchmark/tree/main/packages/router-benchmark). It's as fast as `find-my-way` and even faster. It's written completely on TypeScript.\n\nThe aim of the router is to properly parse URI and find the handler in the shortest possible time. It doesn't have any problems with url-encoded tricky URIs. It will deliver all the params in the context. It parses params and wildcards in proper manner. It allows to use complex wildcards and parameters with regex. It does not call handlers but returns handlers. You must specify the type of handler functions yourself for your use case.\n\n### Benchmark Comparison\n\nBenchmarked against popular routers with **full route matching AND parameter extraction** per lookup.\nSee the full benchmark [here](https://github.com/prostojs/router-benchmark/tree/main/packages/router-benchmark).\n\n#### Basic benchmark (22 routes, 200k ops, 2 attempts)\n\n| Route Type | Express | find-my-way | rou3 | Hono RegExpRouter | **@prostojs/router** |\n|------------|---------|-------------|------|-------------------|----------------------|\n| Short (2-5 segments) | 2,348 | 22,374 | 32,242 | **37,863** | 36,385 |\n| Long (5-10 segments) | 1,141 | 6,283 | 7,157 | 8,250 | **9,020** |\n| Mixed (50/50) | 2,201 | 16,786 | 20,828 | **37,617** | 21,432 |\n\n*ops/ms — higher is better*\n\n#### Scaling benchmark (500k ops, 5 attempts)\n\n| Router | 22 routes | 50 routes | 100 routes | 200 routes |\n|--------|-----------|-----------|------------|------------|\n| **@prostojs/router** | 44,665 | 14,411 | 10,855 | 9,400 |\n| Hono RegExpRouter | 42,409 | 12,525 | 10,162 | 6,627 |\n| rou3 | 38,861 | 17,533 | 12,495 | 10,481 |\n| find-my-way | 29,182 | 13,038 | 13,571 | 10,804 |\n| Express | 2,393 | 994 | 654 | 295 |\n\n*ops/ms on short routes — higher is better*\n\n> **Note:** Hono's RegExpRouter fails to compile beyond ~50 deep routes, falling back to the slower TrieRouter (~3,600 ops/ms). ProstoRouter maintains strong performance across all route counts.\n\n- [Quick Start](./README.md#quick-start)\n- [Install](./README.md#install)\n- [Router options](./README.md#router-options)\n- [Handlers Type](./README.md#handlers-type)\n- [Route specific Handler Type](./README.md#route-specific-handler-type)\n- [Lookup result](./README.md#lookup-result)\n- [Lookup alias](./README.md#lookup-alias)\n- [Parametric routes](./README.md#parametric-routes)\n- [Wildcards](./README.md#wildcards)\n- [Optional Parameters](./README.md#optional-parameters)\n- [Retrieving params](./README.md#retrieving-params)\n- [Register routes shortcuts](./README.md#register-routes-shortcuts)\n- [Register all](./README.md#register-all)\n- [Path builders](./README.md#path-builders)\n\n### Quick Start\n\n```ts\nimport { ProstoRouter } from 'prosto-router'\nimport http from 'http'\n\nconst router = new ProstoRouter()\n\nrouter.on('GET', '/api/path', () => 'ok')\n\nconst server = http.createServer((req, res) => {\n const found = router.lookup(req.method, req.url)\n if (found) {\n res.end(found.route.handlers[0]())\n } else {\n res.statusCode = 404\n res.end('404 Not Found')\n }\n})\nserver.listen(3000, (err) => {\n if (err) return console.error(err)\n console.log('Server is listening 3000')\n})\n```\n\n```ts\n// `require` example\nconst { ProstoRouter } = require('@prostojs/router')\nconst http = require('http')\n\nconst router = new ProstoRouter()\n```\n\n### Install\n\n`npm install @prostojs/router`\n\n### Router options\n\n```ts\nconst router = new ProstoRouter({\n // Ignore trailing URI slash\n // (by default = false)\n ignoreTrailingSlash: false,\n\n // Ignore URI case (by default = false)\n ignoreCase: false,\n\n // By default duplicate paths are enabled,\n // the handlers are collected into an array\n disableDuplicatePath: false,\n\n // You can put any logger that implements\n // TConsoleInterface interface\n logger: ...,\n\n // Specify which log messages to see\n // (DEBUG, INFO, LOG, WARN, ERROR, NOTHING)\n logLevel: EProstoLogLevel.INFO,\n\n // enables caching of mapping of\n // incoming paths to the handlers\n // which increases the speed of routing\n // (by default 0)\n cacheLimit: 50\n})\n```\n\n### Handlers Type\n\n```ts\ntype MyHandlerType = (\n req: ClientRequest,\n res: ServerResponse,\n ctx: TProstoLookupContext,\n) => string\nconst router = new ProstoRouter()\n\nrouter.on(\n 'GET',\n '/api/path',\n (req: ClientRequest, res: ServerResponse, ctx: TProstoLookupContext) =>\n 'ok',\n)\n```\n\n### Route specific Handler Type\n\n```ts\ninterface ParamsType = {}\n\ntype MyHandlerType = (\n req: ClientRequest,\n res: ServerResponse,\n ctx: TProstoLookupContext\n) => string\n\nrouter.on(\n 'GET',\n '/api/path',\n (req: ClientRequest, res: ServerResponse, ctx: TProstoLookupContext) => 'ok'\n)\n```\n\n### Lookup result\n\nLookup returns `TProstoLookupResult | undefined`\n\n```ts\ninterface TProstoLookupResult {\n route: TProstoRoute // the matched route itself\n ctx: TProstoLookupContext // the lookup context\n // (contains params that were parsed from the URI)\n}\n```\n\n```ts\n// The real interface has more props\n// I highlight here the main props\ninterface TProstoRoute {\n // normallized path that was registered\n path: string\n\n // array of handlers in registration order\n handlers: HandlerType[]\n\n // the route has only one static segment\n // (segment is the whole url)\n isStatic: boolean\n\n // the route has at least one parameter\n // (it can have static segments as well)\n isParametric: boolean\n\n // the router has wildcard(s) and static\n // segment(s) (optionally)\n isWildcard: boolean\n}\n```\n\n```ts\ninterface TProstoLookupContext> {\n params: ParamsType // parameters from parametric routes or wildcards\n}\n```\n\n### Lookup alias\n\n`router.find` works similarly to `router.lookup`\n\n### Parametric routes\n\nParameter starts with `:`.\nIf you want to have colon in your path without defining a parameter you must escape it with backslash like so `'/api/colon\\\\:novar'`.\nParameters can be separated with hyphen like so `'/api/:key1-:key2'`\nIt's possible to specify RegExp for parameters `'/api/time/:hours(\\\\d{2})h:minutes(\\\\d{2})m'`\n\n```ts\n// simple single param\nrouter.get('/api/vars/:key', () => 'ok')\n\n// two params separated with hyphen\nrouter.get('/api/vars/:key1-:key2', () => 'ok')\n\n// two params with regex\nrouter.get('/api/time/:hours(\\\\d{2})h:minutes(\\\\d{2})m', () => 'ok')\n\n// two params separated with slash\nrouter.get('/api/user/:name1/:name2, () => 'ok')\n\n// three params with the same name (leads to an array as a value)\nrouter.get('/api/array/:name/:name/:name, () => 'ok')\n```\n\n### Wildcards\n\nWidlcard is specified with asterisk `'*'`\n\nThere are several options available:\n\n1. It can be at the beginning of path, in the middle of the path or at the end of the path.\n2. It's possible to have several wildcards.\n3. It's possible to have widlcards mixed with params.\n4. It's possible to pass regex to wildcard.\n\n```ts\n// the most common usage (will match all the URIs that\n// start with `/static/`)\nrouter.get('/static/*', () => 'ok')\n\n// will match all the URIs that start with `/static/`\n// and end with `.js`\nrouter.get('/static/*.js', () => 'ok')\n\n// will match all the URIs that start with `/static/`\n// and have `/test/` in the middle\nrouter.get('/static/*/test/*', () => 'ok')\n\n// will match all the URIs that start with `/static/[numbers]`\nrouter.get('/static/*(\\\\d+)', () => 'ok')\n```\n\n### Optional Parameters\n\nA parametric (wildcard) route can include optional parameters. If you wish to define optional parameters, they should appear at the end of the route. It is not permitted to have obligatory parameters after an optional parameter, and static segments should not appear after optional parameters, except when using `-` and `/` as separators between parameters.\n\nOptional parameters may be omitted when matching a route, and the corresponding handler will still be found.\n\n**Note:**\nA parametric route with optional parameters is treated as a wildcard during lookup, which can reduce routing performance. Please use this feature carefully.\n\nTo define a parameter (wildcard) as optional, simply add `?` at the end.\n\n```ts\n// Optional parameter\nrouter.get('/api/vars/:optionalKey?', () => 'ok')\n\n// Optional wildcard\nrouter.get('/api/vars/:*?', () => 'ok')\n\n// Several optional parameters\nrouter.get('/api/vars/:v1/:v2?/:v3?', () => 'ok')\n```\n\nIn the above example, the router allows routes with optional parameters to be defined using the `?` symbol at the end of the parameter name. For instance, `/api/vars/myKey` and `/api/vars/` are both valid routes for the first example. Similarly, the second example allows routes like `/api/vars/param1/param2` and `/api/vars/` to be matched. Lastly, the third example permits routes with one, two, or three parameters to be matched, with any combination of parameters being optional.\n\n### Retrieving params\n\n```ts\nrouter.get('/api/:key1-:key2/*/array/:name/:name/:name', () => 'ok')\nconst lookupResult = router.lookup(\n '/api/val1-val2/random/part/array/name1/name2/name3',\n)\nif (lookupResult) {\n console.log(lookupResult.ctx)\n // {\n // params: {\n // key1: 'val1',\n // key2: 'val2',\n // '*': 'random/part',\n // name: ['name1', 'name2', 'name3']\n // }\n // }\n}\n```\n\n### Register routes shortcuts\n\n```ts\nrouter.on('GET', '/api/path', () => 'ok')\n// is equal to\nrouter.get('/api/path', () => 'ok')\n\nrouter.on('POST', '/api/path', () => 'ok')\n// is equal to\nrouter.post('/api/path', () => 'ok')\n\n// and so on\nrouter.post('/api/path', () => 'ok')\nrouter.put('/api/path', () => 'ok')\nrouter.patch('/api/path', () => 'ok')\nrouter.delete('/api/path', () => 'ok')\nrouter.options('/api/path', () => 'ok')\nrouter.head('/api/path', () => 'ok')\n```\n\n### Register all\n\n```ts\nrouter.on('*', '/api/path', () => 'ok')\n// is equal to\nrouter.all('/api/path', () => 'ok')\n```\n\n### Path builders\n\nWhen you define a new route you receive a path builder for it\n\n```js\nconst { getPath: pathBuilder } = router.get('/api/path', () => 'ok')\nconsole.log(pathBuilder())\n// /api/path\n\nconst { getPath: userPathBuilder } = router.get('/api/user/:name', () => 'ok')\nconsole.log(\n userPathBuilder({\n name: 'John',\n }),\n)\n// /api/user/John\n\nconst { getPath: wildcardBuilder } = router.get('/static/*', () => 'ok')\nconsole.log(\n wildcardBuilder({\n '*': 'index.html',\n }),\n)\n// /static/index.html\n\nconst { getPath: multiParamsBuilder } = router.get(\n '/api/asset/:type/:type/:id',\n () => 'ok',\n)\nconsole.log(\n userPathBuilder({\n type: ['CJ', 'REV'],\n id: '443551',\n }),\n)\n// /api/asset/CJ/REV/443551\n```\n\n```ts\n// typescript example\ninterface MyParamsType = {\n name: string\n}\n\nconst { getPath: userPathBuilder } = router.get('/api/user/:name', () => 'ok')\n\nconsole.log(userPathBuilder({\n name: 'John'\n}))\n// /api/user/John\n```\n\n### Print tree\n\nPrint the representation of routes in tree:\n\n```js\nconst router = new ProstoRouter()\n\nrouter.on('GET', '/api/users', () => {})\nrouter.on('GET', '/api/user/:id', () => {})\nrouter.on('GET', '/api/dealers', () => {})\nrouter.on('GET', '/api/dealer/:id', () => {})\nrouter.on('GET', '/api/assets', () => {})\nrouter.on('GET', '/api/assets/:type/:id', () => {})\nrouter.on('GET', '/api/lead/a:key1-p:key2', () => {})\nrouter.on('GET', 'static/*', () => {})\nrouter.on('GET', 'static/*/styles/:filename.css', () => {})\nrouter.on('GET', '*', () => {})\n\nrouter.toTree()\n```\n\n\n","readmeFilename":"README.md"}
![](\"./docs/logo.png\"){kind=logo}
\n\n ![](\"https://img.shields.io/badge/License-MIT-red?style=for-the-badge\"){kind=icon}
\n\n![](\"./docs/router-tree.png\")
\n","readmeFilename":"README.md"}