# route-pattern

> Generic Sinatra/Backbone style route pattern matching

Latest version **0.0.6** (published 2013-09-08) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install route-pattern
pnpm add route-pattern
yarn add route-pattern
bun add route-pattern
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.0.6 |
| Published | 2013-09-08 |
| First published | 2013-03-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 38 |
| Author | Bjørge Næss |
| Maintainers | bjoerge |
| Keywords | route, pattern |

## Links

- npm: https://www.npmjs.com/package/route-pattern
- Repository: https://github.com/bjoerge/route-pattern
- Issues: https://github.com/bjoerge/route-pattern/issues
- npm.io page: https://npm.io/package/route-pattern

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 0.0.6 (latest) — 2013-09-08
- 0.0.4 — 2013-04-23
- 0.0.3 — 2013-04-21
- 0.0.2 — 2013-03-27
- 0.0.1 — 2013-03-26

## README

# route-pattern

#### Generic route pattern matching

# Features

The most important feature of this library is that it does pattern matching and nothing, *nothing* more.

Other features are:

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

In other words, you *could* use this library to support routing in your app or framework.

### Example: matching a route against a path 

```js
var pattern = RoutePattern.fromString("/planets/:planet")
pattern.matches("/planets/earth?fruit=apple#bookmark") // true
```

### Matching a route by query string

```js
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
```

### Matching a route by location hash

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

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

### Wildcard matches 

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`:

```js
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:

```js
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 `*`

```js
var pattern = RoutePattern.fromString("*/planets/:planet/*")
pattern.matches("/some/root/path/planets/earth/facts/about/this/planet") // true
```

## Getting match data

```js
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`.

### Capturing wildcards and splats

Wildcards in the route string will ignore whatever is in the place of the `*`

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

Splat parameters is like wildcards, only that they will capture the value of the identifier that comes after the `*` 

```js
var pattern = RoutePattern.fromString("*before/planets/:planet/*after")
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

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

## Browser

This module works in all major browsers, including IE 8-10. However, it makes use of ECMAScript 5 features, so in 
order to make it work on legacy browsers, you need to include a ECMAScript 5 shim, like the [es5-shim](https://github.com/kriskowal/es5-shim). 

Download latest version:
* [Source](https://raw.github.com/bjoerge/route-pattern/master/route-pattern-standalone-0.0.3.js)
* [Minified](https://raw.github.com/bjoerge/route-pattern/master/route-pattern-standalone-0.0.3.min.js)

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

# API

### `RoutePattern.fromString(routeString)`
Compiles a route string and returns a RoutePattern instance.

### `new RoutePattern(opts)`
Constructor. Usually its better to use `RoutePattern.fromString(routeString)` instead of using the constructor directly.

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

### routePattern.matches(locationString)
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). Useful where same script resides on multiple domains.

# Changelog

## 0.0.3
  * Rename `RegexPattern` => `RegExpPattern`.
  * Make all the Pattern classes' `match()` methods  return null if there are no match.

## License

MIT

---
_Source: https://npm.io/package/route-pattern · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._