Registry / http-networking / find-my-way-ts

find-my-way-ts

library0.1.6jsnpmunverified

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.

http-networking web-framework

npm install find-my-way-ts

github ↗package ↗

INSTALL

IMPORT

SIG · FIND-MY-WAY-TS

find-my-way-ts

http-networkingjavascriptv0.1.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

findMyWay

✓ import { findMyWay } from 'find-my-way-ts';

✗ const findMyWay = require('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

✓ import type { HTTPMethod } from 'find-my-way-ts';

✗ import { 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

✓ import type { Handler } from 'find-my-way-ts';

✗ import { Handler } from 'find-my-way-ts';

This is a TypeScript type definition for route handlers. Use `import type`.

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`); });

Debug

Known issues

breakingAs 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"`).

affects: >=0.1.0

gotchaOlder 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.

affects: <0.1.6

gotchaEarly 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.

affects: <0.1.4

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.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: (0 , find_my_way_ts__WEBPACK_IMPORTED_MODULE_0__.findMyWay) is not a function

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

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'.

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

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.

Upgrade

Version history

0.1.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/tim-smart/find-my-way-ts ↗

packagehttps://www.npmjs.com/package/find-my-way-ts ↗