soseki 0.0.5 → 0.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026-present, tai-kun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/src/components/browser-router.d.ts

@@ -0,0 +1,19 @@
+import type { RouteDefinition } from "../core/route.types.js";
+/**
+ * `BrowserRouter` コンポーネントに引き渡すプロパティーの型定義です。
+ */
+export type BrowserRouterProps = {
+    /**
+     * アプリケーション全体の画面構造を定義したルート定義の配列です。
+     */
+    routes: readonly RouteDefinition[];
+};
+/**
+ * ブラウザー環境における SPA ルーティングを開始するための、最上位エントリーポイントコンポーネントです。
+ *
+ * モダンなブラウザー標準の `Navigation API` に依存しています。
+ *
+ * @param props アプリケーションに組み込むルート定義の配列です。
+ */
+export default function BrowserRouter(props: BrowserRouterProps): React.ReactElement;
+//# sourceMappingURL=browser-router.d.ts.map

package/dist/src/components/browser-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-router.d.ts","sourceRoot":"","sources":["../../../src/components/browser-router.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,CAAC,YAAY,CAKnF"}

package/dist/src/components/browser-router.jsx

@@ -0,0 +1,15 @@
+import NavigationApiEngine from "../engines/navigation-api-engine.js";
+import useSingleton from "../hooks/_use-singleton.js";
+import Router from "./router.jsx";
+/**
+ * ブラウザー環境における SPA ルーティングを開始するための、最上位エントリーポイントコンポーネントです。
+ *
+ * モダンなブラウザー標準の `Navigation API` に依存しています。
+ *
+ * @param props アプリケーションに組み込むルート定義の配列です。
+ */
+export default function BrowserRouter(props) {
+    const { routes } = props;
+    const engine = useSingleton(() => new NavigationApiEngine());
+    return <Router engine={engine} routes={routes}/>;
+}

package/dist/src/components/outlet.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+/**
+ * ネストされたルーティング構造において、親ルートのレイアウト内にマッチした子ルートを適切な位置にはめ込んで描画するためのプレースホルダーコンポーネントです。
+ *
+ * @returns 描画すべき子ルートの React 要素を返します。これ以上下位のルートがない場合は `null` を返します。
+ */
+export default function Outlet(): React.ReactElement | null;
+//# sourceMappingURL=outlet.d.ts.map

package/dist/src/components/outlet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outlet.d.ts","sourceRoot":"","sources":["../../../src/components/outlet.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,IAAI,KAAK,CAAC,YAAY,GAAG,IAAI,CAO1D"}

package/dist/src/components/outlet.jsx

@@ -0,0 +1,15 @@
+import * as React from "react";
+import RouteContext from "../contexts/route-context.js";
+import { RouteContextMissingError } from "../core/errors.js";
+/**
+ * ネストされたルーティング構造において、親ルートのレイアウト内にマッチした子ルートを適切な位置にはめ込んで描画するためのプレースホルダーコンポーネントです。
+ *
+ * @returns 描画すべき子ルートの React 要素を返します。これ以上下位のルートがない場合は `null` を返します。
+ */
+export default function Outlet() {
+    const routeContext = React.use(RouteContext);
+    if (!routeContext) {
+        throw new RouteContextMissingError();
+    }
+    return routeContext.outlet;
+}

package/dist/src/components/router.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import type { RouteDefinition } from "../core/route.types.js";
+import type { IEngine } from "../engines/engine.types.js";
+/**
+ * `Router` コンポーネントに渡されるルートプロパティーの型定義です。
+ */
+export type RouterProps = {
+    /**
+     * プラグイン形式で差し込まれる、ルーティングの実装です。
+     */
+    engine: IEngine;
+    /**
+     * ユーザーがアプリケーションに定義したルート定義の配列です。
+     */
+    routes: readonly RouteDefinition[];
+};
+/**
+ * 宣言的なルート定義と、命令的なルーティング実行エンジンを仲介・統合し、アプリケーションの最上位でルーティングのライフサイクルと状態管理を司るプロバイダーコンポーネントです。
+ */
+export default function Router(props: RouterProps): React.JSX.Element | null;
+//# sourceMappingURL=router.d.ts.map

