Major changes

* New feature! Ability to set `endsWith` to match paths like `/test?query=string` and ignore the query string * Remove `isarray` * Explicitly handle trailing delimiters instead of trimming them (e.g. `/test/` is now treated as `/test/` instead of `/test` when matching) * Reverse `keys` and `options` arguments - functions were previously overloaded to accept `keys` and `options` as the second argument

Author: blakeembrey

.travis.yml

@@ -1,9 +1,8 @@
+sudo: false
 language: node_js
 
 node_js:
- - "0.10"
- - "0.12"
  - "4.0"
- - "4.1"
+ - "stable"
 
 after_script: "npm install coveralls@2 && cat ./coverage/lcov.info | coveralls"

Readme.md

@@ -1,6 +1,6 @@
 # Path-to-RegExp
 
-> Turn an Express-style path string such as `/user/:name` into a regular expression.
+> Turn a path string such as `/user/:name` into a regular expression.
 
 [![NPM version][npm-image]][npm-url]
 [![Build status][travis-image]][travis-url]
@@ -20,38 +20,39 @@ npm install path-to-regexp --save
 ```javascript
 var pathToRegexp = require('path-to-regexp')
 
-// pathToRegexp(path, keys, options)
+// pathToRegexp(path, options?, keys?)
 // pathToRegexp.parse(path)
 // pathToRegexp.compile(path)
 ```
 
-- **path** An Express-style string, an array of strings, or a regular expression.
-- **keys** An array to be populated with the keys found in the path.
+- **path** A string, array of strings, or a regular expression.
 - **options**
  - **sensitive** When `true` the route will be case sensitive. (default: `false`)
  - **strict** When `false` the trailing slash is optional. (default: `false`)
  - **end** When `false` the path will match at the beginning. (default: `true`)
  - **delimiter** Set the default delimiter for repeat parameters. (default: `'/'`)
+ - **endsWith** Optional character, or list of characters, to treat as "end" characters
+- **keys** An (optional) array to be populated with the keys found in the path. (also returned as `RegExp#keys`)
 
 ```javascript
 var keys = []
-var re = pathToRegexp('/foo/:bar', keys)
+var re = pathToRegexp('/foo/:bar', null, keys)
 // re = /^\/foo\/([^\/]+?)\/?$/i
 // keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }]
 ```
 
-**Please note:** The `RegExp` returned by `path-to-regexp` is intended for use with pathnames or hostnames. It can not handle the query strings or fragments of a URL.
+**Please note:** The `RegExp` returned by `path-to-regexp` is intended for ordered data (e.g. pathnames, hostnames). It does not handle arbitrary data (e.g. query strings, URL fragments, JSON, etc).
 
 ### Parameters
 
-The path string can be used to define parameters and populate the keys.
+The path argument is used to define parameters and populate the list of keys.
 
 #### Named Parameters
 
 Named parameters are defined by prefixing a colon to the parameter name (`:foo`). By default, the parameter will match until the following path segment.
 
 ```js
-var re = pathToRegexp('/:foo/:bar', keys)
+var re = pathToRegexp('/:foo/:bar')
 // keys = [{ name: 'foo', prefix: '/', ... }, { name: 'bar', prefix: '/', ... }]
 
 re.exec('/test/route')
@@ -61,21 +62,21 @@ re.exec('/test/route')
 **Please note:** Named parameters must be made up of "word characters" (`[A-Za-z0-9_]`).
 
 ```js
-var re = pathToRegexp('/(apple-)?icon-:res(\\d+).png', keys)
+var re = pathToRegexp('/(apple-)?icon-:res(\\d+).png')
 // keys = [{ name: 0, prefix: '/', ... }, { name: 'res', prefix: '', ... }]
 
 re.exec('/icon-76.png')
 //=> ['/icon-76.png', undefined, '76']
 ```
 
-#### Modified Parameters
+#### Parameter Modifiers
 
 ##### Optional
 
-Parameters can be suffixed with a question mark (`?`) to make the parameter optional. This will also make the prefix optional.
+Parameters can be suffixed with a question mark (`?`) to make the parameter optional.
 
 ```js
