k8o

はじめに

URLPattern APIは、URLのパターンマッチを簡単にするためのAPIです。Safari 26のサポートによって、Baseline 2025入りした新しい機能です。

この記事では、URLPattern APIの基本的な使い方について紹介します。

URLPattern

URLPattern APIは、生成したURLPatternオブジェクトを使って、URLのパターンマッチを行います。

const pattern = new URLPattern(
  input,
  baseURL,
  options,
)

inputは必須で、baseURLとoptionsは省略可能です。baseURLを省略してinputとoptionsを指定することもできます。

// これはもちろんOK
new URLPattern(
  input,
)

// baseURLだけを省略可能
new URLPattern(
  input,
  options,
)

第1引数のinputにはURLのパターンを文字列かオブジェクトで渡します。

const pattern1 = new URLPattern("https://k8o.me/blog/:id");

オブジェクトの場合は、protocol、username、password、hostname、port、pathname、search、hash、baseURLの各プロパティにパターンを指定します。

const pattern2 = new URLPattern({
  protocol: "https",
  hostname: "k8o.me",
  pathname: "/blog/:id",
});

const pattern3 = new URLPattern({
  pathname: "/blog/:id",
  baseURL: "https://k8o.me",
});

pattern1、pattern2、pattern3はすべて同じ意味になります。

指定していないプロパティは*が渡された、つまりワイルドカードとして扱われます。ただし、baseURLを指定した場合はその限りではなく、各プロパティに''が設定されたとして扱われます。

// 同じ
const pattern1 = new URLPattern({
  protocol: "https",
  hostname: "k8o.me",
  pathname: "/blog/:id",
});
const pattern2 = new URLPattern({
  protocol: "https",
  username: "*",
  password: "*",
  hostname: "k8o.me",
  port: "*",
  pathname: "/blog/:id",
  search: "*",
  hash: "*",
});

// 同じ
const pattern3 = new URLPattern({
  baseURL: "https://k8o.me",
});
const pattern4 = new URLPattern({
  protocol: "https",
  username: "*",
  password: "*",
  hostname: "k8o.me",
  port: "",
  pathname: "/",
  search: "",
  hash: "",
});

第2引数のbaseURLには、相対URLを解決するための基準となるURLを文字列で渡します。

// pattern1とpattern2は同じ意味になる
const pattern1 = new URLPattern("https://k8o.me/blog/:id");
const pattern2 = new URLPattern("/blog/:id", "https://k8o.me");

第3引数のoptionsにはパターンマッチのオプションを渡せます。現在付与できるのはignoreCaseのみで、デフォルトはfalseです。 デフォルトでは大文字小文字を区別しますが、ignoreCaseをtrueにすると大文字小文字を区別しなくなります。

const pattern = new URLPattern("/blog/:id", "https://k8o.me", { ignoreCase: true });

定義したパターンと照合するexecメソッド

作成したURLPatternオブジェクトは、URLのパターンマッチをexecメソッドで行います。 execメソッドは、指定したURLが定義したパターンに一致するかどうかを確認し、一致した場合はマッチした部品ごとの情報を返します。

const pattern = new URLPattern("https://k8o.me/blog/:id");
const result = pattern.exec("https://k8o.me/blog/urlpattern?query=abc#section1");

// 一致しない場合はnullが返る
if (result) {
  console.log(result.inputs);  // ["https://k8o.me/blog/urlpattern?query=abc#section1"]
  console.log(result.pathname); // { input: "/blog/urlpattern", groups: {id: 'urlpattern'} }
  console.log(result.search);   // { input: "query=abc", groups: {} }
  console.log(result.hash);     // { input: "section1", groups: {} }
  console.log(result.username); // { input: "", groups: {} }
} else {
  console.log("パターンに一致しませんでした");
}

戻り値は各部品ごとに一致した情報をオブジェクトで返します。inputには一致した文字列が、groupsにはパターンマッチでキャプチャされた値が格納されます。

返り値のオブジェクトは部品の他にinputsプロパティも持ち、入力された情報が配列で返ってきます。

execメソッドの引数にはコンストラクタと同様にinputとbaseURLを渡せます。 渡すのは照合するURLですので、オブジェクトをinputに渡した場合、指定していない部分は''が渡されたものとされます。

定義したパターンに一致すること確認するtestメソッド

作成したURLPatternオブジェクトは、URLのパターンマッチの一致をtestメソッドで確認できます。 testメソッドは、指定したURLが定義したパターンに一致するかどうかを真偽値で返します。

const pattern = new URLPattern("/blog/:id", "https://k8o.me");
console.log(pattern.test("https://k8o.me/blog/urlpattern?query=abc#section1")); // true
console.log(pattern.test("https://k8o.me/blog")); // false

testメソッドの引数はexecメソッドと同様です。

適用されたパターンマッチを部品ごとに確認する

作成したURLPatternオブジェクトが適用されたパターンマッチを部品ごとに確認するためのメソッドを提供します。 protocol、username、password、hostname、port、pathname、search、hashの各部品にどのようなパターンが適用されたかを確認できます。

const pattern1 = new URLPattern("https://k8o.me");
console.log(pattern1.protocol); // "https"
console.log(pattern1.username); // "*"
console.log(pattern1.password); // "*"
console.log(pattern1.hostname); // "k8o.me"
console.log(pattern1.port);     // ""
console.log(pattern1.pathname); // "*"
console.log(pattern1.search);   // "*"
console.log(pattern1.hash);     // "*"

const pattern2 = new URLPattern({
  baseURL: "https://k8o.me",
});
console.log(pattern2.protocol); // "https"
console.log(pattern2.username); // "*"
console.log(pattern2.password); // "*"
console.log(pattern2.hostname); // "k8o.me"
console.log(pattern2.port);     // ""
console.log(pattern2.pathname); // "/"
console.log(pattern2.search);   // ""
console.log(pattern2.hash);     // ""

const pattern3 = new URLPattern({
  baseURL: "https://k8o.me",
  protocol: "https",
  hostname: "k8o.me",
});
console.log(pattern3.protocol); // "https"
console.log(pattern3.username); // "*"
console.log(pattern3.password); // "*"
console.log(pattern3.hostname); // "k8o.me"
console.log(pattern3.port);     // "*"
console.log(pattern3.pathname); // "*"
console.log(pattern3.search);   // "*"
console.log(pattern3.hash);     // "*"

初めの方に紹介したURLPatternオブジェクトの異なる第1引数による同一性は、この機能を用いて確認しました。

おわりに

URLのパターンマッチを簡単にするためのURLPattern APIについて紹介しました。

これまではRegExp等を使って行ってきたURLのパターンマッチを、URLPattern APIによってより簡単かつ正確にパターンマッチを行えるのは非常に便利だと感じました。