find-my-way-ts Fast HTTP Router

0.1.6 · active · verified Tue Apr 21

find-my-way-ts is a highly performant, framework-independent HTTP router designed for Node.js environments, leveraging a Radix Tree (also known as a compact Prefix Tree) for extremely fast route matching. It is a TypeScript-first fork of the popular `find-my-way` router, providing enhanced type safety and improved developer experience through its explicit type definitions. Currently at version 0.1.6, the package appears to be under active development, with frequent patch releases addressing bug fixes and minor enhancements, such as improved URI error handling and `QueryString` module integration. Its primary differentiator is its speed and efficient algorithm for path resolution, supporting route parameters and wildcards, making it suitable for high-throughput HTTP servers. Its pre-1.0 status suggests a relatively fast-moving API, though the current changes are mostly iterative improvements.

Common errors

```
TypeError: (0 , find_my_way_ts__WEBPACK_IMPORTED_MODULE_0__.findMyWay) is not a function
```
cause Attempting to import `findMyWay` using CommonJS `require()` syntax or an incorrect ESM named import pattern in an environment that expects ESM.

fix Ensure you are using ESM `import { findMyWay } from 'find-my-way-ts';` and that your build/runtime environment supports ESM. If using Node.js, ensure your package.json `type` is set to `module` or use `.mjs` extension for your file.
```
URIError: URI malformed
```
cause Passing an improperly encoded or malformed URI path to the router, which earlier versions of `find-my-way-ts` did not gracefully handle.

fix Upgrade to `find-my-way-ts@0.1.6` or newer. If the issue persists with valid URIs, ensure client-side URI encoding is correct or implement custom URL sanitization before passing to the router.
```
Property 'searchParams' does not exist on type 'Route'.
```
cause Type definitions for `searchParams` on the `Route` object (or handler arguments) were incorrect or missing in older versions.

fix Upgrade to `find-my-way-ts@0.1.2` or newer, which includes a fix for `searchParams` types. Ensure your `tsconfig.json` targets a modern TypeScript version.
```
ReferenceError: Function is not defined
```
cause This error can occur in highly restricted environments (like some serverless platforms) that disallow `new Function` if using `find-my-way-ts` versions prior to `0.1.4`.

fix Upgrade to `find-my-way-ts@0.1.4` or newer. This version specifically removed the usage of `new Function` to enhance compatibility with such runtimes.

Warnings

breaking As a pre-1.0 package, the API of `find-my-way-ts` is subject to frequent changes without adhering to semantic versioning for major releases. Users should expect potential breaking changes between minor versions (e.g., 0.1.x to 0.2.x).
Fix: Always review the release notes (`CHANGELOG.md`) when upgrading and lock package versions in `package.json` to specific patch releases (e.g., `"find-my-way-ts": "~0.1.6"` or `"find-my-way-ts": "0.1.6"`).
gotcha Older versions (pre-0.1.6) might have failed or behaved unpredictably when encountering malformed URIs. The `0.1.6` release specifically addresses improved handling of invalid URI errors, suggesting previous instability.
Fix: Upgrade to `find-my-way-ts@0.1.6` or newer to benefit from improved URI error handling and stability.
gotcha Early versions (pre-0.1.4 and pre-0.1.1) used `new Function` for internal optimizations, which caused compatibility issues and performance penalties in certain serverless and edge runtimes (e.g., Cloudflare Workers, EdgeRuntime). These usages have since been removed.
Fix: Ensure you are using `find-my-way-ts@0.1.4` or newer to avoid `new Function`-related issues and ensure broader runtime compatibility.
gotcha `find-my-way-ts` is a fork of `find-my-way`. While aiming for similar functionality, there might be subtle behavioral differences or API divergences that could affect migration or expectations if you're familiar with the original package.
Fix: Refer to the `find-my-way-ts` documentation and source code for the most accurate and up-to-date API specifics and behavioral guarantees, rather than relying solely on `find-my-way` knowledge.
gotcha The original `find-my-way` library (which `find-my-way-ts` is based on) has had a ReDoS vulnerability in multiparametric routes (CVE-2024-45813). While `find-my-way-ts` may have different internal implementations, it's prudent to be aware of potential similar vulnerabilities in regex-based routing if not explicitly patched or verified.
Fix: Carefully review and test complex regex-based routes for potential ReDoS attack vectors. Monitor `find-my-way-ts`'s security advisories and ensure regular updates to mitigate known vulnerabilities.

Install

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

Imports

findMyWay
wrong:
```
const findMyWay = require('find-my-way-ts');
```
correct:
```
import { findMyWay } from 'find-my-way-ts';
```
The primary function to instantiate the router. Being a TypeScript-first package, ESM `import` is the recommended and best-supported pattern.
HTTPMethod
wrong:
```
import { HTTPMethod } from 'find-my-way-ts';
```
correct:
```
import type { HTTPMethod } from 'find-my-way-ts';
```
This is a TypeScript enum/type for HTTP methods. Use `import type` to ensure it's removed from the compiled JavaScript bundle.
Handler
wrong:
```
import { Handler } from 'find-my-way-ts';
```
correct:
```
import type { Handler } from 'find-my-way-ts';
```
This is a TypeScript type definition for route handlers. Use `import type`.

Quickstart

This quickstart sets up a basic HTTP server using `find-my-way-ts` to route incoming requests. It demonstrates GET routes with and without parameters, a POST/PUT route with body parsing, and accessing query parameters. It uses Node.js's native `http` module for server creation.

import { findMyWay } from 'find-my-way-ts';
import * as http from 'http';

const router = findMyWay();

router.on('GET', '/', (req, res, params, store, searchParams) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({ message: 'Hello from root!', params, searchParams }));
});

router.on('GET', '/user/:id', (req, res, params, store, searchParams) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({ message: `Hello user ${params.id}!`, params, searchParams }));
});

router.on(['POST', 'PUT'], '/data', (req, res, params, store, searchParams) => {
  let body = '';
  req.on('data', chunk => { body += chunk; });
  req.on('end', () => {
    res.statusCode = 200;
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify({ message: `Data received for ${req.method}!`, body: JSON.parse(body || '{}'), params, searchParams }));
  });
});

router.on('GET', '/search', (req, res, params, store, searchParams) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({ message: 'Search results!', params, searchParams, query: req.url?.split('?')[1] }));
});

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

const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
  console.log(`Server listening on http://localhost:${PORT}`);
  console.log('Try visiting:');
  console.log(`- http://localhost:${PORT}/`);
  console.log(`- http://localhost:${PORT}/user/123`);
  console.log(`- http://localhost:${PORT}/search?q=test&page=1`);
  console.log(`- curl -X POST -H "Content-Type: application/json" -d '{"item": "new"}' http://localhost:${PORT}/data`);
});

view raw JSON →