package/dist/src/components/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/components/router.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9F,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,4BAA4B,CAAC;AAkEvE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,KAAK,EAAE,WAAW,4BAkIhD"}

package/dist/src/components/router.jsx

@@ -0,0 +1,138 @@
+import * as React from "react";
+import RouteContext from "../contexts/route-context.js";
+import RouterContext from "../contexts/router-context.js";
+import processRoutes from "../core/_process-routes.js";
+/**
+ * マッチした個々のルートコンポーネントを、固有の `RouteContext` で包み込みながら再帰的にマウント・展開していくための内部レンダラーコンポーネントです。
+ */
+function ComponentRenderer(props) {
+    const parentRoute = React.use(RouteContext);
+    const { route, outlet } = props;
+    const context = {
+        ...route,
+        outlet,
+        // 親ルートのアクションとローダーを引き継ぐことで、`useActionData` と `useLoaderData` がデータを参照できようにします。
+        action: route.action ?? parentRoute?.action,
+        loader: route.loader ?? parentRoute?.loader,
+    };
+    const Comp = route.component;
+    return (<RouteContext value={context}>{typeof Comp === "function" ? <Comp /> : outlet}</RouteContext>);
+}
+/**
+ * マッチしたルート配列を親から子の順番へと正しく巡回し、各階層を入れ子状の React エレメントツリーへと再帰的にビルドするコンポーネントです。
+ */
+function RouteRenderer(props) {
+    const { index = 0, routes } = props;
+    const route = routes[index];
+    // 配列の終端に達していない場合はインデックスを 1 進めて自身を再帰的に呼び出し、ネストされる子要素を生成します。
+    const outlet = index < routes.length - 1 ? <RouteRenderer routes={routes} index={index + 1}/> : null;
+    return <ComponentRenderer route={route} outlet={outlet}/>;
+}
+/**
+ * 宣言的なルート定義と、命令的なルーティング実行エンジンを仲介・統合し、アプリケーションの最上位でルーティングのライフサイクルと状態管理を司るプロバイダーコンポーネントです。
+ */
+export default function Router(props) {
+    const { engine, routes: routesProp } = props;
+    // レンダリングを跨いで常に同一参照を維持し、かつ子コンポーネントから不要な再レンダリングなしでメソッドを叩けるように、ルーターコアの外部参照実体を useRef で永続管理します。
+    const routerRef = React.useRef({});
+    // エンジン、ストア、イベント購読メカニズムのセットアップを一元化し、useMemo でインスタンス化します。
+    const router = React.useMemo(() => {
+        const actionDataStore = new Map();
+        const loaderDataStore = new Map();
+        const subscribers = new Set();
+        const routes = processRoutes(routesProp);
+        let ac = null;
+        /**
+         * 現在のフェーズで有効な、シングルトン構造の中断シグナルをオンデマンドで生成・回収します。
+         */
+        function getAbortSignal() {
+            return (ac || (ac = new AbortController())).signal;
+        }
+        // エンジンを初期化し、初期ロード時のマッチングルートおよび解決済みのデータマップを取得・登録します。
+        const initialState = engine.init({
+            routes,
+            getSignal: getAbortSignal,
+            loaderDataStore,
+        });
+        let currentRoutes = initialState?.routes;
+        /**
+         * エンジン内部での遷移確定時に、状態を React 側へ通知・マージするための状態更新関数です。
+         */
+        function updateRouter(newState) {
+            if (newState !== undefined) {
+                currentRoutes = newState?.routes;
+            }
+            if (newState) {
+                routerRef.current.currentEntry = newState.entry;
+            }
+            // 状態変更の発生を、React の useSyncExternalStore などのすべての購読者に一斉通知して再描画を促します。
+            subscribers.forEach((notify) => notify());
+        }
+        /**
+         * エンジンによるイベントのリアルタイム監視を開始するトリガー関数です。
+         */
+        function startRouterEngine() {
+            const stop = engine.start({
+                routes,
+                update: updateRouter,
+                getSignal: getAbortSignal,
+                actionDataStore,
+                loaderDataStore,
+            });
+            return function stopRouterEngine() {
+                try {
+                    if (typeof stop === "function") {
+                        stop();
+                    }
+                }
+                finally {
+                    try {
+                        ac?.abort();
+                    }
+                    catch { }
+                    ac = null;
+                }
+            };
+        }
+        // 作成した各種ストアや命令型メソッドの参照を、永続化 Ref オブジェクトへと安全にマージします。
+        Object.assign(routerRef.current, {
+            submit(args) {
+                return engine.submit(args);
+            },
+            navigate(args) {
+                return engine.navigate(args);
+            },
+            currentEntry: initialState?.entry,
+            actionDataStore,
+            loaderDataStore,
+        });
+        return {
+            start: startRouterEngine,
+            context: {
+                routerRef,
+                subscribe(cb) {
+                    subscribers.add(cb);
+                    return () => {
+                        subscribers.delete(cb);
+                    };
+                },
+            },
+            getRoutes() {
+                return currentRoutes;
+            },
+        };
+    }, [engine, routesProp]);
+    // コンポーネントのマウント時にルーターエンジンを始動させ、アンマウント時には自動的に破棄タスクを連動させます。
+    React.useEffect(() => router.start(), [router]);
+    // マッチしたルート階層配列をリアクティブに常時監視します。
+    const routes = React.useSyncExternalStore(router.context.subscribe, router.getRoutes);
+    // 有効なルートマッチングがない場合は何も描画しません。
+    if (!routes) {
+        // TODO(tai-kun): 404 Not Found ページを表示できるようにします。
+        return null;
+    }
+    return (<RouterContext value={router.context}>
+      {/* マッチルート配列は詳細度の高い「子 -> 親」の順で並んでいるため、React のネストレイアウト構造（親の中に子を入れる）に適合させるために `.toReversed()` で「親 -> 子」の順に反転させてからレンダラーへ投入します。*/}
+      <RouteRenderer routes={routes.toReversed()}/>
+    </RouterContext>);
+}

