Lightweight Route Recognizer

Common errors

• ReferenceError: RouteRecognizer is not defined

  cause The `RouteRecognizer` class was not correctly imported or required before use.
  fix For ES Modules: `import RouteRecognizer from 'route-recognizer';` For CommonJS: `const RouteRecognizer = require('route-recognizer');`

• TypeError: router.add is not a function

  cause The `router` variable is not an instance of `RouteRecognizer`. This usually happens if `new` keyword is omitted during instantiation.
  fix Ensure `RouteRecognizer` is instantiated correctly: `const router = new RouteRecognizer();`

• Error: There are no routes named `routeName`

  cause This error occurs when attempting to generate a URL by name (if the library supported it, which `route-recognizer` doesn't directly expose but a higher-level router built on top might) or if a named route was not registered. `route-recognizer` itself does not have a public API for generating paths by name; names are for identification within its internal structure or for systems built on top. The core library only recognizes paths.
  fix This specific error is unlikely to come directly from `route-recognizer` as it primarily deals with `recognize`. If encountered in a surrounding router, ensure the route name used for generation matches a registered route. For `route-recognizer` directly, verify that you are not trying to generate routes by name, but rather using `recognize` with a path string.

Warnings

• gotcha When multiple routes match a given path, `route-recognizer` prioritizes routes based on specificity: explicit static paths are preferred over dynamic segments, and fewer dynamic segments are preferred. If segments are identical, the number of handlers and then definition order are used as tiebreakers. This behavior might be unexpected if a user anticipates a different matching priority (e.g., first-defined wins).
  Fix: Always test routes with ambiguous paths to ensure they resolve as intended. Structure route definitions from most specific to least specific, if possible, to align with the recognizer's internal sorting logic.
• deprecated The `route-recognizer` package has not seen active development since its last release (0.3.4 in 2018), and its GitHub repository shows no recent commits. Development dependencies mentioned in the README (like Bower and Travis CI) are largely outdated. This indicates the library is no longer actively maintained and may not be compatible with newer JavaScript features or build environments without additional polyfills or transpilation.
  Fix: Consider alternatives for new projects. For existing projects, be aware that security updates or bug fixes are unlikely. Test thoroughly in modern environments.
• gotcha Dynamic segments (e.g., `:id`) in `route-recognizer` match any character *except* a forward slash (`/`). This means a dynamic segment will not consume subsequent path segments. For matching multiple path segments, a star segment (e.g., `*path`) should be used instead.
  Fix: Use dynamic segments (`:param`) for single path segments and star segments (`*param`) for multi-segment or trailing path matches.

Install

• npm install route-recognizer npm
• yarn add route-recognizer yarn
• pnpm add route-recognizer pnpm

Imports

• RouteRecognizer
  wrong:

  import { RouteRecognizer } from 'route-recognizer';

  correct:

  import RouteRecognizer from 'route-recognizer';

  The library uses a default export for its main class, not named export for the class itself.
• RouteRecognizer (CommonJS)
  wrong:

  const { RouteRecognizer } = require('route-recognizer');

  correct:

  const RouteRecognizer = require('route-recognizer');

  CommonJS usage aligns with the default export pattern; directly assigning the require result to the class name.
• RouteRecognizer (Type)

  import type { RouteRecognizer } from 'route-recognizer';

  For TypeScript, import the type explicitly if only type-checking is needed, although direct value import also works for both value and type.

Quickstart

This quickstart demonstrates how to instantiate RouteRecognizer, add various route patterns including dynamic and star segments, and then use the `recognize` method to match paths and retrieve associated handlers and parameters.

import RouteRecognizer from 'route-recognizer';

const router = new RouteRecognizer();

const postsHandler = (params) => `Handling posts with params: ${JSON.stringify(params)}`;
const singlePostHandler = (params) => `Handling single post with ID: ${params.id}`; 
const adminHandler = () => `Admin section accessed`;
const pageHandler = (params) => `Serving page: ${params.path}`;

router.add([{ path: "/posts", handler: postsHandler }], { as: "allPosts" });
router.add([{ path: "/posts/:id", handler: singlePostHandler }], { as: "singlePost" });
router.add([ { path: "/admin", handler: adminHandler }, { path: "/posts", handler: postsHandler } ], { as: "adminPosts" });
router.add([{ path: "/pages/*path", handler: pageHandler }], { as: "catchAllPages" });

let result = router.recognize("/posts");
console.log("Recognizing /posts:", result?.[0]?.handler(result?.[0]?.params));

result = router.recognize("/posts/123");
console.log("Recognizing /posts/123:", result?.[0]?.handler(result?.[0]?.params));

result = router.recognize("/admin/posts");
console.log("Recognizing /admin/posts:", result?.[1]?.handler(result?.[1]?.params));

result = router.recognize("/pages/about/us");
console.log("Recognizing /pages/about/us:", result?.[0]?.handler(result?.[0]?.params));