soseki 0.0.9 → 0.0.11

package/src/core/route-pattern-utils.ts

@@ -0,0 +1,327 @@
+import { inject, parse } from "regexparam";
+
+import type { RouteParams } from "./_regexparam.js";
+import { RoutePatternMismatchError } from "./errors.js";
+import RoutePath from "./route-path.js";
+
+/**
+ * 対象の型プロパティーをすべて任意とし、さらに各プロパティー値に undefined を許容する型です。
+ *
+ * @template T オブジェクトの型定義です。
+ */
+type Optional<T> = {
+  readonly [P in keyof T]?: T[P] | undefined;
+};
+
+/**
+ * ルートパターンの照合処理において、URL の文字列情報を抽出するためのインターフェースです。
+ */
+export interface RoutePatternMatchURL {
+  /**
+   * ホスト名を除いた URL パス全体の文字列を表します。
+   */
+  readonly pathname: string;
+}
+
+/**
+ * 引数に渡された対象から URL パスを取得し、一貫した形式に正規化します。
+ *
+ * @param target 文字列または URL 情報を持つオブジェクトです。
+ * @returns 正規化されたパス文字列です。
+ */
+function normalizeTarget(target: string | RoutePatternMatchURL): string {
+  return new RoutePath(typeof target === "string" ? target : target.pathname).pathname;
+}
+
+/**
+ * ルートパターンを解析および処理する際の挙動を設定するオプションです。
+ */
+export type RoutePatternUtilsOptions = {
+  /**
+   * 子ディレクトリーへの前方一致を許可するかどうかを制御するフラグです。下位パスが存在する場合にも一致とみなす場合に true を指定します。
+   *
+   * @default false
+   */
+  readonly allowChild?: boolean | undefined;
+};
+
+/**
+ * ルートパターンの解析などを行うユーティリティークラスです。
+ *
+ * @template TRoutePattern リテラル型で固定されたルートパターンの文字列定義です。
+ */
+export default class RoutePatternUtils<const TRoutePattern extends string = string> {
+  /**
+   * ルートパターンと対象のパスが一致するかどうかを静的に検証します。
+   *
+   * @template TRoutePattern パターンの文字列型です。
+   * @param routePattern 基準となるルートパターン文字列です。
+   * @param target 検証対象のパス文字列またはオブジェクトです。
+   * @param options 解析時の振る舞いを制御するオプションです。
+   * @returns 一致する場合は true、一致しない場合は false です。
+   */
+  public static match<const TRoutePattern extends string>(
+    routePattern: TRoutePattern,
+    target: string | RoutePatternMatchURL,
+    options: RoutePatternUtilsOptions,
+  ): boolean {
+    return new RoutePatternUtils(routePattern, options).match(target);
+  }
+
+  /**
+   * 静的な解析を行い、対象のパスからパラメーターを抽出します。一致しない場合はエラーを投げます。
+   *
+   * @template TRoutePattern パターンの文字列型です。
+   * @param routePattern 基準となるルートパターン文字列です。
+   * @param target 解析対象のパス文字列またはオブジェクトです。
+   * @param options 解析時の振る舞いを制御するオプションです。
+   * @returns 抽出されたパラメーターオブジェクトです。
+   */
+  public static parse<const TRoutePattern extends string>(
+    routePattern: TRoutePattern,
+    target: string | RoutePatternMatchURL,
+    options: RoutePatternUtilsOptions,
+  ): RouteParams<TRoutePattern> {
+    return new RoutePatternUtils(routePattern, options).parse(target);
+  }
+
+  /**
+   * 静的な埋め込みを行い、ルートパターンにパラメーターを適用してパスを生成します。
+   *
+   * @template TRoutePattern パターンの文字列型です。
+   * @param routePattern 基準となるルートパターン文字列です。
+   * @param params 埋め込むパラメーターのキーと値の組み合わせです。
+   * @param options 解析時の振る舞いを制御するオプションです。
+   * @returns パラメーターが適用された新しいパス文字列です。
+   */
+  public static inject<const TRoutePattern extends string>(
+    routePattern: TRoutePattern,
+    params: Readonly<RouteParams<TRoutePattern>>,
+    options: RoutePatternUtilsOptions,
+  ): string {
+    return new RoutePatternUtils(routePattern, options).inject(params);
+  }
+
+  // public static partialInject<const TRoutePattern extends string>(
+  //   routePattern: TRoutePattern,
+  //   params: Optional<RouteParams<TRoutePattern>>,
+  //   options: RoutePatternUtilsOptions = {},
+  // ): string {}
+
+  /**
+   * 対象のパスに含まれるパラメーターの一部を指定された値で置き換えて、新しいパスを静的に生成します。
+   *
+   * @template TRoutePattern パターンの文字列型です。
+   * @param routePattern 基準となるルートパターン文字列です。
+   * @param target 既存のパス文字列またはオブジェクトです。
+   * @param params 上書きするパラメーターです。
+   * @param options 解析時の振る舞いを制御するオプションです。
+   * @returns 置き換え後のパス文字列です。
+   */
+  public static replace<const TRoutePattern extends string>(
+    routePattern: TRoutePattern,
+    target: string | RoutePatternMatchURL,
+    params: Optional<RouteParams<TRoutePattern>>,
+    options: RoutePatternUtilsOptions,
+  ): string {
+    return new RoutePatternUtils(routePattern, options).replace(target, params);
+  }
+
+  /**
+   * 静的な解析を行い、対象のパスからパラメーターを安全に抽出します。一致しない場合は null を返します。
+   *
+   * @template TRoutePattern パターンの文字列型です。
+   * @param routePattern 基準となるルートパターン文字列です。
+   * @param target 解析対象のパス文字列またはオブジェクトです。
+   * @param options 解析時の振る舞いを制御するオプションです。
+   * @returns 抽出されたパラメーターオブジェクト、一致しない場合は null です。
+   */
+  public static parseSafe<const TRoutePattern extends string>(
+    routePattern: TRoutePattern,
+    target: string | RoutePatternMatchURL,
+    options: RoutePatternUtilsOptions,
+  ): RouteParams<TRoutePattern> | null {
+    return new RoutePatternUtils(routePattern, options).parseSafe(target);
+  }
+
+  // public static injectSafe<const TRoutePattern extends string>(
+  //   routePattern: TRoutePattern,
+  //   params: Readonly<RouteParams<TRoutePattern>>,
+  //   options: RoutePatternUtilsOptions = {},
+  // ): string | null {}
+
+  /**
+   * 対象のパスに含まれるパラメーターの一部を指定された値で安全に置き換えます。不一致の場合は null を返します。
+   *
+   * @template TRoutePattern パターンの文字列型です。
+   * @param routePattern 基準となるルートパターン文字列です。
+   * @param target 既存のパス文字列またはオブジェクトです。
+   * @param params 上書きするパラメーターです。
+   * @param options 解析時の振る舞いを制御するオプションです。
+   * @returns 置き換え後のパス文字列、不一致の場合は null です。
+   */
+  public static replaceSafe<const TRoutePattern extends string>(
+    routePattern: TRoutePattern,
+    target: string | RoutePatternMatchURL,
+    params: Optional<RouteParams<TRoutePattern>>,
+    options: RoutePatternUtilsOptions,
+  ): string | null {
+    return new RoutePatternUtils(routePattern, options).replaceSafe(target, params);
+  }
+
+  /**
+   * インスタンスに保持されるルートパターン文字列です。
+   */
+  public readonly route: string;
+
+  /**
+   * ルートパターンのマッチングとパラメーター抽出に使用する正規表現オブジェクトです。
+   */
+  public readonly pattern: RegExp;
+
+  /**
+   * ルートパターンから抽出されたパラメーター名の配列です。
+   */
+  public readonly paramKeys: readonly Extract<keyof RouteParams<TRoutePattern>, string>[];
+
+  /**
+   * 新しい `RoutePatternUtils` インスタンスを作成します。
+   *
+   * @param routePattern 解析基準となるルートパターンです。
+   * @param options 前方一致などを制御するオプションです。
+   */
+  public constructor(routePattern: TRoutePattern, options: RoutePatternUtilsOptions = {}) {
+    const { keys, pattern } = parse(routePattern, options.allowChild);
+    this.route = routePattern;
+    this.pattern = pattern;
+    this.paramKeys = keys satisfies string[] as any[];
+  }
+
+  /**
+   * パスが構築時のルートパターンに一致するかどうかを評価します。
+   *
+   * @param target 検証対象のパス文字列またはオブジェクトです。
+   * @returns パターンに合致する場合は true、それ以外は false です。
+   */
+  public match(target: string | RoutePatternMatchURL): boolean {
+    target = normalizeTarget(target);
+    return this.pattern.test(target);
+  }
+
+  /**
+   * インスタンスのルートパターンを基に対象パスからパラメーターを抽出します。解析できない場合は、処理が継続できないため例外を投げます。
+   *
+   * @param target 解析対象のパス文字列またはオブジェクトです。
+   * @returns 抽出したパラメーターオブジェクトです。
+   */
+  public parse(target: string | RoutePatternMatchURL): RouteParams<TRoutePattern> {
+    const params = this.parseSafe(target);
+    if (params === null) {
+      throw new RoutePatternMismatchError({
+        route: this.route,
+        target: normalizeTarget(target),
+      });
+    }
+
+    return params;
+  }
+
+  /**
+   * 指定されたパラメーター群をルートパターンに埋め込んで、具体的なパス文字列を構築します。
+   *
+   * @param params パラメーターのキーと値のオブジェクトです。
+   * @returns 生成されたパス文字列です。
+   */
+  public inject(params: Readonly<RouteParams<TRoutePattern>>): string {
+    return inject(this.route, params);
+  }
+
+  // public partialInject(params: Optional<RouteParams<TRoutePattern>>): string {}
+
+  /**
+   * 現在のパスに含まれるパラメーター値の一部を、指定された値で上書きした新しいパスを構築します。対象パスがルートパターンと一致しない場合は例外を投げます。
+   *
+   * @param target 基準となる現在のパス文字列またはオブジェクトです。
+   * @param params 変更を適用する一部のパラメーターです。
+   * @returns 新しく生成されたパス文字列です。
+   */
+  public replace(
+    target: string | RoutePatternMatchURL,
+    params: Optional<RouteParams<TRoutePattern>>,
+  ): string {
+    const replaced = this.replaceSafe(target, params);
+    if (replaced === null) {
+      throw new RoutePatternMismatchError({
+        route: this.route,
+        target: normalizeTarget(target),
+      });
+    }
+
+    return replaced;
+  }
+
+  /**
+   * パターンに基づきパスの解析を行い、プレースホルダーに該当する箇所をオブジェクトとして抽出します。
+   *
+   * @param target 解析対象のパス文字列またはオブジェクトです。
+   * @returns 抽出に成功した場合はパラメーターのオブジェクト、不一致の場合は null です。
+   */
+  public parseSafe(target: string | RoutePatternMatchURL): RouteParams<TRoutePattern> | null {
+    target = normalizeTarget(target);
+    const matches = this.pattern.exec(target);
+    if (!matches) {
+      return null;
+    }
+
+    const params: Record<string, string> = {};
+    for (let i = 0, param: string | undefined; i < this.paramKeys.length; i++) {
+      // exec メソッドの戻り値のインデックス 0 にはマッチした文字列全体が格納されているため、各パラメーターの値はインデックス 1 以降（i + 1）から取得します。
+      param = matches[i + 1];
+
+      // キャプチャーされたセグメントが存在し、かつ文字列型である場合にのみ、対応するパラメーターキーと値をマッピングします。
+      // オプショナルなパラメーターが URL 側で省略されている場合は undefined となるため、この条件節により除外されます。
+      if (typeof param === "string") {
+        params[this.paramKeys[i]!] = param;
+      }
+    }
+
+    return params as RouteParams<TRoutePattern>;
+  }
+
+  // public injectSafe(params: Readonly<RouteParams<TRoutePattern>>): string | null {
+  //   if (!this.paramKeys.every((key) => key in params && typeof params[key] === "string")) {
+  //     return null;
+  //   }
+
+  //   return inject(this.route, params);
+  // }
+
+  /**
+   * 既存のパスから抽出されたパラメーター値をベースとして、任意のパラメーターのみを上書きしたパス文字列を再構築します。
+   *
+   * @param target 基にするパス文字列またはオブジェクトです。
+   * @param params 上書き指定するパラメーターオブジェクトです。
+   * @returns 再構築されたパス文字列、パスが不一致の場合は null です。
+   */
+  public replaceSafe(
+    target: string | RoutePatternMatchURL,
+    params: Optional<RouteParams<TRoutePattern>>,
+  ): string | null {
+    const defaults = this.parseSafe(target);
+    if (defaults === null) {
+      return null;
+    }
+
+    const values: Record<string, any> = {};
+    for (const key of this.paramKeys) {
+      const param = params[key];
+      if (typeof param === "string") {
+        values[key] = param;
+      } else {
+        values[key] = defaults[key];
+      }
+    }
+
+    return inject(this.route, values);
+  }
+}