package/dist/src/contexts/route-context.d.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+import type { MatchedRoute } from "../core/match-routes.js";
+/**
+ * 現在のコンポーネント階層に紐づいている個別ルートのコンテキスト形状定義です。
+ */
+export type RouteContextValue = MatchedRoute & {
+    /**
+     * 現在のルートの下位に位置する子ルートを表示するための React 要素です。
+     *
+     * これ以上下位にマッチする子ルートが存在しない場合は `null` になります。
+     */
+    readonly outlet: React.ReactElement | null;
+};
+/**
+ * 階層的にネストされたルーターのレイアウト構造において、親ルートから子ルートへそれぞれの階層固有のルート情報伝播させるための React コンテキストです。
+ */
+declare const RouteContext: React.Context<RouteContextValue | null>;
+export default RouteContext;
+//# sourceMappingURL=route-context.d.ts.map

package/dist/src/contexts/route-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-context.d.ts","sourceRoot":"","sources":["../../../src/contexts/route-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF;;GAEG;AACH,QAAA,MAAM,YAAY,yCAAoE,CAAC;AAEvF,eAAe,YAAY,CAAC"}

package/dist/src/contexts/route-context.js

@@ -0,0 +1,6 @@
+import * as React from "react";
+/**
+ * 階層的にネストされたルーターのレイアウト構造において、親ルートから子ルートへそれぞれの階層固有のルート情報伝播させるための React コンテキストです。
+ */
+const RouteContext = /*#__PURE__*/ React.createContext(null);
+export default RouteContext;

package/dist/src/contexts/router-context.d.ts

