url-pattern

What is url-pattern?

The url-pattern npm package is a utility for matching URL patterns and extracting parameters from URLs. It is useful for routing in web applications, where you need to determine which code to execute based on the URL path.

What are url-pattern's main functionalities?

Pattern Matching

This feature allows you to define URL patterns and match them against actual URLs. The example demonstrates how to create a pattern for user IDs and match it against a URL, extracting the user ID as a parameter.

const UrlPattern = require('url-pattern');
const pattern = new UrlPattern('/users/:id');
const match = pattern.match('/users/123');
console.log(match); // { id: '123' }

Reverse URL Generation

This feature allows you to generate URLs from a pattern and a set of parameters. The example shows how to create a URL for a specific user ID using the pattern.

const UrlPattern = require('url-pattern');
const pattern = new UrlPattern('/users/:id');
const url = pattern.stringify({ id: '123' });
console.log(url); // '/users/123'

Wildcard Matching

This feature allows you to use wildcards in your URL patterns to match any sequence of characters. The example demonstrates how to match any file path under the '/files' directory.

const UrlPattern = require('url-pattern');
const pattern = new UrlPattern('/files/*');
const match = pattern.match('/files/images/photo.jpg');
console.log(match); // { _: 'images/photo.jpg' }

Other packages similar to url-pattern

path-to-regexp

The path-to-regexp package is another utility for matching URL patterns and extracting parameters. It is more flexible and powerful than url-pattern, supporting advanced pattern matching features like optional parameters and custom parameter patterns.

route-parser

The route-parser package provides similar functionality for defining and matching URL patterns. It is simpler and more lightweight compared to url-pattern, making it a good choice for smaller projects or when you need a minimal solution.

url-patterns

The url-patterns package is another alternative for URL pattern matching and parameter extraction. It offers a similar API to url-pattern but includes additional features like query string parsing and more advanced pattern matching capabilities.

README

url-pattern

url-pattern is easy pattern matching and segment extraction for urls, domains, filepaths and any string composed of segments joined by a separator character

check out passage if you are looking for simple composable routing that builds on top of url-pattern

npm install url-pattern

require with commonjs:

var Pattern = require('url-pattern');

lib/url-pattern.js can be used in the browser. it supports AMD as well.

match urls or filepaths

make pattern from string

var pattern = new Pattern('/users/:id');

the default separator is /. you can pass a custom separator as the second argument.

match pattern against url

match returns the extracted parameters or null if there was no match:

pattern.match('/users/5'); // => {id: '5'}
pattern.match('/projects/5'); // => null

make pattern from regex

var regexPattern = new Pattern(/\/test\/(.*)/);

match regex pattern against url

if the pattern was created from a regex an array of the captured groups is returned on match:

regexPattern.match('/test/users'); // => ['users']
regexPattern.match('/users/test'); // => null

make wildcard pattern from string

var wildcardPattern = new Pattern('*/users/:id/*');

match wildcard pattern against url

wildcard matches are collected in the _ property:

wildcardPattern.match('/api/v1/users/10/followers/20');
// => {id: '10', _: ['/api/v1', 'followers/20']}

make optional pattern from string

var optionalPattern = new Pattern('(/)users(/:foo)/bar(/*)');

match optional pattern against url

optional matches are stored in the corresponding property, if they exist.

optionalPattern.match('users/bar');
// => {}
optionalPattern.match('/users/bar');
// => {}
optionalPattern.match('/users/biff/bar');
// => {foo: 'biff'}
optionalPattern.match('/users/biff/bar/beep/boop');
// => {foo: 'biff', _: ['beep/boop']}

match domains

make pattern from string

var pattern = new Pattern(':sub.google.com', '.');

the default separator is /. you can pass a custom separator as the second argument to Pattern.

match pattern against domain

match returns the extracted parameters or null if there was no match:

pattern.match('www.google.com'); // => {sub: 'www'}
pattern.match('www.google.io'); // => null

make pattern from regex

var regexPattern = new Pattern(/example\.(.*)/);

match regex pattern against domain

if the pattern was created from a regex an array of the captured groups is returned on match:

regexPattern.match('example.com'); // => ['com']
regexPattern.match('google.com'); // => null

make wildcard pattern from string

var wildcardPattern = new Pattern('*.:sub.google.*');

match wildcard pattern against url

wildcard matches are collected in the _ property:

wildcardPattern.match('subsub.www.google.com');
// => {sub: 'www', _: ['subsub', 'com']}

changelog

0.7

instead of

var urlPattern = require('url-pattern');
var pattern = urlPattern.newPattern('/example');

now use

var Pattern = require('url-pattern');
var pattern = new Pattern('/example');

contribution

TLDR: bugfixes, issues and discussion are always welcome. ask me before implementing new features.

i will happily merge pull requests that fix bugs with reasonable code.

i will only merge pull requests that modify/add functionality if the changes align with my goals for this package and only if the changes are well written, documented and tested.

communicate: write an issue to start a discussion before writing code that may or may not get merged.

todo

• https://github.com/snd/url-pattern/issues/6
  • parse string into array of objects describing structure
    • constant
    • binding
    • wildcard
    • optional
  • multiple occurences of the same name are collected into an array
    • this elegantly normalizes * and :
  • binding parsing is flexible and has a start and end regex
    • default: : and `[^a-zA-Z0-9]
    • custom: #{ and }
  • test that empty names are not allowed
• browser tests

license: MIT