router-http 1.0.13 → 2.0.0

package/README.md

@@ -4,117 +4,200 @@
 [![Coverage Status](https://img.shields.io/coveralls/Kikobeats/router-http.svg?style=flat-square)](https://coveralls.io/github/Kikobeats/router-http)
 [![NPM Status](https://img.shields.io/npm/dm/router-http.svg?style=flat-square)](https://www.npmjs.org/package/router-http)
 
-A middleware style router, similar to [express@router](https://github.com/pillarjs/router), plus:
+- [router-http](#router-http)
+  - [Why not Express router?](#why-not-express-router)
+  - [Installation](#installation)
+  - [Getting Started](#getting-started)
+    - [Declaring routes](#declaring-routes)
+    - [Declaring middlewares](#declaring-middlewares)
+    - [Starting the server](#starting-the-server)
+  - [Advanced](#advanced)
+    - [Request object](#request-object)
+    - [Print routes](#print-routes)
+    - [Nested routers](#nested-routers)
+    - [Skipping to parent router](#skipping-to-parent-router)
+  - [Benchmark](#benchmark)
+  - [Related](#related)
+  - [License](#license)
 
-- Faster (~30% more requests per second than Express).
-- Maintained and well tested.
-- Smaller (1.8 kB).
 
-Don't get me wrong: The original Express router is a piece of art. I used it for years and I just considered create this library after experienced a bug that never was addressed in the stable version due to the [lack of maintenance](https://github.com/pillarjs/router/pull/60).
+A middleware-style router similar to [express router](https://github.com/pillarjs/router), with key advantages:
 
-While I was evaluating the market for finding an alternative, I found [polka](https://github.com/lukeed/polka/tree/master/packages/polka) was a good starting point for creating a replacement. This library is different from polka in that it only contains the code that is strictly necessary for routing, nothing else.
+- **Predictable performance** – Backed by [find-my-way](https://github.com/delvedor/find-my-way), a trie-based router with constant O(1) lookup time.
+- **Battle-tested** – Well maintained with comprehensive test coverage.
+- **Lightweight** – Only 1.3 kB (minifized + gzipped)
 
-## Install
+## Why not Express router?
+
+Express uses regex-based route matching that degrades linearly as routes increase:
+
+| Routes | `express@router` | `router-http` |
+|--------|-----------|---------------|
+| 5      | ~10.7M ops/sec | **~13.7M ops/sec** |
+| 10     | ~6.5M ops/sec | **~13.7M ops/sec** |
+| 50     | ~1.5M ops/sec | **~11.5M ops/sec** |
+| 1000   | ~41K ops/sec | **~10.6M ops/sec** |
+
+In contrast, **router-http** is backed by a trie-based implementation that maintains nearly constant performance regardless of the number of routes.
+
+## Installation
 
 ```bash
-$ npm install router-http --save
+npm install router-http
 ```
 
-## Usage
+## Getting Started
 
-First, you should to create a router:
+First, define a handler for errors and unmatched routes:
 
 ```js
 const createRouter = require('router-http')
 
-const router = createRouter((error, req, res) => {
-  const hasError = error !== undefined
-  res.statusCode = hasError ? error.statusCode ?? 500 : 404
-  res.end(hasError ? error.message ?? 'Internal Server Error' : 'Not Found')
-})
+const finalHandler = (error, req, res) => {
+  if (error) {
+    res.statusCode = 500
+    res.end(error.message)
+  } else {
+    res.statusCode = 404
+    res.end('Not Found')
+  }
+}
+
+const router = createRouter(finalHandler)
 ```
 
-The router requires a final handler that will be called if an error occurred or none of the routes match.
+You can also pass [find-my-way options](https://github.com/delvedor/find-my-way#options) as a second argument:
+
+```js
+const router = createRouter(finalHandler, {
+  caseSensitive: false,
+  ignoreTrailingSlash: true
+})
+```
 
 ### Declaring routes
 
-The routes are declared using HTTP verbs:
+Use HTTP verb methods to define your routes:
 
 ```js
-/**
- * Declaring multiple routes based on the HTTP verb.
- */
 router
-  .get('/', (req, res) => {
-    res.statusCode = 204
-    res.end()
-  })
-  .post('/ping', (req, res) => res.end('pong'))
-  .get('/greetings/:name', (req, res) => {
-    const { name } = req.params
-    res.end(`Hello, ${name}!`)
-  })
+  .get('/', (req, res) => res.end('Hello World'))
+  .post('/users', (req, res) => res.end('User created'))
+  .put('/users/:id', (req, res) => res.end('User updated'))
+  .delete('/users/:id', (req, res) => res.end('User deleted'))
 ```
 
-Alternatively, you can call `.all` for associate a route for all the verbs:
+Use `.all()` to match any HTTP method:
 
 ```js
-/**
- * Declaring a route to match all the HTTP verbs.
- */
 router.all('/ping', (req, res) => res.end('pong'))
 ```
 
+The dynamic segments will be captured using the `:param` syntax, with parameters accessible via `req.params`:
+
+```js
+router.get('/users/:id', (req, res) => {
+  res.end(`User ID: ${req.params.id}`)
+})
+
+router.get('/posts/:year/:month', (req, res) => {
+  const { year, month } = req.params
+  res.end(`Posts from ${month}/${year}`)
+})
+```
+
+See [Request object](#request-object) for details on how to access route parameters and other useful properties added to `req`.
+
 ### Declaring middlewares
 
-A middleware can be declared at root level:
+A middleware is declared using `.use()`. it will be added globally before running any route:
 
 ```js
-/**
- * Declaring a middleware that will be always executed.
- */
+// Global middleware (runs on every request)
 router
-  .use('/', (req, res, next) => {
+  .use((req, res, next) => {
     req.timestamp = Date.now()
     next()
-  })
+})
 ```
 
-or for specific routes:
+You can also declare middleware specific to routes:
 
 ```js
-/**
- * Declaring a middleware to execute for a certain route path.
- */
+const auth = (req, res, next) => { /* verify token */ next() }
+const log = (req, res, next) => { /* log request */ next() }
+
+const protected = [auth, log]
+
 router
-  .use('/greetings', (req, res, next) => {
-    req.greetings = 'Greetings'
-    next()
-  })
-  .get('/greetings/:username', (req, res) => {
-    res.end(`${req.greetings}, ${req.params.username}`)
-  })
+  .get('/admin', protected, (req, res) => res.end('Admin panel'))
+  .get('/settings', protected, (req, res) => res.end('Settings'))
 ```
 
-Also, you can declare conditional middlewares:
+If you want to add a middleware conditionally, just return a falsy value:
 
 ```js
-/**
- * Just add the middleware if it's production environment
- */
 router
-  .use(process.env.NODE_ENV === 'production' && authentication())
+  .use(process.env.NODE_ENV === 'production' && rateLimiter())
 ```
 
-They are only will add if the condition is satisfied.
+### Starting the server
 
-Middlewares always run **before** route handlers, regardless of declaration order. This means you can declare `.use()` before or after `.get()` / `.post()` / etc., and the middleware will still execute first.
+The router is a standard request handler. Pass it to `http.createServer`:
 
-### Nested routers
+```js
+const http = require('http')
 
-You can use a router as a middleware for another router. This is useful for prefixing routes or for modularizing your application.
+console.log(router.prettyPrint())
+// └── / (GET)
+//     ├── favicon.ico (GET)
+//     └── user/
+//         └── :id (GET)
 
-When a sub-router is used as a middleware, it will only handle requests that match its prefix. If no route matches inside the sub-router, it will automatically call `next()` to pass control back to the parent router.
+http.createServer(router).listen(3000)
+```
+
+## Advanced
+
+### Request object
+
+The router adds these properties to `req`:
+
+| Property | Description |
+|----------|-------------|
+| `req.path` | URL pathname |
+| `req.params` | Route parameters object |
+| `req.query` | Raw query string (after `?`) |
+| `req.search` | Raw search string (including `?`) |
+
+> `req.query` and `req.search` are only set if not already present.
+
+### Print routes
+
+You can visualize your router's routes in a readable tree format using the `router.prettyPrint()` method. This is especially helpful for debugging or understanding your route structure at a glance.
+
+For example:
+
+```js
+const http = require('http')
+
+console.log(router.prettyPrint())
+// └── / (GET)
+//     ├── favicon.ico (GET)
+//     └── user/
+//         └── :id (GET)
+
+http.createServer(router).listen(3000)
+```
+
+The printed output shows the nested structure of your routes along with their registered HTTP methods. This works for both flat and deeply nested routers, including those mounted via `.use()`.
+
+See more in [find-my-way prettyPrint documentation](https://github.com/delvedor/find-my-way#routerprettyprint).
+
+
+### Nested routers
+
+You can use a router as a middleware for another router. This is useful for prefixing routes or for modularizing your application:
 
 ```js
 const createRouter = require('router-http')
@@ -144,47 +227,29 @@ router
 http.createServer(router).listen(3000)
 ```
 
-#### Exit Current Router
+When a sub-router is used as a middleware, it will only handle requests that match its prefix. If no route matches inside the sub-router, it will automatically call `next()` to pass control back to the parent router.
+
+### Skipping to parent router
 
-You can use `next('router')` to skip all remaining handlers in the current router and pass control back to the parent router. This is useful for conditional routing, such as a "Beta" router that only handles requests for certain users:
+Use `next('router')` to exit the current router and pass control back to the parent:
 
 ```js
-const beta = createRouter(final)
+const beta = createRouter(finalHandler)
 
-// Middleware to check if the user is a beta tester
 beta.use((req, res, next) => {
   if (!req.isBetaTester) return next('router')
   next()
 })
 
-beta.get('/search', (req, res) => {
-  res.end('Using the new AI-powered search engine!')
-})
-
-const router = createRouter(final)
+beta.get('/feature', (req, res) => res.end('Beta feature'))
 
-// Mount the beta router
 router.use('/v1', beta)
-
-// This will be reached if:
-// 1. The user is NOT a beta tester (next('router') was called)
-// 2. Or the path didn't match anything inside the beta router
-router.get('/v1/search', (req, res) => {
-  res.end('Using the classic search engine.')
-})
-```
-
-### Using the router
-
-After the router has been initialized, start using it as handler in your Node.js server:
-
-```js
-const server = http.createServer(router)
+router.get('/v1/feature', (req, res) => res.end('Stable feature'))
 ```
 
 ## Benchmark
 
-With all the improvements, router-http is approximately 30% faster than the express router:
+With all the improvements, **router-http** is approximately 30% faster than the express router:
 
 **express@5.2.1**
 
@@ -212,19 +277,16 @@ Requests/sec: 102751.65
 Transfer/sec:     12.84MB
 ```
 
-See more details, check [benchmark](/benchmark) section.
+See [benchmark](/benchmark) for details.
 
 ## Related
 
-- [send-http](https://github.com/Kikobeats/send-http) – A `res.end` with data type detection.
-- [http-body](https://github.com/Kikobeats/http-body) – Parse the http.IncomingMessage body into text/json/buffer.
-- [http-compression](https://github.com/Kikobeats/http-compression) – Adding compression (gzip/brotli) for your HTTP server in Node.js.
+- [send-http](https://github.com/Kikobeats/send-http) – `res.end` with data type detection
+- [http-body](https://github.com/Kikobeats/http-body) – Parse request body to text/json/buffer
+- [http-compression](https://github.com/Kikobeats/http-compression) – Gzip/Brotli compression middleware
 
 ## License
 
-Full credits to [Luke Edwards](https://github.com/lukeed) for writing [Polka](https://github.com/lukeed/polka) and inspired this project.
-
-**router-http** © [Kiko Beats](https://kikobeats.com), released under the [MIT](https://github.com/Kikobeats/router-http/blob/master/LICENSE.md) License.<br>
-Authored and maintained by [Kiko Beats](https://kikobeats.com) with help from [contributors](https://github.com/Kikobeats/router-http/contributors).
+**router-http** © [Kiko Beats](https://kikobeats.com), released under the [MIT](https://github.com/Kikobeats/router-http/blob/master/LICENSE.md) License.
 
-> [kikobeats.com](https://kikobeats.com) · GitHub [Kiko Beats](https://github.com/Kikobeats) · X [@Kikobeats](https://x.com/Kikobeats)
+Credits to [Luke Edwards](https://github.com/lukeed) for [Polka](https://github.com/lukeed/polka) which inspired this project.

package/package.json

@@ -2,7 +2,7 @@
   "name": "router-http",
   "description": "Simple HTTP router compatible with Express",
   "homepage": "https://github.com/Kikobeats/router-http",
-  "version": "1.0.13",
+  "version": "2.0.0",
   "main": "src/index.js",
   "author": {
     "email": "josefrancisco.verdu@gmail.com",
@@ -29,8 +29,8 @@
     "routes"
   ],
   "dependencies": {
-    "null-prototype-object": "~1.2.5",
-    "trouter": "~4.0.0"
+    "find-my-way": "~9.3.0",
+    "null-prototype-object": "~1.2.5"
   },
   "devDependencies": {
     "@commitlint/cli": "latest",
@@ -55,19 +55,6 @@
   "files": [
     "src"
   ],
-  "scripts": {
-    "clean": "rm -rf node_modules",
-    "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
-    "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
-    "lint": "standard",
-    "postrelease": "npm run release:tags && npm run release:github && (ci-publish || npm publish --access=public)",
-    "prerelease": "npm run contributors",
-    "pretest": "npm run lint",
-    "release": "standard-version -a",
-    "release:github": "github-generate-release",
-    "release:tags": "git push --follow-tags origin HEAD:master",
-    "test": "c8 ava"
-  },
   "license": "MIT",
   "commitlint": {
     "extends": [
@@ -91,5 +78,18 @@
   "simple-git-hooks": {
     "commit-msg": "npx commitlint --edit",
     "pre-commit": "npx nano-staged"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules",
+    "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
+    "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
+    "lint": "standard",
+    "postrelease": "npm run release:tags && npm run release:github && (ci-publish || npm publish --access=public)",
+    "prerelease": "npm run contributors",
+    "pretest": "npm run lint",
+    "release": "standard-version -a",
+    "release:github": "github-generate-release",
+    "release:tags": "git push --follow-tags origin HEAD:master",
+    "test": "c8 ava"
   }
-}
+}

package/src/index.js

@@ -1,161 +1,242 @@
 'use strict'
 
 const NullProtoObj = require('null-prototype-object')
-const { Trouter } = require('trouter')
+const FindMyWay = require('find-my-way')
+
+const HTTP_METHODS = [
+  'get',
+  'post',
+  'put',
+  'patch',
+  'delete',
+  'head',
+  'options',
+  'trace',
+  'connect'
+]
+
+const SLASH_CHAR_CODE = 47
+const SYNC_ITERATION_LIMIT = 100
 
 const requiredFinalHandler = () => {
   throw new TypeError('You should to provide a final handler')
 }
 
-/**
- * ensure input starts with '/'
- */
-const lead = route => (route.charCodeAt(0) === 47 ? route : `/${route}`)
+const ensureLeadingSlash = route =>
+  route.charCodeAt(0) === SLASH_CHAR_CODE ? route : `/${route}`
 
-const value = x => {
-  const y = x.indexOf('/', 1)
-  return y > 1 ? x.substring(0, y) : x
+const getFirstPathSegment = pathname => {
+  const secondSlashIndex = pathname.indexOf('/', 1)
+  return secondSlashIndex > 1
+    ? pathname.substring(0, secondSlashIndex)
+    : pathname
 }
 
-const parse = ({ url }) => {
-  const index = url.indexOf('?', 1)
-  if (index === -1) return { pathname: url, query: null, search: null }
-  const search = url.substring(index)
+const parseUrl = ({ url }) => {
+  const queryIndex = url.indexOf('?', 1)
+  if (queryIndex === -1) {
+    return { pathname: url, query: null, search: null }
+  }
+  const search = url.substring(queryIndex)
   return {
-    pathname: url.substring(0, index),
+    pathname: url.substring(0, queryIndex),
     query: search.substring(1),
     search
   }
 }
 
-const mutate = (str, req) => {
-  req.url = req.url.substring(str.length) || '/'
-  req.path = req.path.substring(str.length) || '/'
+const mutateRequestUrl = (prefix, req) => {
+  req.url = req.url.substring(prefix.length) || '/'
+  req.path = req.path.substring(prefix.length) || '/'
 }
 
-class Router extends Trouter {
-  constructor (unhandler) {
-    super()
-    this.unhandler = unhandler
+module.exports = (finalhandler = requiredFinalHandler(), options = {}) => {
+  const router = FindMyWay({
+    ...options,
+    defaultRoute: (req, res) => finalhandler(undefined, req, res)
+  })
+
+  const globalMiddlewares = []
+  const middlewaresByPath = new NullProtoObj()
+
+  const findRoute = (method, path, constraints) => {
+    const result = router.find(method, path, constraints)
+    if (result === null) {
+      return { params: {}, handlers: [] }
+    }
+    return { params: result.params, handlers: result.handler.handlers }
   }
 
-  /**
-   * Middleware per all routes
-   */
-  #middlewares = []
-
-  /**
-   * Middleware for specific routes
-   */
-  #middlewaresBy = new NullProtoObj()
-
-  /**
-   * Middleware declaration, where the page is optional
-   * .use(one)
-   * .use('/v1', one)
-   * .use(one, two)
-   * .use('/v2', two)
-   */
-  use = (page = '/', ...fns) => {
-    if (typeof page === 'function' || typeof page === 'boolean') {
-      this.#middlewares = this.#middlewares.concat(page, fns).filter(Boolean)
-    } else if (page === '/') {
-      this.#middlewares = this.#middlewares.concat(fns).filter(Boolean)
-    } else {
-      page = lead(page)
-      fns.filter(Boolean).forEach(fn => {
-        const array = this.#middlewaresBy[page] ?? []
-        if (array.length === 0) {
-          array.push((r, _, nxt) => {
-            mutate(page, r)
-            nxt()
-          })
-        }
-        this.#middlewaresBy[page] = array.concat(fn)
-      })
+  const registerRoute = (method, path, handlers) => {
+    const routeHandler = () => {}
+    routeHandler.handlers = handlers
+    router.on(method, path, routeHandler)
+  }
+
+  const addRoute = (method, path, ...handlers) => {
+    const fns = handlers.flat().filter(Boolean)
+    if (fns.length === 0) return handler
+
+    const methods = method === '' ? HTTP_METHODS : [method]
+
+    for (let i = 0; i < methods.length; i++) {
+      registerRoute(methods[i].toUpperCase(), path, fns)
     }
-    return this
+
+    return handler
   }
 
-  handler = (req, res, next) => {
-    const info = parse(req)
-    const pathname = info.pathname
+  const selectMiddleware = (
+    index,
+    globalLen,
+    pathLen,
+    globalMw,
+    pathMw,
+    routeHandlers
+  ) => {
+    if (index < globalLen) return globalMw[index]
+    if (index < globalLen + pathLen) return pathMw[index - globalLen]
+    return routeHandlers[index - globalLen - pathLen]
+  }
+
+  const handler = (req, res, next) => {
+    const urlInfo = parseUrl(req)
+    const pathname = urlInfo.pathname
     req.path = pathname
-    const route = this.find(req.method, pathname)
-    const page = value(pathname)
 
-    const m = this.#middlewares
-    const mb = this.#middlewaresBy[page]
-    const f = route.handlers.length > 0 ? route.handlers : null
+    const pathSegment = getFirstPathSegment(pathname)
+
+    let route = findRoute(req.method, pathname)
 
-    if (f) {
-      req.params = req.params
-        ? { ...req.params, ...route.params }
-        : route.params
+    if (route.handlers.length === 0 && req.method === 'HEAD') {
+      route = findRoute('GET', pathname)
+    }
+
+    const globalMw = globalMiddlewares
+    const pathMw = middlewaresByPath[pathSegment]
+    const routeHandlers = route.handlers.length > 0 ? route.handlers : null
+
+    if (routeHandlers !== null) {
+      req.params =
+        req.params !== undefined
+          ? { ...req.params, ...route.params }
+          : route.params
     } else {
       req.params = req.params || {}
     }
 
-    req.search = req.query || info.search
-    req.query = req.query || info.query
+    req.search = req.query || urlInfo.search
+    req.query = req.query || urlInfo.query
 
     let index = 0
-    let sync = 0
+    let syncCount = 0
 
-    const mLen = m.length
-    const mbLen = mb ? mb.length : 0
-    const fLen = f ? f.length : 0
-    const total = mLen + mbLen + fLen
+    const globalLen = globalMw.length
+    const pathLen = pathMw !== undefined ? pathMw.length : 0
+    const routeLen = routeHandlers !== null ? routeHandlers.length : 0
+    const totalMiddlewares = globalLen + pathLen + routeLen
 
-    const _next = err => {
+    const handleNext = err => {
       if (err === 'router') {
-        if (next) return next()
-        index = total
+        if (next !== undefined) return next()
+        index = totalMiddlewares
         err = undefined
       }
-      if (err) return this.unhandler(err, req, res, next)
-      if (++sync > 100) {
-        sync = 0
-        return setImmediate(loop)
+      if (err !== undefined) return finalhandler(err, req, res, next)
+      if (++syncCount > SYNC_ITERATION_LIMIT) {
+        syncCount = 0
+        return setImmediate(executeLoop)
       }
-      loop()
+      executeLoop()
     }
 
-    const loop = () => {
-      if (index < total) {
+    const executeLoop = () => {
+      if (index < totalMiddlewares) {
         if (res.writableEnded) return
-        const i = index++
-        const mware =
-          i < mLen
-            ? m[i]
-            : i < mLen + mbLen
-              ? mb[i - mLen]
-              : f[i - mLen - mbLen]
+
+        const currentIndex = index++
+        const middleware = selectMiddleware(
+          currentIndex,
+          globalLen,
+          pathLen,
+          globalMw,
+          pathMw,
+          routeHandlers
+        )
 
         try {
-          const result = mware(req, res, _next)
-          if (result && typeof result.then === 'function') {
-            return result.then(undefined, _next)
+          const result = middleware(req, res, handleNext)
+          if (
+            result !== null &&
+            result !== undefined &&
+            typeof result.then === 'function'
+          ) {
+            result.then(undefined, handleNext)
           }
         } catch (err) {
-          return _next(err)
+          handleNext(err)
         }
         return
       }
 
       if (res.writableEnded) return
+      if (next !== undefined) return next()
+      finalhandler(undefined, req, res, handleNext)
+    }
+
+    executeLoop()
+  }
 
-      if (next) return next()
+  handler.use = (path = '/', ...fns) => {
+    if (typeof path === 'function' || typeof path === 'boolean') {
+      const middlewares = [path, ...fns].filter(Boolean)
+      for (let i = 0; i < middlewares.length; i++) {
+        globalMiddlewares.push(middlewares[i])
+      }
+    } else if (path === '/') {
+      const middlewares = fns.filter(Boolean)
+      for (let i = 0; i < middlewares.length; i++) {
+        globalMiddlewares.push(middlewares[i])
+      }
+    } else {
+      const normalizedPath = ensureLeadingSlash(path)
+      const middlewares = fns.filter(Boolean)
+
+      if (middlewares.length > 0) {
+        let pathMiddlewares = middlewaresByPath[normalizedPath]
+
+        if (pathMiddlewares === undefined) {
+          pathMiddlewares = []
+          pathMiddlewares.push((req, _, next) => {
+            mutateRequestUrl(normalizedPath, req)
+            next()
+          })
+          middlewaresByPath[normalizedPath] = pathMiddlewares
+        }
 
-      this.unhandler(undefined, req, res, _next)
+        for (let i = 0; i < middlewares.length; i++) {
+          pathMiddlewares.push(middlewares[i])
+        }
+      }
     }
+    return handler
+  }
+
+  handler.all = addRoute.bind(null, '')
 
-    loop()
+  for (let i = 0; i < HTTP_METHODS.length; i++) {
+    const method = HTTP_METHODS[i]
+    handler[method] = addRoute.bind(null, method)
   }
-}
 
-module.exports = (finalhandler = requiredFinalHandler()) => {
-  const router = new Router(finalhandler)
-  const handler = (req, res, next) => router.handler(req, res, next)
-  return Object.assign(handler, router)
+  handler.del = handler.delete
+
+  handler.prettyPrint = (...args) => router.prettyPrint(...args)
+
+  Object.defineProperty(handler, 'routes', {
+    get: () => router.routes,
+    enumerable: true
+  })
+
+  return handler
 }