@@ -0,0 +1,55 @@
+import type { NinjaPromise } from "ninja-promise";
+import * as React from "react";
+import type { HistoryEntry } from "../core/expect-history-entry.js";
+import type { HistoryEntryId } from "../core/history-entry-id-schema.js";
+import type { ActionFunction, LoaderFunction } from "../core/route.types.js";
+import type { IEngine } from "../engines/engine.types.js";
+/**
+ * ルーターの実体へのアクセスを提供する、読み取り専用の Ref オブジェクト型です。
+ */
+export type RouterRef = Readonly<React.RefObject<{
+    /**
+     * フォームデータやクエリーパラメーターをルーターに送信するための関数です。
+     */
+    readonly submit: (args: IEngine.SubmitArgs) => void;
+    /**
+     * URL 遷移や履歴スタックの相対移動をルーターに命令するための関数です。
+     */
+    readonly navigate: (args: IEngine.NavigateArgs) => void;
+    /**
+     * 現在ブラウザー上でアクティブになっている履歴エントリーの情報です。
+     */
+    readonly currentEntry: HistoryEntry;
+    /**
+     * 履歴エントリーの ID ごとにアクションの実行状態を管理するデータストアです。
+     */
+    readonly actionDataStore: ReadonlyMap<HistoryEntryId, ReadonlyMap<ActionFunction, NinjaPromise<unknown>>>;
+    /**
+     * 履歴エントリーの ID ごとにローダーの実行状態を管理するデータストアです。
+     */
+    readonly loaderDataStore: ReadonlyMap<HistoryEntryId, ReadonlyMap<LoaderFunction, NinjaPromise<unknown>>>;
+}>>;
+/**
+ * `RouterContext` がコンポーネントツリーの配下に供給するオブジェクトの型定義です。
+ */
+export type RouterContextValue = {
+    /**
+     * ルーターの最新実体への参照を保持する Ref オブジェクトです。
+     */
+    readonly routerRef: RouterRef;
+    /**
+     * ルーターの状態変更を監視するための購読関数です。
+     *
+     * @param onRouterChange ルーターの内部状態が変化した際に実行されるコールバック関数です。
+     * @returns 監視を安全に解除するためのクリーンアップ関数を返します。
+     */
+    readonly subscribe: (onRouterChange: () => void) => () => void;
+};
+/**
+ * アプリケーションの最上位からルーターのグローバル状態を子コンポーネントへ一元的に伝播させるための React コンテキストです。
+ *
+ * パフォーマンス最適化のためにプロバイダー自体は基本的に更新されず、子コンポーネントは `subscribe` と `useSyncExternalStore`を使って必要な部分データだけを購読します。
+ */
+declare const RouterContext: React.Context<RouterContextValue | null>;
+export default RouterContext;
+//# sourceMappingURL=router-context.d.ts.map

package/dist/src/contexts/router-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-context.d.ts","sourceRoot":"","sources":["../../../src/contexts/router-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,CAC9B,KAAK,CAAC,SAAS,CAAC;IACd;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,KAAK,IAAI,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,KAAK,IAAI,CAAC;IAExD;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,WAAW,CACnC,cAAc,EACd,WAAW,CAAC,cAAc,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CACnD,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,WAAW,CACnC,cAAc,EACd,WAAW,CAAC,cAAc,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CACnD,CAAC;CACH,CAAC,CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,cAAc,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CAChE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,aAAa,0CAAqE,CAAC;AAEzF,eAAe,aAAa,CAAC"}

package/dist/src/contexts/router-context.js

@@ -0,0 +1,8 @@
+import * as React from "react";
+/**
+ * アプリケーションの最上位からルーターのグローバル状態を子コンポーネントへ一元的に伝播させるための React コンテキストです。
+ *
+ * パフォーマンス最適化のためにプロバイダー自体は基本的に更新されず、子コンポーネントは `subscribe` と `useSyncExternalStore`を使って必要な部分データだけを購読します。
+ */
+const RouterContext = /*#__PURE__*/ React.createContext(null);
+export default RouterContext;

