route-pattern

Generic Sinatra/Backbone style route pattern matching

route-pattern

Features

  • Environment, framework and tool agnostic. Works in both Node.js and the browser. No jQuery, Express etc. needed.
  • Match against the path, search (query string) and the hash part of a location
  • Define patterns for matching only against the parts of the location you are interested in
  • Match against a location and capture named parameters, query string, etc.
  • Well tested.
  • Create a pattern for matching against the query string part of an url
var pattern = RoutePattern.fromString("/planets/:planet")
pattern.matches("/planets/earth?fruit=apple#bookmark") // true 
var pattern = RoutePattern.fromString("?foo=:foo&fruit=:fruit")
pattern.matches("/hello/world?foo=bar&fruit=apple") // true 
pattern.matches("/ignore/what/is/here?fruit=apple&foo=bar") // true 

Path-like patterns can be used in the hash part of the route string too.

var pattern = RoutePattern.fromString("#/chapters/:chapter")
pattern.matches("#/chapters/5") // true 
pattern.matches("/books/3432?display=full#/chapters/2") // true 

By default, query string routes will match only when all speficied parameters are present in the matched location string, and they are the only query parameters in the location string. Thus, the following statement will be false:

RoutePattern.fromString("?foo=:foo").matches("?foo=bar&baz=qux") // false 

To specify that other query parameters should be allowed, add a single wildcard to the route string:

RoutePattern.fromString("?foo=:foo&*").matches("?foo=bar&baz=qux") // true 

Wildcards can also be used in the path to ignore whatever is in the place of the *

var pattern = RoutePattern.fromString("*/planets/:planet/*")
pattern.matches("/some/root/path/planets/earth/facts/about/this/planet") // true 
var pattern = RoutePattern.fromString("/hello/:planet?foo=:foo&fruit=:fruit#:section")
pattern.match("/hello/earth?foo=bar&fruit=apple#chapter2");
// Returns: 
{
  params: ["bar", "apple", ],
  namedParams: { planet: "earth", foo: "bar", fruit: "apple" }
  pathParams: { planet: "world" }
  queryParams: { foo: "bar", fruit: "apple" }
  hashParams: { section: "chapter2" }
}

Note: namedParams is a merge of pathParams, queryParams and hashParams.

var pattern = RoutePattern.fromString("*/planets/:planet/*")
pattern.match("/some/root/path/planets/earth/facts/about/this/planet") // true 
// Returns: 
{
  params: ["earth"],
  namedParams: {
    planet: "earth"
  }
  //... 
}

after the *

var pattern = RoutePattern.fromString("*/planets/:planet/*")
pattern.match("/some/root/path/planets/earth/facts/about/this/planet")
// Returns: 
{
  params: ["some/root/path","earth","facts/about/this/planet"],
  namedParams: {
    before: "some/root/path",
    planet: "earth",
    after:"facts/about/this/planet"
  }
  //... 
}

Getting started

  1. Install with npm: npm install route-pattern
  2. From your .js file: var RoutePattern = require("route-pattern");

Download latest version:

  • Development
  • Production (minified)

When included with a <script> tag, it it will expose the RoutePattern class as a global variable.

API

Returns a RoutePattern instance.

Constructor. Usually its better to use RoutePattern.fromString(routeString) instead of using this constructor directly.

Available options are:

  • pathPattern: a RoutePattern.PathPattern-instance
  • queryStringPattern: A RoutePattern.QueryStringPattern-instance,
  • hashPattern: A RoutePattern.HashStringPattern-instance,
  • queryStringPattern: A RoutePattern.QueryStringPattern-instance,
  • routeString: A reference to the original routestring (optional)

All options are optional, but to make sense, at least one of pathPattern, queryStringPattern, hashPattern or hashPattern should be given.

Matches a location string against the pattern and returns captured values (i.e. params, namedParams, queryParams, hashParams and pathParams)

Tests whether the pattern matches a given location string

Example:

RoutePattern.fromString("/foo/:bar").matches("/foo/bar/baz") // false
RoutePattern.fromString("/foo/:bar").matches("/foo/bar") // true

Future work:

  • Allow pattern matching against the full url (i.e. scheme, domain, port in addition to the currently supported parts of the url)

MIT