-var re = pathToRegexp('/:foo/:bar?', keys)
+var re = pathToRegexp('/:foo/:bar?')
 // keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }]
 
 re.exec('/test')
@@ -85,12 +86,14 @@ re.exec('/test/route')
 //=> ['/test', 'test', 'route']
 ```
 
+**Tip:** If the parameter is the _only_ value in the segment, the prefix is also optional.
+
 ##### Zero or more
 
 Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches. The prefix is taken into account for each match.
 
 ```js
-var re = pathToRegexp('/:foo*', keys)
+var re = pathToRegexp('/:foo*')
 // keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }]
 
 re.exec('/')
@@ -105,7 +108,7 @@ re.exec('/bar/baz')
 Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches. The prefix is taken into account for each match.
 
 ```js
-var re = pathToRegexp('/:foo+', keys)
+var re = pathToRegexp('/:foo+')
 // keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }]
 
 re.exec('/')
@@ -120,7 +123,7 @@ re.exec('/bar/baz')
 All parameters can be provided a custom regexp, which overrides the default (`[^\/]+`).
 
 ```js
-var re = pathToRegexp('/:foo(\\d+)', keys)
+var re = pathToRegexp('/:foo(\\d+)')
 // keys = [{ name: 'foo', ... }]
 
 re.exec('/123')
@@ -137,7 +140,7 @@ re.exec('/abc')
 It is possible to write an unnamed parameter that only consists of a matching group. It works the same as a named parameter, except it will be numerically indexed.
 
 ```js
-var re = pathToRegexp('/:foo/(.*)', keys)
+var re = pathToRegexp('/:foo/(.*)')
 // keys = [{ name: 'foo', ... }, { name: 0, ... }]
 
 re.exec('/test/route')
@@ -149,7 +152,7 @@ re.exec('/test/route')
 An asterisk can be used for matching everything. It is equivalent to an unnamed matching group of `(.*)`.
 
 ```js
-var re = pathToRegexp('/foo/*', keys)
+var re = pathToRegexp('/foo/*')
 // keys = [{ name: '0', ... }]
 
 re.exec('/foo/bar/baz')
@@ -173,11 +176,11 @@ console.log(tokens[2])
 //=> { name: 0, prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '.*' }
 ```
 
-**Note:** This method only works with Express-style strings.
+**Note:** This method only works with strings.
 
 ### Compile ("Reverse" Path-To-RegExp)
 
-Path-To-RegExp exposes a compile function for transforming an Express-style path into a valid path.
+Path-To-RegExp exposes a compile function for transforming a string into a valid path.
 
 ```js
 var toPath = pathToRegexp.compile('/user/:id')
@@ -225,10 +228,8 @@ Path-To-RegExp exposes the two functions used internally that accept an array of
 
 Path-To-RegExp breaks compatibility with Express <= `4.x`:
 
-* No longer a direct conversion to a RegExp with sugar on top - it's a path matcher with named and unnamed matching groups
- * It's unlikely you previously abused this feature, it's rare and you could always use a RegExp instead
-* All matching RegExp special characters can be used in a matching group. E.g. `/:user(.*)`
- * Other RegExp features are not support - no nested matching groups, non-capturing groups or look aheads
+* RegExp special characters can only be used in a parameter
+ * Express.js 4.x used all `RegExp` special characters regardless of position - this considered a bug
 * Parameters have suffixes that augment meaning - `*`, `+` and `?`. E.g. `/:user*`
 
 ## TypeScript

index.d.ts