package/dist/src/core/_compare-route-paths.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 2つのルートパスの優先順位を比較し、ソート順を決定するための比較関数です。
+ *
+ * より具体的で制限の厳しいパス（詳細度スコアが高いパス）が、ソート結果においてより前方に配置されるように負の値を返します。
+ *
+ * @param pathA 比較対象となる1つ目のパス文字列です。
+ * @param pathB 比較対象となる2つ目のパス文字列です。
+ * @returns `pathA` を優先する場合は負の数、`pathB` を優先する場合は正の数、等価である場合は `0` を返します。
+ */
+export default function compareRoutePaths(pathA: string, pathB: string): number;
+//# sourceMappingURL=_compare-route-paths.d.ts.map

package/dist/src/core/_compare-route-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_compare-route-paths.d.ts","sourceRoot":"","sources":["../../../src/core/_compare-route-paths.ts"],"names":[],"mappings":"AA+DA;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA+B9E"}

package/dist/src/core/_compare-route-paths.js

@@ -0,0 +1,92 @@
+/**
+ * セグメントの種類に応じたスコア定数です。
+ *
+ * 数値が大きいほど優先順位（詳細度）が高いです。
+ *
+ * 詳細度（regexparam の README より）:
+ * | 順位 | 種別 | 例 |
+ * | --: | :-- | :-- |
+ * | 1 | Static                | `/foo`, `/foo/bar`                                    |
+ * | 2 | Parameter with suffix | `/movies/:title.mp4`, `/movies/:title.(mp4\|mov)`     |
+ * | 3 | Parameter             | `/:title`, `/books/:title`, `/books/:genre/:title`    |
+ * | 4 | Optional Parameters   | `/:title?`, `/books/:title?`, `/books/:genre/:title?` |
+ * | 5 | Wildcards             | `*`, `/books/*`, `/books/:genre/*`                    |
+ * | 6 | Optional Wildcard     | `/books/*?`                                           |
+ *
+ * @see https://github.com/lukeed/regexparam
+ */
+const SCORE = {
+    PARAM: 4,
+    STATIC: 6,
+    WILDCARD: 2,
+    OPTIONAL_PARAM: 3,
+    OPTIONAL_WILDCARD: 1,
+    PARAM_WITH_SUFFIX: 5,
+};
+/**
+ * 与えられた単一のセグメント文字列を解析し、その特性に応じた詳細度スコアを算出します。
+ *
+ * @param s 解析対象となるセグメント文字列です。
+ * @returns セグメントの種別に対応する、`SCORE` 定数から抽出された数値スコアです。
+ */
+function getSegmentScore(s) {
+    if (s === "*?") {
+        return SCORE.OPTIONAL_WILDCARD;
+    }
+    if (s === "*") {
+        return SCORE.WILDCARD;
+    }
+    if (s[0] === ":") {
+        if (s[s.length - 1] === "?") {
+            return SCORE.OPTIONAL_PARAM;
+        }
+        if (s.indexOf(".") < 0) {
+            return SCORE.PARAM;
+        }
+        return SCORE.PARAM_WITH_SUFFIX;
+    }
+    return SCORE.STATIC;
+}
+/**
+ * 英語のロケール設定に基づき、大文字小文字などを標準化した文字列比較を行うための `Intl.Collator` インスタンスです。
+ *
+ * 決定論的な辞書順ソートを保証するために使用します。
+ */
+const enCollator = new Intl.Collator("en");
+/**
+ * 2つのルートパスの優先順位を比較し、ソート順を決定するための比較関数です。
+ *
+ * より具体的で制限の厳しいパス（詳細度スコアが高いパス）が、ソート結果においてより前方に配置されるように負の値を返します。
+ *
+ * @param pathA 比較対象となる1つ目のパス文字列です。
+ * @param pathB 比較対象となる2つ目のパス文字列です。
+ * @returns `pathA` を優先する場合は負の数、`pathB` を優先する場合は正の数、等価である場合は `0` を返します。
+ */
+export default function compareRoutePaths(pathA, pathB) {
+    const partsA = pathA.split("/").filter(Boolean);
+    const partsB = pathB.split("/").filter(Boolean);
+    const length = Math.max(partsA.length, partsB.length);
+    for (let i = 0; i < length; i++) {
+        const a = partsA[i];
+        // パス A のセグメントが先に終了した場合は、パス B を優先します。
+        if (a === undefined) {
+            return 1;
+        }
+        const b = partsB[i];
+        // パス B のセグメントが先に終了した場合は、パス A を優先します。
+        if (b === undefined) {
+            return -1;
+        }
+        const scoreA = getSegmentScore(a);
+        const scoreB = getSegmentScore(b);
+        // スコアが異なる場合は、スコアが高い方を優先します。
+        if (scoreA !== scoreB) {
+            return scoreB - scoreA;
+        }
+        // スコアが同じ場合は、文字列の辞書順で比較します。
+        if (a !== b) {
+            return enCollator.compare(a, b);
+        }
+    }
+    return 0;
+}

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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1 @@
+{"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"}