package/src/core/route.types.ts

@@ -1,95 +1,31 @@
 import type * as React from "react";
 
+import type { RouteParams as $RouteParams } from "./_regexparam.js";
 import type { ReadonlyURL } from "./readonly-url.types.js";
+import type RoutePatternUtils from "./route-pattern-utils.js";
 import type { RouteGetRequest, RoutePostRequest } from "./route-request.js";
 
-/**
- * 個別のパスパラメーターを解析し、適切なプロパティーの型オブジェクトへと変換する内部ユーティリティー型です。
- *
- * パラメーターの末尾の形状を条件付き型により詳細に選別します。
- *
- * @template Param 解析対象となる単一のパラメーター文字列です。
- */
-// oxfmt-ignore
-type ParamRecord<Param extends string> =
-  // パラメーター末尾に「?」がある場合、オプショナルなプロパティー型に変換します
-    Param extends `${infer Name}?`
-    ? { [K in Name]?: string }
-
-  // パラメーターに拡張子が含まれている場合、拡張子を除いた名前を必須のプロパティー型に変換します。
-  : Param extends `${infer Name}.${string}`
-    ? { [K in Name]: string }
-
-  // 上記のいずれのパターンにも該当しない場合は、パラメーター名をそのまま必須のプロパティー型に変換します。
-  : { [K in Param]: string };
-
-/**
- * パス文字列のセグメントから動的なパラメーターやワイルドカードを再帰的に抽出し、型安全なオブジェクト構造を構築するユーティリティー型です。
- *
- * 開発者が指定した文字列リテラル型の形状に基づいて、ルーティングに必要なパラメーターの型を静的に決定します。
- *
- * このユーティリティー型は、ライブラリー `regexparam` の改良版です。
- *
- * @template T 解析対象となる URL パス全体の文字列リテラル型です。
- * @see https://github.com/lukeed/regexparam
- * @see https://github.com/lukeed/regexparam/issues/31
- * @see https://github.com/lukeed/regexparam/pull/33
- */
-// oxfmt-ignore
-type RouteParams<T extends string> =
-  // 与えられた型が具体的なリテラルでなく文字列型である場合は、汎用的なレコード型へとフォールバックします。
-    string extends T
-    ? { [K in string]?: string }
-
-  // パスの中間にワイルドカードが存在する場合、前後のパラメーターに加えて、必須のワイルドカードプロパティーを結合します。
-  : T extends `${infer Prev}/*/${infer Rest}`
-    ? & RouteParams<Prev>
-      & { wild: string }
-      & RouteParams<`/${Rest}`>
-
-  // パスの先頭がコロンで開始されている場合、先頭にスラッシュ（/）を補正して再帰的に再評価します。
-  : T extends `:${infer Rest}`
-    ? RouteParams<`/:${Rest}`>
-
-  // パスの中間にコロンで始まるパラメーターが含まれている場合、そのセグメントの型情報を抽出し、スラッシュ以降の残りのパスの解析結果と交差型で結合します。
-  : T extends `${string}:${infer Param}/${infer Rest}`
-    ? & ParamRecord<Param>
-      & RouteParams<`/${Rest}`>
-
-  // パスの末尾がコロンで始まるパラメーターで終了している場合、そのセグメントの型情報を判定して抽出を完了します。
-  : T extends `${string}/:${infer Param}`
-    ? ParamRecord<Param>
-
-  // パスの末尾がオプショナルワイルドカードで終了している場合、キー名を「"*"」としたオプショナルなプロパティー型を返します。
-  : T extends `${string}/*?`
-    ? { "*"?: string }
-
-  // パスの末尾が通常のワイルドカードで終了している場合、キー名を「"*"」とした必須のプロパティー型を返します。
-  : T extends `${string}/*`
-    ? { "*": string }
-
-  // 抽出可能なパラメーターやワイルドカードが一切検出されなかった場合は、空のオブジェクト型を返します。
-  : {};
-
 /**
  * 文字列リテラルとして定義されたパスの形状から、含まれるパスパラメーターを解析し、静的に型付けされたオブジェクトとして抽出する型定義です。
  *
- * @template TRoutePath パラメーター抽出の対象となるパス文字列リテラル型です。
+ * @template TRoutePattern パラメーター抽出の対象となるパス文字列リテラル型です。
  */
