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 simple pattern matching and segment extraction for urls, domains, filepaths and other strings

This is a great little library -- thanks!
michael

npm install url-pattern

> var UrlPattern = require('url-pattern');

> var pattern = new UrlPattern('/api/users/:id');

> pattern.match('/api/users/10');
{id: '10'}

> pattern.match('/api/products/5');
null

> var pattern = new UrlPattern('/v:major(.:minor)/*');

> pattern.match('/v1.2/');
{major: '1', minor: '2', _: ''}

> pattern.match('/v2/users');
{major: '2', _: 'users'}

> pattern.match('/v/');
null

lib/url-pattern.js supports AMD.
if AMD is not available it sets the global variable UrlPattern.

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

make pattern from string

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

match pattern against string

match returns the extracted segments:

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

or null if there was no match:

> pattern.match('/projects/5');
null

named segment names (starting with :) and named segment values stop at the next non-alphanumeric character.

make pattern from regex

> var pattern = new UrlPattern(/\/test\/(.*)/);

match regex pattern against string

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

> pattern.match('/test/users');
['users']

> pattern.match('/users/test');
null

wildcards

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

wildcard matches are collected in the _ property:

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

if there is only one wildcard _ contains the matching string. otherwise _ contains an array of matching strings.

optional segments

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

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

> pattern.match('users/bar');
{}

> pattern.match('/users/bar');
{}

> pattern.match('/users/biff/bar');
{foo: 'biff'}

> pattern.match('/users/biff/bar/beep/boop');
{foo: 'biff', _: 'beep/boop'}

matching domains

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

> pattern.match('www.google.com');
{sub: 'www'}

> pattern.match('www.google.io');
null

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

> pattern.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');

0.8

single wildcard matches are now saved directly as a string on the _ property and not as an array with 1 element:

> var pattern = new Pattern('/api/*');
> pattern.match('/api/users/5')
{_: 'users/5'}

if named segments occur more than once the results are collected in an array.

parsing of named segment names (:foo) and named segment values now stops at the next non-alphanumeric character. it is no longer needed to declare separators other than / explicitely. it was previously necessary to use the second argument to new UrlPattern to override the default separator /. the second argument is now ignored. mixing of separators is now possible (/ and . in this example):

> var pattern = new UrlPattern('/v:major(.:minor)/*');

> pattern.match('/v1.2/');
{major: '1', minor: '2', _: ''}

> pattern.match('/v2/users');
{major: '2', _: 'users'}

> pattern.match('/v/');
null

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, are well written, documented and tested.

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

license: MIT