package/dist/src/core/_match-route-path.js

@@ -0,0 +1,26 @@
+/**
+ * 指定されたルートの正規表現パターンと URL のパス部分を照合し、マッチング検証およびパラメーター抽出を行う関数です。
+ *
+ * ルーティングエンジンが、現在の遷移先 URL に適合するルートを特定し、動的セグメントの値を型安全に回収する目的で使用します。
+ *
+ * @param route 検証対象となるルートオブジェクトから、マッチングに必要な `paramKeys` と `pathPattern` を抽出したオブジェクトです。
+ * @param url マッチングの判定元となる、読み取り専用の URL オブジェクトです。
+ * @returns マッチした場合は抽出されたパラメーターを含む `MatchPathResult` を返し、マッチしなかった場合は `null` を返します。
+ */
+export default function matchPath(route, url) {
+    const matches = route.pathPattern.exec(url.pathname);
+    if (!matches) {
+        return null;
+    }
+    const params = {};
+    for (let i = 0, param; i < route.paramKeys.length; i++) {
+        // exec メソッドの戻り値のインデックス 0 にはマッチした文字列全体が格納されているため、各パラメーターの値はインデックス 1 以降（i + 1）から取得します。
+        param = matches[i + 1];
+        // キャプチャーされたセグメントが存在し、かつ文字列型である場合にのみ、対応するパラメーターキーと値をマッピングします。
+        // オプショナルなパラメーターが URL 側で省略されている場合は undefined となるため、この条件節により除外されます。
+        if (typeof param === "string") {
+            params[route.paramKeys[i]] = param;
+        }
+    }
+    return { params };
+}

package/dist/src/core/_process-routes.d.ts

@@ -0,0 +1,14 @@
+import type { Route, RouteDefinition } from "./route.types.js";
+/**
+ * 定義したルーティング設定の配列を、内部のルーティングエンジンが直接利用可能な正規化済みのルートオブジェクトの配列へと変換します。
+ *
+ * 実行内容:
+ * - 各ルートのパス正規化
+ * - 動的解析用の正規表現コンパイル
+ * - 詳細度に基づく優先順位ソート
+ *
+ * @param routes ルーティング定義を格納した読み取り専用の配列です。
+ * @returns 読み取り専用の正規化済みルートオブジェクトの配列です。
+ */
+export default function processRoutes(routes: readonly RouteDefinition[]): readonly Route[];
+//# sourceMappingURL=_process-routes.d.ts.map

package/dist/src/core/_process-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_process-routes.d.ts","sourceRoot":"","sources":["../../../src/core/_process-routes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,KAAK,EAAE,CAoC1F"}

package/dist/src/core/_process-routes.js

