Simple HTTP Router

Common errors

• TypeError: next is not a function

  cause A middleware function was declared without the `next` argument or `next()` was called on a non-function.
  fix Ensure your middleware functions are defined with `(req, res, next)` as parameters, and `next()` is correctly invoked. Example: `router.use((req, res, next) => { /* ... */ next() })`.

• Cannot GET /some/path (or similar HTTP 404 Not Found response)

  cause The requested URL path does not match any defined route, or route matching options (case sensitivity, trailing slashes) are causing a mismatch.
  fix Verify that the route path is correctly defined and matches the incoming request, considering case sensitivity and trailing slashes. Check the `createRouter` options for `caseSensitive` and `ignoreTrailingSlash`. Example: `createRouter(finalHandler, { caseSensitive: false, ignoreTrailingSlash: true })`.

• TypeError: Cannot read properties of undefined (reading 'id') for req.params.id

  cause Attempting to access `req.params` for a route that does not have dynamic segments, or the dynamic segment name in the route definition doesn't match the one accessed in `req.params`.
  fix Ensure your route is defined with dynamic segments (e.g., `/users/:id`) if you intend to access `req.params`. Double-check that the parameter name used in `req.params.name` matches the `:name` in your route definition.

Warnings

• breaking Version 2.0.0 introduced a fundamental shift from a likely regex-based routing engine to a trie-based implementation via `find-my-way`. While the external API aims for compatibility, this change can lead to subtle behavioral differences in route matching, parameter parsing, or route prioritization, especially in complex routing scenarios or edge cases, potentially breaking assumptions made on previous versions.
  Fix: Thoroughly test existing routing logic and middleware behavior after upgrading to v2.x, paying close attention to dynamic parameters, optional segments, and conflicting routes. Consult the `find-my-way` documentation for specific routing behaviors.
• gotcha router-http is a CommonJS module, meaning `import` syntax is not natively supported for the package itself without transpilation or specific Node.js configuration (`"type": "module"` in your project's `package.json` and a default CommonJS module would cause issues). The `require()` syntax must be used to load the `createRouter` function.
  Fix: Always use `const createRouter = require('router-http')` to import the module in a CommonJS environment. If you are developing an ESM project, you might need to use dynamic `import('router-http')` or a build tool that handles CJS interoperability.
• gotcha Middleware functions require an explicit `next()` call to pass control to subsequent middleware or the final route handler. Failing to call `next()` will cause the request to hang unless `res.end()` or `res.statusCode` is explicitly set within the middleware.
  Fix: Ensure all middleware functions follow the `(req, res, next)` signature and include `next()` at the point where control should be passed. For asynchronous operations, call `next()` after the operation completes or if an error occurs (`next(error)`).
• breaking The package explicitly requires Node.js version 18 or higher. Running on older Node.js environments will result in errors or unexpected behavior due to unsupported language features or API changes.
  Fix: Upgrade your Node.js environment to version 18 or newer to meet the minimum engine requirements. Check your `package.json` `engines` field and ensure your deployment environment is compatible.

Install

• npm install router-http npm
• yarn add router-http yarn
• pnpm add router-http pnpm

Imports

• createRouter
  wrong:

  import createRouter from 'router-http'

  correct:

  const createRouter = require('router-http')

  router-http is a CommonJS module. ESM import syntax is not supported directly for the package entry point. Use `require()`.
• router.get
  wrong:

  import { get } from 'router-http'; get('/', (req, res) => { /* ... */ })

  correct:

  router.get('/', (req, res) => { /* ... */ })

  Methods like `.get()`, `.post()`, `.use()` are called on the router instance returned by `createRouter`, not directly imported.
• MiddlewareFunction
  wrong:

  router.use(async (req, res) => { /* ... */ })

  correct:

  router.use((req, res, next) => { /* ... */ next() })

  Middleware functions must accept `(req, res, next)` and explicitly call `next()` to pass control to the next middleware or route handler. Omitting `next()` or failing to call it will halt the request processing.

Quickstart

Demonstrates how to initialize router-http, define a final error/404 handler, add global middleware, declare various HTTP method routes with dynamic parameters, and start a basic Node.js HTTP server.

const http = require('http')
const createRouter = require('router-http')

const finalHandler = (error, req, res) => {
  if (error) {
    res.statusCode = error.statusCode || 500
    res.end(error.message)
  } else {
    res.statusCode = 404
    res.end('Not Found')
  }
}

const router = createRouter(finalHandler, { caseSensitive: false, ignoreTrailingSlash: true })

// Global middleware (runs on every request)
router.use((req, res, next) => {
  req.timestamp = Date.now()
  next()
})

router
  .get('/', (req, res) => res.end(`Hello World at ${req.timestamp}`))
  .post('/users', (req, res) => res.end('User created'))
  .put('/users/:id', (req, res) => res.end(`User ${req.params.id} updated`))
  .delete('/users/:id', (req, res) => res.end(`User ${req.params.id} deleted`))
  .all('/ping', (req, res) => res.end('pong'))

const server = http.createServer((req, res) => {
  router(req, res)
})

server.listen(3000, () => {
  console.log('Server listening on http://localhost:3000')
  console.log('Try visiting / or /users/123, or POST to /users')
})