URLPattern

The URLPattern interface of Azion Runtime: its constructor, its properties, and the methods that match a URL against a pattern.

Last updated

View as Markdown Agent setup

The URLPattern interface of Azion Runtime matches a URL, or parts of a URL, against a pattern. A pattern can hold capture groups that extract parts of the matched URL, such as the ID in a path. For more information, refer to URLPattern on MDN Web Docs.

Under azion dev, hasRegExpGroups is undefined. The constructor, the other properties, and both methods return the same values locally and deployed.

Constructor

new URLPattern(input, baseURL)

URLPattern() returns a URLPattern object built from the pattern and the base URL you pass:

ParameterTypeDescription
inputObject or stringThe pattern. An object takes one pattern per URL component, such as { pathname: '/users/:id' }. A string takes the pattern as a URL string, such as /books/:isbn, resolved against baseURL.
baseURLStringBase URL for a relative pattern string, such as https://example.com.

With a base URL, the components the string leaves out come from the base URL: new URLPattern('/books/:isbn', 'https://example.com') has the protocol https, the hostname example.com, and the pathname /books/:isbn.

A pattern takes named groups such as :id, wildcards (*), optional parts in braces such as http{s}?, and a regular expression after a group name, such as :name(\d+).

Properties

Each component property returns the pattern of that component, as you passed it. A component you set to an empty string, such as port, returns an empty string.

PropertyTypeDescription
hashStringPattern that matches the hash part of a URL.
hostnameStringPattern that matches the hostname part of a URL, such as {*.}?example.com.
passwordStringPattern that matches the password part of a URL.
pathnameStringPattern that matches the pathname part of a URL, such as /api/*.
portStringPattern that matches the port part of a URL.
protocolStringPattern that matches the protocol part of a URL, such as http{s}?.
searchStringPattern that matches the search part of a URL, such as q=:q.
usernameStringPattern that matches the username part of a URL.
hasRegExpGroupsBooleantrue for a pattern that holds a regular expression group, such as /a/(\d+).

Methods

MethodDescription
pattern.exec(input)Returns an object with the matched parts of the URL, or null when the URL does not match. Each component of the result, such as pathname, carries the captured values in groups.
pattern.test(input)Returns true when the URL matches the pattern, and false when it does not.

Both methods take a URL string. exec() also takes an object of URL components: for the pattern { pathname: '/files/:name(\\d+).:ext' }, exec({ pathname: '/files/12.png' }) returns the pathname groups { name: '12', ext: 'png' }.

Example

This handler matches two URLs against a pathname pattern with a named group, then returns the results of test() and exec() with Response.json():

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const pattern = new URLPattern({ pathname: '/users/:id' });
04 return Response.json({
05 test: pattern.test('https://example.com/users/42'),
06 group: pattern.exec('https://example.com/users/42')?.pathname.groups,
07 miss: pattern.exec('https://example.com/posts/1'),
08 });
09 },
10};

The function returns these values. The id group captures 42, and exec() returns null for the URL that does not match:

JSON
01{
02 "test": true,
03 "group": {
04 "id": "42"
05 },
06 "miss": null
07}
Request

The incoming request, whose URL a function can match against a pattern.

Response

How a function builds the response it returns, as the example does with Response.json().

Handlers

The handler shapes a function exports to receive requests.

Web APIs

The other Web APIs that Azion Runtime supports.