URL Pattern
Validate URLs and extract values easily!
Installation
Using npm
npm i @helix-re/url-pattern
Usage
Note: URL Pattern supports both ES and CJS modules.
To use the APIs, you will need to understand the concept of a namespace. We define namespace as one or more characters between 2 slashes. Let's look at an example URL.
https://example.com/foo/bar/
We recommend using URL Pattern only with the pathname
part of the URL.
/foo/bar/
We also define a concept of named and anonymous namespaces. Let's see how they work in practice on the example URL. There are 2 anonymous namespaces foo
and bar
, or 1 named namespace foo
with value bar
.
The reason we define 2 concepts is that a typical application might use a combination of both. For example, if we look at the HELIX RE office on Google Maps.
https://google.com/maps/place/HELIX+RE/@51.5333649,-0.1075597,17z/data=!3m1!4b1!4m5!3m4!1s0x48761bb724ab195d:0x1c29f788dbea0821!8m2!3d51.5333649!4d-0.1053657
Again, remove the domain part.
/maps/place/HELIX+RE/@51.5333649,-0.1075597,17z/data=!3m1!4b1!4m5!3m4!1s0x48761bb724ab195d:0x1c29f788dbea0821!8m2!3d51.5333649!4d-0.1053657
-
maps
is an anonymous namespace -
place
is a named namespace with valueHELIX+RE
-
@51.5333649,-0.1075597,17z
is an anonymous namespace -
data=!3m1!4b1!4m5!3m4!1s0x48761bb724ab195d:0x1c29f788dbea0821!8m2!3d51.5333649!4d-0.1053657
is an anonymous namespace
Let's look at how we can extract the place
namespace with URL Pattern.
import { required, select } from '@helix-re/url-pattern';
const pattern = required() + select('place');
url.match(new RegExp(`^${pattern}`))[1]; // 'HELIX+RE'
All we had to do was require an anonymous namespace (maps
) and select the value of a named namespace place
.
Another common use case is defining optional namespaces. Let's assume Google Maps works even if you skip the initial /maps/
prefix. We could make our selector work like this.
import { optional, select } from '@helix-re/url-pattern';
const pattern = optional('maps') + select('place');
url.match(new RegExp(`^${pattern}`))[1]; // 'HELIX+RE'
Our pattern will now match the following URL as well.
/place/HELIX+RE/@51.5333649,-0.1075597,17z/data=!3m1!4b1!4m5!3m4!1s0x48761bb724ab195d:0x1c29f788dbea0821!8m2!3d51.5333649!4d-0.1053657
API
- optional(values)
Denotes one or more optional anonymous namespaces. Note that you need to know their values in advance.
- required(name)
Denotes a required namespace. Accepts an optional name
parameter. If skipped, we require an anonymous namespace.
- select(name)
Selects a namespace value which can be accessed in the matched result. Accepts an optional name
parameter. If skipped we select an anonymous namespace.