@@ -1,5 +1,4 @@
-declare function pathToRegexp (path: pathToRegexp.Path, options?: pathToRegexp.RegExpOptions & pathToRegexp.ParseOptions): pathToRegexp.PathRegExp;
-declare function pathToRegexp (path: pathToRegexp.Path, keys?: pathToRegexp.Key[], options?: pathToRegexp.RegExpOptions & pathToRegexp.ParseOptions): pathToRegexp.PathRegExp;
+declare function pathToRegexp (path: pathToRegexp.Path, options?: pathToRegexp.RegExpOptions & pathToRegexp.ParseOptions, keys?: pathToRegexp.Key[]): pathToRegexp.PathRegExp;
 
 declare namespace pathToRegexp {
  export interface PathRegExp extends RegExp {
@@ -24,6 +23,10 @@ declare namespace pathToRegexp {
  * Sets the final character for non-ending optimistic matches. (default: `/`)
  */
  delimiter?: string;
+ /**
+ * List of characters that can also be "end" characters.
+ */
+ endsWith?: string | string[];
  }
 
  export interface ParseOptions {
@@ -51,8 +54,7 @@ declare namespace pathToRegexp {
  /**
  * Transform an array of tokens into a matching regular expression.
  */
- export function tokensToRegExp (tokens: Token[], options?: RegExpOptions): PathRegExp;
- export function tokensToRegExp (tokens: Token[], keys?: Key[], options?: RegExpOptions): PathRegExp;
+ export function tokensToRegExp (tokens: Token[], options?: RegExpOptions, keys?: Key[]): PathRegExp;
 
  export interface Key {
  name: string | number;

index.js

@@ -1,5 +1,3 @@
-var isarray = require('isarray')
-
 /**
  * Expose `pathToRegexp`.
  */
@@ -39,10 +37,10 @@ function parse (str, options) {
  var key = 0
  var index = 0
  var path = ''
- var defaultDelimiter = options && options.delimiter || '/'
+ var defaultDelimiter = (options && options.delimiter) || '/'
  var res
 
- while ((res = PATH_REGEXP.exec(str)) != null) {
+ while ((res = PATH_REGEXP.exec(str)) !== null) {
  var m = res[0]
  var escaped = res[1]
  var offset = res.index
@@ -69,7 +67,7 @@ function parse (str, options) {
  path = ''
  }
 
- var partial = prefix != null && next != null && next !== prefix
+ var partial = prefix !== undefined && next !== undefined && next !== prefix
  var repeat = modifier === '+' || modifier === '*'
  var optional = modifier === '?' || modifier === '*'
  var delimiter = res[2] || defaultDelimiter
@@ -118,7 +116,7 @@ function compile (str, options) {
  * @return {string}
  */
 function encodeURIComponentPretty (str) {
- return encodeURI(str).replace(/[\/?#]/g, function (c) {
+ return encodeURI(str).replace(/[/?#]/g, function (c) {
  return '%' + c.charCodeAt(0).toString(16).toUpperCase()
  })
 }
@@ -180,7 +178,7 @@ function tokensToFunction (tokens) {
  }
  }
 
- if (isarray(value)) {
+ if (Array.isArray(value)) {
  if (!token.repeat) {
  throw new TypeError('Expected "' + token.name + '" to not repeat, but received `' + JSON.stringify(value) + '`')
  }
@@ -226,7 +224,7 @@ function tokensToFunction (tokens) {
  * @return {string}
  */
 function escapeString (str) {
- return str.replace(/([.+*?=^!:${}()[\]|\/\\])/g, '\\$1')
+ return str.replace(/([.+*?=^!:${}()[\]|/\\])/g, '\\$1')
 }
 
 /**
@@ -236,7 +234,7 @@ function escapeString (str) {
  * @return {string}
  */
 function escapeGroup (group) {
- return group.replace(/([=!:$\/()])/g, '\\$1')
+ return group.replace(/([=!:$/()])/g, '\\$1')
 }
 
 /**
@@ -294,15 +292,15 @@ function regexpToRegexp (path, keys) {
  * Transform an array into a regexp.
  *
  * @param {!Array} path
- * @param {Array} keys
  * @param {!Object} options
+ * @param {Array} keys
  * @return {!RegExp}
  */
-function arrayToRegexp (path, keys, options) {
+function arrayToRegexp (path, options, keys) {
  var parts = []
 
  for (var i = 0; i < path.length; i++) {
- parts.push(pathToRegexp(path[i], keys, options).source)
+ parts.push(pathToRegexp(path[i], options, keys).source)
  }
 
  var regexp = new RegExp('(?:' + parts.join('|') + ')', flags(options))
@@ -314,28 +312,24 @@ function arrayToRegexp (path, keys, options) {
  * Create a path regexp from string input.
  *
  * @param {string} path
- * @param {!Array} keys
  * @param {!Object} options
+ * @param {!Array} keys
  * @return {!RegExp}
  */
-function stringToRegexp (path, keys, options) {
- return tokensToRegExp(parse(path, options), keys, options)
+function stringToRegexp (path, options, keys) {
+ return tokensToRegExp(parse(path, options), options, keys)
 }
 
 /**
  * Expose a function for taking tokens and returning a RegExp.
  *
- * @param {!Array}  tokens
- * @param {(Array|Object)=} keys
- * @param {Object=}  options
+ * @param {!Array} tokens
+ * @param {Object=} options
+ * @param {Array=} keys
  * @return {!RegExp}
  */
-function tokensToRegExp (tokens, keys, options) {
- if (!isarray(keys)) {
- options = /** @type {!Object} */ (keys || options)
- keys = []
- }
-
+function tokensToRegExp (tokens, options, keys) {
+ keys = keys || []
  options = options || {}
 
  var strict = options.strict
@@ -373,22 +367,19 @@ function tokensToRegExp (tokens, keys, options) {
  }
 
  var delimiter = escapeString(options.delimiter || '/')
- var endsWithDelimiter = route.slice(-delimiter.length) === delimiter
+ var endsWith = [].concat(options.endsWith || []).map(escapeString).concat('$').join('|')
 
- // In non-strict mode we allow a slash at the end of match. If the path to
- // match already ends with a slash, we remove it for consistency. The slash
- // is valid at the end of a path match, not in the middle. This is important
- // in non-ending mode, where "/test/" shouldn't match "/test//route".
+ // In non-strict mode we allow a delimiter at the end of a match.
  if (!strict) {
- route = (endsWithDelimiter ? route.slice(0, -delimiter.length) : route) + '(?:' + delimiter + '(?=$))?'
+ route += '(?:' + delimiter + '(?=' + endsWith + '))?'
  }
 
  if (end) {
- route += '$'
+ route += endsWith === '$' ? endsWith : '(?=' + endsWith + ')'
  } else {
  // In non-ending mode, we need the capturing groups to match as much as
  // possible by using a positive lookahead to the end or next path segment.
- route += strict && endsWithDelimiter ? '' : '(?=' + delimiter + '|$)'
+ route += '(?=' + delimiter + '|' + endsWith + ')'
  }
 
  return attachKeys(new RegExp('^' + route, flags(options)), keys)
@@ -402,25 +393,21 @@ function tokensToRegExp (tokens, keys, options) {
  * contain `[{ name: 'id', delimiter: '/', optional: false, repeat: false }]`.
  *
  * @param {(string|RegExp|Array)} path
- * @param {(Array|Object)=} keys
  * @param {Object=} options
+ * @param {Array=} keys
  * @return {!RegExp}
  */
-function pathToRegexp (path, keys, options) {
- if (!isarray(keys)) {
- options = /** @type {!Object} */ (keys || options)
- keys = []
- }
-
+function pathToRegexp (path, options, keys) {
+ keys = keys || []
  options = options || {}
 
  if (path instanceof RegExp) {
- return regexpToRegexp(path, /** @type {!Array} */ (keys))
+ return regexpToRegexp(path, keys)
  }
 
- if (isarray(path)) {
- return arrayToRegexp(/** @type {!Array} */ (path), /** @type {!Array} */ (keys), options)
+ if (Array.isArray(path)) {
+ return arrayToRegexp(/** @type {!Array} */ (path), options, keys)
  }
 
- return stringToRegexp(/** @type {string} */ (path), /** @type {!Array} */ (keys), options)
+ return stringToRegexp(/** @type {string} */ (path), options, keys)
 }