-export type RoutePathParams<TRoutePath extends string = string> = Readonly<RouteParams<TRoutePath>>;
+export type RouteParams<TRoutePattern extends string = string> = Readonly<
+  $RouteParams<TRoutePattern>
+>;
 
 /**
  * データ更新などのアクション処理を実行する際に、該当する関数へ渡される引数の型定義です。
  *
  * 解析済みのパスパラメーターと、HTTP の POST メソッドを抽象化したリクエストオブジェクトを含みます。
  *
- * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TRoutePattern 対象となるルートのパス文字列リテラル型です。
  */
-export type ActionFunctionArgs<TRoutePath extends string = string> = {
+export type ActionFunctionArgs<TRoutePattern extends string = string> = {
   /**
    * 現在の URL パスから抽出されたパラメーターオブジェクトです。
    */
-  params: RoutePathParams<TRoutePath>;
+  params: RouteParams<TRoutePattern>;
 
   /**
    * フォームデータなどを内包する、HTTP の POST メソッドに特化したルーティングリクエストオブジェクトです。
@@ -100,11 +36,11 @@ export type ActionFunctionArgs<TRoutePath extends string = string> = {
 /**
  * データの登録、更新、削除といった副作用を伴うアクション処理を定義するための関数インターフェースです。
  *
- * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TRoutePattern 対象となるルートのパス文字列リテラル型です。
  * @template TData アクション関数が返す戻り値の型定義です。既定値は `unknown` です。
  */
-export interface ActionFunction<TRoutePath extends string = string, TData = unknown> {
-  (args: ActionFunctionArgs<TRoutePath>): TData;
+export interface ActionFunction<TRoutePattern extends string = string, TData = unknown> {
+  (args: ActionFunctionArgs<TRoutePattern>): TData;
 }
 
 /**
@@ -112,9 +48,9 @@ export interface ActionFunction<TRoutePath extends string = string, TData = unkn
  *
  * アクションを実行した契機となる HTTP メソッドの種類（GET / POST）に応じて、含まれるコンテキスト情報が分岐します。
  *
- * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TRoutePattern 対象となるルートのパス文字列リテラル型です。
  */
-export type ShouldReloadFunctionArgs<TRoutePath extends string = string> =
+export type ShouldReloadFunctionArgs<TRoutePattern extends string = string> =
   | {
       /**
        * 再読み込みを引き起こした HTTP メソッドの種別です。
@@ -129,7 +65,7 @@ export type ShouldReloadFunctionArgs<TRoutePath extends string = string> =
       /**
        * 現在の URL から抽出されたパスパラメーターです。
        */
-      currentParams: RoutePathParams<TRoutePath>;
+      currentParams: RouteParams<TRoutePattern>;
 
       /**
        * POST リクエストが発生する直前の読み取り専用 URL オブジェクトです。
@@ -139,7 +75,7 @@ export type ShouldReloadFunctionArgs<TRoutePath extends string = string> =
       /**
        * POST リクエストが発生する直前の URL から抽出されたパスパラメーターです。
        */
-      prevParams: RoutePathParams;
+      prevParams: RouteParams;
 
       /**
        * システムが内部ロジックに基づいて判断した、再読み込み実行の既定の判定フラグです。
@@ -160,7 +96,7 @@ export type ShouldReloadFunctionArgs<TRoutePath extends string = string> =
       /**
        * 現在の URL から抽出されたパスパラメーターです。
        */
-      currentParams: RoutePathParams<TRoutePath>;
+      currentParams: RouteParams<TRoutePattern>;
 
       /**
        * POST リクエストが発生する直前の読み取り専用 URL オブジェクトです。
@@ -170,7 +106,7 @@ export type ShouldReloadFunctionArgs<TRoutePath extends string = string> =
       /**
        * POST リクエストが発生する直前の URL から抽出されたパスパラメーターです。
        */
-      prevParams: RoutePathParams;
+      prevParams: RouteParams;
 
       /**
        * POST リクエストと共に送信された標準のフォームデータオブジェクトです。
@@ -191,11 +127,11 @@ export type ShouldReloadFunctionArgs<TRoutePath extends string = string> =
 /**
  * ルートデータの再読み込みが不必要な場合に、余分な通信や再取得処理を抑制するための判定関数インターフェースです。
  *
- * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TRoutePattern 対象となるルートのパス文字列リテラル型です。
  * @returns データを再読み込みする場合は `true`、スキップする場合は `false` を返します。
  */
-export interface ShouldReloadFunction<TRoutePath extends string = string> {
-  (args: ShouldReloadFunctionArgs<TRoutePath>): boolean;
+export interface ShouldReloadFunction<TRoutePattern extends string = string> {
+  (args: ShouldReloadFunctionArgs<TRoutePattern>): boolean;
 }
 
 /**
@@ -203,13 +139,13 @@ export interface ShouldReloadFunction<TRoutePath extends string = string> {
  *
  * 解析済みのパスパラメーターと、HTTP の GET メソッドを抽象化したリクエストオブジェクトを含みます。
  *
- * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TRoutePattern 対象となるルートのパス文字列リテラル型です。
  */
-export type LoaderFunctionArgs<TRoutePath extends string = string> = {
+export type LoaderFunctionArgs<TRoutePattern extends string = string> = {
   /**
    * 現在の URL パスから抽出されたパラメーターオブジェクトです。
    */
-  params: RoutePathParams<TRoutePath>;
+  params: RouteParams<TRoutePattern>;
 
   /**
    * HTTP の GET メソッドに特化したルーティングリクエストオブジェクトです。
@@ -220,11 +156,11 @@ export type LoaderFunctionArgs<TRoutePath extends string = string> = {
 /**
  * 画面の初期描画時や遷移時にデータをオンデマンドで取得するための関数インターフェースです。
  *
- * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TRoutePattern 対象となるルートのパス文字列リテラル型です。
  * @template TData ローダー関数が返す戻り値の型定義です。既定値は `unknown` です。
  */
-export interface LoaderFunction<TRoutePath extends string = string, TData = unknown> {
-  (args: LoaderFunctionArgs<TRoutePath>): TData;
+export interface LoaderFunction<TRoutePattern extends string = string, TData = unknown> {
+  (args: LoaderFunctionArgs<TRoutePattern>): TData;
 }
 
 /**
@@ -344,14 +280,9 @@ export type Route = {
   readonly index: boolean;
 
   /**
-   * 実際の URL パスがこのルートに合致するかを検証するために動的に生成された正規表現オブジェクトです。
-   */
-  readonly pathPattern: RegExp;
-
-  /**
-   * パスパターン内に含まれるパラメーターのキー名を、順番通りに格納した読み取り専用の配列です。
+   * ルートパターンの解析などを行うユーティリティーです。
    */
-  readonly paramKeys: readonly string[];
+  readonly utils: RoutePatternUtils;
 
   /**
    * データ更新用のアクション関数です。未定義の場合は `undefined` となります。

package/src/core/start-action.ts

@@ -6,7 +6,7 @@ import type { MatchedRoute } from "./match-routes.js";
 import type { ReadonlyFormData } from "./readonly-form-data.types.js";
 import RedirectResponse from "./redirect-response.js";
 import RouteRequest from "./route-request.js";
-import type { ActionFunction, RoutePathParams } from "./route.types.js";
+import type { ActionFunction, RouteParams } from "./route.types.js";
 
 /**
  * アクション処理の実行開始時に必要となる、起点リクエスト情報の型定義です。
@@ -64,7 +64,7 @@ export default function startAction(
   request: ActionStartRequest,
 ): StartedAction | null {
   let action: ActionFunction | undefined;
-  let params: RoutePathParams;
+  let params: RouteParams;
   let urlPath: string;
 
   for ({ action, params, urlPath } of routes) {

package/src/engines/navigation-api-engine.ts

@@ -105,8 +105,7 @@ export default class NavigationApiEngine implements IEngine {
      * ユーザーのアクションによって発生したすべての遷移要求をインターセプトして処理する、ルーティングの中枢ハンドラーです。
      */
     const handleNavigate = (event: NavigateEvent): void => {
-      // 処理すべきでない通常のブラウザー固有のナビゲーション（ハッシュ変更、ファイルのダウンロードなど）は、
-      // 標準の挙動を妨げないようにインターセプトせず即座にスルーします。
+      // 処理すべきでない通常のブラウザー固有のナビゲーション（ハッシュ変更、ファイルのダウンロードなど）は、標準の挙動を妨げないようにインターセプトせず即座にスルーします。
       // 参照: https://developer.mozilla.org/docs/Web/API/Navigation_API#handling_a_navigation_using_intercept
       if (
         !event.isTrusted ||
@@ -187,8 +186,7 @@ export default class NavigationApiEngine implements IEngine {
           switch (action.data.status) {
             case "rejected": {
               // アクションがエラーで失敗した場合は、URL を変更せず現在の元のページに強制リダイレクトさせます。
-              const { pathname, search, hash } = currentEntry.url;
-              controller.redirect(pathname + search + hash);
+              controller.redirect(RoutePath.encode(currentEntry.url));
 
               break;
             }
@@ -197,12 +195,12 @@ export default class NavigationApiEngine implements IEngine {
               // アクションが正常終了した場合、返り値にリダイレクト指示が含まれていればその目的地へ遷移させます。
               // リダイレクトがなければそのまま本来の目的地へとブラウザーのコミット先を書き換えます。
               const { redirectTo = currentEntry.url } = actionResponse;
-              const { pathname, search, hash } = redirectTo;
-              controller.redirect(pathname + search + hash);
+              const redirectPath = new RoutePath(redirectTo);
+              controller.redirect(redirectPath.toString());
 
-              redirectUrl.pathname = pathname;
-              redirectUrl.search = search;
-              redirectUrl.hash = hash;
+              redirectUrl.pathname = redirectPath.pathname;
+              redirectUrl.search = redirectPath.search;
+              redirectUrl.hash = redirectPath.hash;
 
               break;
             }

package/src/hooks/use-params.ts

@@ -1,4 +1,4 @@
-import type { RoutePathParams } from "../core/route.types.js";
+import type { RouteParams } from "../core/route.types.js";
 import useRouteContext from "./use-route-context.js";
 
 /**
@@ -6,6 +6,6 @@ import useRouteContext from "./use-route-context.js";
  *
  * @returns 現在のパスパラメーターを含むオブジェクトを返します。
  */
-export default function useParams<TPath extends string = string>(): RoutePathParams<TPath> {
-  return useRouteContext().params as RoutePathParams<TPath>;
+export default function useParams<TPath extends string = string>(): RouteParams<TPath> {
+  return useRouteContext().params as RouteParams<TPath>;
 }

package/src/soseki.ts

@@ -37,6 +37,9 @@ export type * from "./core/readonly-url.types.js";
 export type * from "./core/redirect-response.js";
 export { default as RedirectResponse } from "./core/redirect-response.js";
 
+export type * from "./core/route-pattern-utils.js";
+export { default as RoutePatternUtils } from "./core/route-pattern-utils.js";
+
 export type * from "./core/route-request.js";
 export { default as RouteRequest } from "./core/route-request.js";
 

package/dist/src/core/_match-route-path.d.ts

@@ -1,22 +0,0 @@
-import type { ReadonlyURL } from "./readonly-url.types.js";
-import type { Route, RoutePathParams } from "./route.types.js";
-/**
- * パスマッチングの処理結果を表すオブジェクトの型定義です。
- */
-export type MatchPathResult = {
-    /**
-     * マッチした URL パスから抽出されたパラメーターのキーと値のオブジェクトです。
-     */
-    params: RoutePathParams;
-};
-/**
- * 指定されたルートの正規表現パターンと URL のパス部分を照合し、マッチング検証およびパラメーター抽出を行う関数です。
- *
- * ルーティングエンジンが、現在の遷移先 URL に適合するルートを特定し、動的セグメントの値を型安全に回収する目的で使用します。
- *
- * @param route 検証対象となるルートオブジェクトから、マッチングに必要な `paramKeys` と `pathPattern` を抽出したオブジェクトです。
- * @param url マッチングの判定元となる、読み取り専用の URL オブジェクトです。
- * @returns マッチした場合は抽出されたパラメーターを含む `MatchPathResult` を返し、マッチしなかった場合は `null` を返します。
- */
-export default function matchPath(route: Pick<Route, "paramKeys" | "pathPattern">, url: ReadonlyURL): MatchPathResult | null;
-//# sourceMappingURL=_match-route-path.d.ts.map

package/dist/src/core/_match-route-path.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_match-route-path.d.ts","sourceRoot":"","sources":["../../../src/core/_match-route-path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;OAEG;IACH,MAAM,EAAE,eAAe,CAAC;CACzB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAAC,EAC/C,GAAG,EAAE,WAAW,GACf,eAAe,GAAG,IAAI,CAmBxB"}