@@ -0,0 +1,45 @@
+import { parse } from "regexparam";
+import compareRoutePaths from "./_compare-route-paths.js";
+import RoutePath from "./route-path.js";
+/**
+ * 定義したルーティング設定の配列を、内部のルーティングエンジンが直接利用可能な正規化済みのルートオブジェクトの配列へと変換します。
+ *
+ * 実行内容:
+ * - 各ルートのパス正規化
+ * - 動的解析用の正規表現コンパイル
+ * - 詳細度に基づく優先順位ソート
+ *
+ * @param routes ルーティング定義を格納した読み取り専用の配列です。
+ * @returns 読み取り専用の正規化済みルートオブジェクトの配列です。
+ */
+export default function processRoutes(routes) {
+    return (routes
+        .map((route) => {
+        const path = RoutePath.encode(route.path);
+        const index = route.index === true;
+        const { keys: paramKeys, pattern: pathPattern } = parse(path, 
+        // インデックスルートでないとき loose オプションを `true` にして子ルートに対してもマッチするようにします。
+        // これにより、前方一致による階層的なマッチングが有効になります。
+        !index);
+        return {
+            path,
+            index,
+            action: route.action,
+            loader: route.loader,
+            // オブジェクト形式またはモジュール形式の双方を安全に評価し、描画対象となる React コンポーネントを確定します。
+            component: typeof route.component === "function"
+                ? route.component
+                : Symbol.toStringTag in route &&
+                    route[Symbol.toStringTag] === "Module" &&
+                    typeof route.default === "function"
+                    ? route.default
+                    : undefined,
+            paramKeys,
+            pathPattern,
+            shouldReload: route.shouldReload || ((args) => args.defaultShouldReload),
+        };
+    })
+        // すべてのルートを正規化した後、compareRoutePaths 関数を用いて詳細度が高い順にソートします。
+        // マッチング漏れや誤ったルートへの誤認を防ぐため、制限の厳しい（具体的な）パスパターンを持つルートオブジェクトが配列のより前方に配置されます。
+        .sort((a, b) => compareRoutePaths(a.path, b.path)));
+}

package/dist/src/core/_singleton.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 指定された識別子に対して、渡されたファクトリー関数を一度だけ実行し、その生成結果をシングルトンとして永続化および共有します。
+ *
+ * 2回目以降の呼び出しでは、ファクトリー関数は実行されず、初回に生成されたキャッシュデータが即座に返されます。
+ *
+ * @template T ファクトリー関数が生成するシングルトンオブジェクトの型定義です。
+ * @param key シングルトンオブジェクトをキャッシュ内で一意に識別するためのキーです。
+ * @param fn 初回呼び出し時にのみ実行される、オブジェクト生成用のファクトリー関数です。
+ * @returns 初回実行時に生成された、またはキャッシュから回収された型 `T` のシングルトンインスタンスを返します。
+ */
+export default function singleton<T>(key: unknown, fn: (...args: any) => T): T;
+//# sourceMappingURL=_singleton.d.ts.map

package/dist/src/core/_singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_singleton.d.ts","sourceRoot":"","sources":["../../../src/core/_singleton.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAE7E"}

package/dist/src/core/_singleton.js

@@ -0,0 +1,18 @@
+import { callFnOnce } from "call-fn-once";
+/**
+ * 初回実行時の生成結果を保持するためのグローバルなキャッシュ管理マップです。
+ */
+const cacheMap = new Map();
+/**
+ * 指定された識別子に対して、渡されたファクトリー関数を一度だけ実行し、その生成結果をシングルトンとして永続化および共有します。
+ *
+ * 2回目以降の呼び出しでは、ファクトリー関数は実行されず、初回に生成されたキャッシュデータが即座に返されます。
+ *
+ * @template T ファクトリー関数が生成するシングルトンオブジェクトの型定義です。
+ * @param key シングルトンオブジェクトをキャッシュ内で一意に識別するためのキーです。
+ * @param fn 初回呼び出し時にのみ実行される、オブジェクト生成用のファクトリー関数です。
+ * @returns 初回実行時に生成された、またはキャッシュから回収された型 `T` のシングルトンインスタンスを返します。
+ */
+export default function singleton(key, fn) {
+    return callFnOnce(cacheMap, key, fn);
+}