route-recognizer

What is route-recognizer?

The route-recognizer npm package is a lightweight JavaScript library for recognizing and handling URL routes. It is commonly used in client-side applications to manage navigation and routing, allowing developers to map URLs to specific handlers or actions.

What are route-recognizer's main functionalities?

Adding Routes

This feature allows you to add routes to the router. In the code sample, a route is added that matches URLs of the form '/posts/:id' and associates them with a handler named 'postHandler'. The recognize method is then used to match a URL against the added routes.

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

router.add([{ path: '/posts/:id', handler: 'postHandler' }]);
console.log(router.recognize('/posts/123'));

Recognizing Routes

This feature allows you to recognize and extract parameters from URLs. In the code sample, a route is added that matches URLs of the form '/users/:userId'. The recognize method is used to match a URL and extract the userId parameter.

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

router.add([{ path: '/users/:userId', handler: 'userHandler' }]);
const result = router.recognize('/users/42');
console.log(result[0].handler); // 'userHandler'
console.log(result[0].params); // { userId: '42' }

Generating URLs

This feature allows you to generate URLs from route names and parameters. In the code sample, a route is added with a name 'product'. The generate method is used to create a URL for the route by providing the necessary parameters.

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

router.add([{ path: '/products/:productId', handler: 'productHandler', name: 'product' }]);
const url = router.generate('product', { productId: '567' });
console.log(url); // '/products/567'

Other packages similar to route-recognizer

react-router

React Router is a popular routing library for React applications. It provides a comprehensive solution for managing navigation and routing in React apps, including nested routes, dynamic routing, and route transitions. Compared to route-recognizer, React Router is more feature-rich and specifically designed for React.

express

Express is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications. It includes a powerful routing system that can handle complex URL patterns and HTTP methods. While Express is a full-fledged web framework, route-recognizer is a lightweight library focused solely on URL recognition and routing.

page

Page.js is a small client-side routing library that can be used to create single-page applications. It provides a simple API for defining routes and handling navigation. Compared to route-recognizer, Page.js is more focused on client-side routing and includes additional features like middleware support.

README

About

route-recognizer is a lightweight JavaScript library (under 2k!) that can be used as the recognizer for a more comprehensive router system (such as router.js).

In keeping with the Unix philosophy, it is a modular library that does one thing and does it well.

Usage

Create a new router:

var router = new RouteRecognizer();

Add a simple new route description:

router.add([{ path: "/posts", handler: handler }]);

Every route can optionally have a name:

router.add([{ path: "/posts", handler: handler }], { as: "routeName"});

The handler is an opaque object with no specific meaning to route-recognizer. A module using route-recognizer could use functions or other objects with domain-specific semantics for what to do with the handler.

A route description can have handlers at various points along the path:

router.add([
  { path: "/admin", handler: admin },
  { path: "/posts", handler: posts }
]);

Recognizing a route will return a list of the handlers and their associated parameters:

var result = router.recognize("/admin/posts");
result === [
  { handler: admin, params: {} },
  { handler: posts, params: {} }
];

Dynamic segments:

router.add([
  { path: "/posts/:id", handler: posts },
  { path: "/comments", handler: comments }
]);

result = router.recognize("/posts/1/comments");
result === [
  { handler: posts, params: { id: "1" } },
  { handler: comments, params: {} }
];

A dynamic segment matches any character but /.

Star segments:

router.add([{ path: "/pages/*path", handler: page }]);

result = router.recognize("/pages/hello/world");
result === [{ handler: page, params: { path: "hello/world" } }];

Sorting

If multiple routes all match a path, route-recognizer will pick the one with the fewest dynamic segments:

router.add([{ path: "/posts/edit", handler: editPost }]);
router.add([{ path: "/posts/:id", handler: showPost }]);
router.add([{ path: "/posts/new", handler: newPost }]);

var result1 = router.recognize("/posts/edit");
result1 === [{ handler: editPost, params: {} }];

var result2 = router.recognize("/posts/1");
result2 === [{ handler: showPost, params: { id: "1" } }];

var result3 = router.recognize("/posts/new");
result3 === [{ handler: newPost, params: {} }];

As you can see, this has the expected result. Explicit static paths match more closely than dynamic paths.

This is also true when comparing star segments and other dynamic segments. The recognizer will prefer fewer star segments and prefer using them for less of the match (and, consequently, using dynamic and static segments for more of the match).

Building / Running Tests

This project uses Ember CLI and Broccoli for building and testing.

Getting Started

Run the following commands to get going:

npm install
bower install

The above assumes that you have bower installed globally (you can install via npm install -g bower if you do not).

Running Tests

Run the following:

npm start

At this point you can navigate to the url specified in the Testem UI (usually http://localhost:7357/). As you change the project the tests will rerun.

Building

npm run build