Find My Way HTTP Router

Common errors

• TypeError: router.lookup is not a function

  cause The `find-my-way` module was imported or required but not instantiated correctly. For example, `require('find-my-way')` returns a constructor function, not an instance directly.
  fix Ensure you instantiate the router after importing/requiring it: `const FindMyWay = require('find-my-way'); const router = FindMyWay();` or `import FindMyWay from 'find-my-way'; const router = new FindMyWay();`.

• Error: Route already registered for method 'GET' with path '/some/path'

  cause Attempting to register the same HTTP method and path combination more than once without using constraints (like versioning or host-based routing).
  fix Check for duplicate route registrations. If intentional, use constraints (`{ constraints: { version: '1.0.0' } }`) or ensure paths are unique. For example, `router.on('GET', '/path', handler1)` and `router.on('GET', '/path', handler2)` will cause this error.

• 404 Not Found (for a path that seems to match a registered route)

  cause This often occurs due to trailing slash mismatch. For instance, a route for `/users` won't match a request for `/users/` if `ignoreTrailingSlash` is not enabled.
  fix Initialize the router with `ignoreTrailingSlash: true` if you want paths with and without trailing slashes to resolve to the same route. Alternatively, register both `/users` and `/users/` explicitly.

Warnings

• breaking The behavior of parameter objects changed in `v9.0.0`. Previously, route parameters might have been regular objects, but they are now 'null objects' (objects created with `Object.create(null)`). This can affect assumptions about prototype chain or methods like `hasOwnProperty` if not accounted for.
  Fix: Ensure your code handles route parameter objects as 'null objects', particularly when using `Object.prototype` methods. Use `Object.prototype.hasOwnProperty.call(params, key)` if checking for own properties.
• breaking Node.js version requirements were increased in `v9.0.0`, dropping support for older Node.js runtimes. The package now requires Node.js version 20 or higher.
  Fix: Upgrade your Node.js environment to version 20 or newer to use `find-my-way` v9.x and above. Refer to your project's `engines` field in `package.json`.
• breaking A security vulnerability (CVE-2024-45813 / GHSA-rrr8-f88r-h8q6) related to a ReDoS (Regular Expression Denial of Service) in multiparametric routes was patched in `v8.2.2` and `v9.0.1`. This could lead to excessive CPU consumption with specifically crafted URLs.
  Fix: Upgrade `find-my-way` to `v9.0.1` or `v8.2.2` (or subsequent versions) immediately to mitigate the ReDoS vulnerability.
• gotcha By default, `find-my-way` invokes a `defaultRoute` for badly formatted URLs (e.g., `/hello/%world`). If not explicitly handled, this might result in a generic 404.
  Fix: Configure the `onBadUrl` option when instantiating the router to provide custom error handling for malformed paths, or ensure your `defaultRoute` gracefully handles such cases. Example: `const router = FindMyWay({ onBadUrl: (path, req, res) => { res.statusCode = 400; res.end(`Bad path: ${path}`); } })`.
• gotcha Trailing slashes are not ignored by default. A route registered for `/foo` will not match `/foo/`.
  Fix: Initialize the router with `ignoreTrailingSlash: true` option to make `/foo` and `/foo/` resolve to the same route. Example: `const router = FindMyWay({ ignoreTrailingSlash: true })`.
• gotcha Node.js `http.METHODS` was updated in Node 22.2.0 to include 'QUERY'. If running an older Node.js version with routes using 'QUERY', it might not be recognized.
  Fix: If using Node.js <22.2.0, avoid the 'QUERY' HTTP method. Upgrade to `find-my-way` `v9.1.0` or newer if using Node.js 22.2.0+ and leveraging the 'QUERY' method.

Install

• npm install find-my-way npm
• yarn add find-my-way yarn
• pnpm add find-my-way pnpm

Imports

• FindMyWay
  wrong:

  import { FindMyWay } from 'find-my-way';

  correct:

  import FindMyWay from 'find-my-way';
  const router = new FindMyWay();

  The default export is typically a class constructor. While `require('find-my-way')()` works for CommonJS, modern ESM/TypeScript usage often involves `new FindMyWay()` or calling the default export directly as a function that returns an instance. Fastify uses `new FindMyWay()` for instantiation.
• FindMyWayOptions
  wrong:

  import { FindMyWayOptions } from 'find-my-way';

  correct:

  import type { FindMyWayOptions } from 'find-my-way';

  Imports for types should use `import type` to ensure they are stripped from the JavaScript output, preventing runtime errors or unnecessary bundle size.
• CommonJS require
  wrong:

  const { FindMyWay } = require('find-my-way');

  correct:

  const FindMyWay = require('find-my-way');
  const router = FindMyWay();

  For CommonJS, `require('find-my-way')` returns the constructor function directly, which is then typically called without `new` to create an instance, as shown in the package's own usage examples. `new` also works.

Quickstart

Demonstrates basic HTTP server creation, defining GET and POST routes, handling route parameters, and using `find-my-way`'s `lookup` method to dispatch incoming requests.

const http = require('http')
const FindMyWay = require('find-my-way')
const router = FindMyWay()

router.on('GET', '/', (req, res, params) => {
  res.end('{"message":"hello world"}')
})

router.on('GET', '/user/:id', (req, res, params) => {
  res.end(`{"message":"hello user ${params.id}"}`)
})

router.on('POST', '/data', (req, res) => {
  let body = ''
  req.on('data', chunk => { body += chunk })
  req.on('end', () => {
    res.end(`Received data: ${body}`)
  })
})

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

server.listen(3000, err => {
  if (err) throw err
  console.log('Server listening on: http://localhost:3000')
  console.log('Try visiting http://localhost:3000 and http://localhost:3000/user/123')
  console.log('Or curl -X POST -d "test" http://localhost:3000/data')
})