soseki 0.0.5 → 0.0.7

package/src/components/router.tsx

@@ -1,233 +1,227 @@
+import type { NinjaPromise } from "ninja-promise";
 import * as React from "react";
+
 import RouteContext from "../contexts/route-context.js";
 import RouterContext, {
-  type RouterContextValue,
   type RouterRef,
+  type RouterContextValue,
 } from "../contexts/router-context.js";
 import processRoutes from "../core/_process-routes.js";
-import type { IDataStore } from "../core/data-store.types.js";
 import type { HistoryEntry } from "../core/expect-history-entry.js";
+import type { HistoryEntryId } from "../core/history-entry-id-schema.js";
 import type { MatchedRoute } from "../core/match-routes.js";
-import type { IAction, ILoader, RouteDefinition } from "../core/route.types.js";
-import type { IEngine, RouterState, SubmitArgs } from "../engines/engine.types.js";
-import type { NavigateArgs } from "../engines/engine.types.js";
+import type { ActionFunction, LoaderFunction, RouteDefinition } from "../core/route.types.js";
+import type { IEngine, RouterState } from "../engines/engine.types.js";
 
 /**
- * ComponentRenderer コンポーネントに渡されるプロパティーの型定義です。
+ * `ComponentRenderer` コンポーネントに渡されるプロパティーの型定義です。
  */
 type ComponentRendererProps = {
   /**
-   * 現在のコンテキストでレンダリングされる、マッチしたルート情報です。
+   * レンダリング対象となる、マッチした単一のルート情報です。
    */
   route: MatchedRoute;
 
   /**
-   * ネストされた下位のルート要素です。存在しない場合は null を指定します。
+   * このルートの配下に描画されるべき子コンポーネントの要素です。
    */
   outlet: React.ReactElement<RouteRendererProps, typeof RouteRenderer> | null;
 };
 
 /**
- * 個別のルートコンポーネントをレンダリングし、ルートコンテキストを提供する内部コンポーネントです。
+ * マッチした個々のルートコンポーネントを、固有の `RouteContext` で包み込みながら再帰的にマウント・展開していくための内部レンダラーコンポーネントです。
  */
 function ComponentRenderer(props: ComponentRendererProps): React.JSX.Element | null {
-  const {
-    route: {
-      path,
-      index,
-      params,
-      urlPath,
-      component: Component,
-    },
-    outlet,
-  } = props;
+  const parentRoute = React.use(RouteContext);
+  const { route, outlet } = props;
   const context = {
-    path,
-    index,
-    params,
+    ...route,
     outlet,
-    urlPath,
+    // 親ルートのアクションとローダーを引き継ぐことで、`useActionData` と `useLoaderData` がデータを参照できようにします。
+    action: route.action ?? parentRoute?.action,
+    loader: route.loader ?? parentRoute?.loader,
   };
+  const Comp = route.component;
 
   return (
-    <RouteContext value={context}>
-      {Component ? <Component /> : outlet}
-    </RouteContext>
+    <RouteContext value={context}>{typeof Comp === "function" ? <Comp /> : outlet}</RouteContext>
   );
 }
 
 /**
- * マッチしたルートを再帰的にレンダリングするためのプロパティーです。
+ * `RouteRenderer` コンポーネントに渡されるプロパティーの型定義です。
  */
 type RouteRendererProps = {
   /**
-   * 現在のパスにマッチしたルートの配列です。
+   * マッチしたルートの階層配列です。
    */
   routes: readonly MatchedRoute[];
 
   /**
-   * 現在レンダリング対象となっているルートのインデックス番号です。
+   * 現在処理しているルート配列のインデックス（深さ）です。
    */
   index?: number;
 };
 
 /**
- * マッチしたルートの階層を順番にレンダリングする内部コンポーネントです。
+ * マッチしたルート配列を親から子の順番へと正しく巡回し、各階層を入れ子状の React エレメントツリーへと再帰的にビルドするコンポーネントです。
  */
 function RouteRenderer(props: RouteRendererProps): React.ReactElement {
-  const {
-    index = 0,
-    routes,
-  } = props;
+  const { index = 0, routes } = props;
   const route = routes[index]!;
-  const outlet = index < routes.length - 1
-    ? <RouteRenderer routes={routes} index={index + 1} />
-    : null;
 
-  return (
-    <ComponentRenderer
-      route={route}
-      outlet={outlet}
-    />
-  );
+  // 配列の終端に達していない場合はインデックスを 1 進めて自身を再帰的に呼び出し、ネストされる子要素を生成します。
+  const outlet =
+    index < routes.length - 1 ? <RouteRenderer routes={routes} index={index + 1} /> : null;
+
+  return <ComponentRenderer route={route} outlet={outlet} />;
 }
 
 /**
- * Router コンポーネントに渡されるプロパティーの型定義です。
+ * `Router` コンポーネントに渡されるルートプロパティーの型定義です。
  */
 export type RouterProps = {
   /**
-   * ルーティングのロジックを制御するエンジンインスタンスです。
+   * プラグイン形式で差し込まれる、ルーティングの実装です。
    */
   engine: IEngine;
 
   /**
-   * アプリケーションのルート定義の配列です。
+   * ユーザーがアプリケーションに定義したルート定義の配列です。
    */
   routes: readonly RouteDefinition[];
 };
 
 /**
- * ルーティング機能を提供するメインのコンポーネントです。
- *
- * エンジンの管理、状態の同期、およびルートのレンダリングを担います。
+ * 宣言的なルート定義と、命令的なルーティング実行エンジンを仲介・統合し、アプリケーションの最上位でルーティングのライフサイクルと状態管理を司るプロバイダーコンポーネントです。
  */
 export default function Router(props: RouterProps) {
-  const {
-    engine,
-    routes: routesProp,
-  } = props;
-  const routerRef = React.useRef({} as {
-    submit(args: SubmitArgs): void;
-    navigate(args: NavigateArgs): void;
-    currentEntry: HistoryEntry;
-    actionDataStore: IDataStore<IAction>;
-    loaderDataStore: IDataStore<ILoader>;
-  });
+  const { engine, routes: routesProp } = props;
+
+  // レンダリングを跨いで常に同一参照を維持し、かつ子コンポーネントから不要な再レンダリングなしでメソッドを叩けるように、ルーターコアの外部参照実体を useRef で永続管理します。
+  const routerRef = React.useRef(
+    {} as {
+      submit(args: IEngine.SubmitArgs): void;
+      navigate(args: IEngine.NavigateArgs): void;
+      currentEntry: HistoryEntry;
+      actionDataStore: Map<HistoryEntryId, Map<ActionFunction, NinjaPromise<unknown>>>;
+      loaderDataStore: Map<HistoryEntryId, Map<LoaderFunction, NinjaPromise<unknown>>>;
+    },
+  );
+
+  // エンジン、ストア、イベント購読メカニズムのセットアップを一元化し、useMemo でインスタンス化します。
   const router = React.useMemo<{
-    start(): () => void;
-    context: RouterContextValue;
-    getRoutes(): readonly MatchedRoute[] | undefined;
-  }>(
-    () => {
-      const actionDataStore: IDataStore<IAction> = new Map();
-      const loaderDataStore: IDataStore<ILoader> = new Map();
-      const subscribers = new Set<() => void>();
-      const routes = processRoutes(routesProp);
-      let ac: AbortController | null = null;
-
-      function getAbortSignal(): AbortSignal {
-        return (ac ||= new AbortController()).signal;
+    readonly start: () => () => void;
+    readonly context: RouterContextValue;
+    readonly getRoutes: () => readonly MatchedRoute[] | undefined;
+  }>(() => {
+    const actionDataStore = new Map<HistoryEntryId, Map<ActionFunction, NinjaPromise<unknown>>>();
+    const loaderDataStore = new Map<HistoryEntryId, Map<LoaderFunction, NinjaPromise<unknown>>>();
+    const subscribers = new Set<() => void>();
+    const routes = processRoutes(routesProp);
+    let ac: AbortController | null = null;
+
+    /**
+     * 現在のフェーズで有効な、シングルトン構造の中断シグナルをオンデマンドで生成・回収します。
+     */
+    function getAbortSignal(): AbortSignal {
+      return (ac ||= new AbortController()).signal;
+    }
+
+    // エンジンを初期化し、初期ロード時のマッチングルートおよび解決済みのデータマップを取得・登録します。
+    const initialState = engine.init({
+      routes,
+      getSignal: getAbortSignal,
+      loaderDataStore,
+    });
+    let currentRoutes = initialState?.routes;
+
+    /**
+     * エンジン内部での遷移確定時に、状態を React 側へ通知・マージするための状態更新関数です。
+     */
+    function updateRouter(newState?: RouterState | null) {
+      if (newState !== undefined) {
+        currentRoutes = newState?.routes;
       }
-
-      const initialState = engine.init({
-        routes,
-        getSignal: getAbortSignal,
-        loaderDataStore,
-      });
-      let currentRoutes = initialState?.routes;
-
-      function updateRouter(newState?: RouterState | null) {
-        if (newState !== undefined) {
-          currentRoutes = newState?.routes;
-        }
-        if (newState) {
-          routerRef.current.currentEntry = newState.entry;
-        }
-
-        // 登録されているすべてのサブスクライバーに通知します。
-        subscribers.forEach(notify => notify());
+      if (newState) {
+        routerRef.current.currentEntry = newState.entry;
       }
 
-      function startRouterEngine() {
-        const stop = engine.start({
-          routes,
-          update: updateRouter,
-          getSignal: getAbortSignal,
-          actionDataStore,
-          loaderDataStore,
-        });
-
-        return function stopRouterEngine() {
-          try {
-            // エンジンの動作を停止します。
-            stop?.();
-          } finally {
-            // 進行中のすべての非同期処理を中断します。
-            try {
-              ac?.abort();
-            } catch {
-            }
-
-            // 中断後は次回の呼び出しに備えてコントローラーを破棄します。
-            ac = null;
-          }
-        };
-      }
+      // 状態変更の発生を、React の useSyncExternalStore などのすべての購読者に一斉通知して再描画を促します。
+      subscribers.forEach((notify) => notify());
+    }
 
-      Object.assign<RouterRef["current"], RouterRef["current"]>(routerRef.current, {
-        submit(args) {
-          return engine.submit(args);
-        },
-        navigate(args) {
-          return engine.navigate(args);
-        },
-        currentEntry: initialState?.entry!,
+    /**
+     * エンジンによるイベントのリアルタイム監視を開始するトリガー関数です。
+     */
+    function startRouterEngine() {
+      const stop = engine.start({
+        routes,
+        update: updateRouter,
+        getSignal: getAbortSignal,
         actionDataStore,
         loaderDataStore,
       });
 
-      return {
-        start: startRouterEngine,
-        context: {
-          routerRef,
-          subscribe(cb) {
-            subscribers.add(cb);
-            return () => {
-              subscribers.delete(cb);
-            };
-          },
-        },
-        getRoutes() {
-          return currentRoutes;
-        },
+      return function stopRouterEngine() {
+        try {
+          if (typeof stop === "function") {
+            stop();
+          }
+        } finally {
+          try {
+            ac?.abort();
+          } catch {}
+          ac = null;
+        }
       };
-    },
-    [
-      engine,
-      routesProp,
-    ],
-  );
+    }
+
+    // 作成した各種ストアや命令型メソッドの参照を、永続化 Ref オブジェクトへと安全にマージします。
+    Object.assign<RouterRef["current"], RouterRef["current"]>(routerRef.current, {
+      submit(args) {
+        return engine.submit(args);
+      },
+      navigate(args) {
+        return engine.navigate(args);
+      },
+      currentEntry: initialState?.entry as HistoryEntry,
+      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]);
+  // コンポーネントのマウント時にルーターエンジンを始動させ、アンマウント時には自動的に破棄タスクを連動させます。
+  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/src/contexts/route-context.ts

@@ -1,20 +1,21 @@
 import * as React from "react";
+
 import type { MatchedRoute } from "../core/match-routes.js";
 
 /**
- * 各ルートのコンテキストで共有される値の型定義です。
+ * 現在のコンポーネント階層に紐づいている個別ルートのコンテキスト形状定義です。
  */
-export type RouteContextValue = Pick<MatchedRoute, "path" | "index" | "params" | "urlPath"> & {
+export type RouteContextValue = MatchedRoute & {
   /**
-   * 子ルートを描画するための React 要素です。
+   * 現在のルートの下位に位置する子ルートを表示するための React 要素です。
    *
-   * 子ルートが存在しない場合は `null` となります。
+   * これ以上下位にマッチする子ルートが存在しない場合は `null` になります。
    */
   readonly outlet: React.ReactElement | null;
 };
 
 /**
- * 個別のルート情報やアウトレット（子ルートの挿入場所）を保持するための React コンテキストです。
+ * 階層的にネストされたルーターのレイアウト構造において、親ルートから子ルートへそれぞれの階層固有のルート情報伝播させるための React コンテキストです。
  */
 const RouteContext = /*#__PURE__*/ React.createContext<RouteContextValue | null>(null);
 

package/src/contexts/router-context.ts

@@ -1,54 +1,71 @@
+import type { NinjaPromise } from "ninja-promise";
 import * as React from "react";
-import type { IReadonlyDataStore } from "../core/data-store.types.js";
+
 import type { HistoryEntry } from "../core/expect-history-entry.js";
-import type { IAction, ILoader } from "../core/route.types.js";
-import type { NavigateArgs, SubmitArgs } from "../engines/engine.types.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<{
     /**
-     * フォームデータやクエリーパラメーターを送信します。
-     *
-     * @param args 送信内容と送信先を含む引数です。
+     * フォームデータやクエリーパラメーターをルーターに送信するための関数です。
      */
-    readonly submit: (args: SubmitArgs) => void;
+    readonly submit: (args: IEngine.SubmitArgs) => void;
 
     /**
-     * 指定されたパスへ遷移します。
-     *
-     * @param args 遷移先と遷移オプションを含む引数です。
+     * URL 遷移や履歴スタックの相対移動をルーターに命令するための関数です。
      */
-    readonly navigate: (args: NavigateArgs) => void;
+    readonly navigate: (args: IEngine.NavigateArgs) => void;
 
     /**
-     * 現在の履歴エントリー情報（ID、URL、インデックスなど）です。
+     * 現在ブラウザー上でアクティブになっている履歴エントリーの情報です。
      */
     readonly currentEntry: HistoryEntry;
 
     /**
-     * 履歴 ID ごとに管理されているアクションデータのマップです。
+     * 履歴エントリーの ID ごとにアクションの実行状態を管理するデータストアです。
      */
-    readonly actionDataStore: IReadonlyDataStore<IAction>;
+    readonly actionDataStore: ReadonlyMap<
+      HistoryEntryId,
+      ReadonlyMap<ActionFunction, NinjaPromise<unknown>>
+    >;
 
     /**
-     * 履歴 ID ごとに管理されているローダーデータのマップです。
+     * 履歴エントリーの ID ごとにローダーの実行状態を管理するデータストアです。
      */
-    readonly loaderDataStore: IReadonlyDataStore<ILoader>;
+    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 コンテキストです。
+ * アプリケーションの最上位からルーターのグローバル状態を子コンポーネントへ一元的に伝播させるための React コンテキストです。
  *
- * 初期値は `null` であり、通常は Provider を介して値が提供されます。
+ * パフォーマンス最適化のためにプロバイダー自体は基本的に更新されず、子コンポーネントは `subscribe` と `useSyncExternalStore`を使って必要な部分データだけを購読します。
  */
 const RouterContext = /*#__PURE__*/ React.createContext<RouterContextValue | null>(null);
 

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

@@ -1,60 +1,74 @@
 /**
  * セグメントの種類に応じたスコア定数です。
  *
- * 数値が大きいほど優先順位（具体性）が高いです。
+ * 数値が大きいほど優先順位（詳細度）が高いです。
+ *
+ * 詳細度（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 = {
-  /**
-   * 静的なパスセグメントのスコアです。
-   */
-  STATIC: 4,
-
-  /**
-   * 必須のパラメーターセグメントのスコアです。
-   */
-  PARAMETER: 3,
-
-  /**
-   * 任意のパラメーターセグメントのスコアです。
-   */
-  OPTIONAL_PARAM: 2,
-
-  /**
-   * ワイルドカードセグメントのスコアです。
-   */
-  WILDCARD: 1,
+  PARAM: 4,
+  STATIC: 6,
+  WILDCARD: 2,
+  OPTIONAL_PARAM: 3,
+  OPTIONAL_WILDCARD: 1,
+  PARAM_WITH_SUFFIX: 5,
 } as const;
 
 /**
- * 指定されたパスセグメントの文字列から、その種類に応じたスコアを計算します。
+ * 与えられた単一のセグメント文字列を解析し、その特性に応じた詳細度スコアを算出します。
  *
- * @param s 解析対象のパスセグメント文字列です。
- * @returns セグメントの種類に基づいた数値スコアを返します。
+ * @param s 解析対象となるセグメント文字列です。
+ * @returns セグメントの種別に対応する、`SCORE` 定数から抽出された数値スコアです。
  */
 function getSegmentScore(s: string): number {
-  if (s.includes("*")) {
+  if (s === "*?") {
+    return SCORE.OPTIONAL_WILDCARD;
+  }
+
+  if (s === "*") {
     return SCORE.WILDCARD;
   }
 
-  if (s.startsWith(":")) {
-    if (s.endsWith("?")) {
+  if (s[0] === ":") {
+    if (s[s.length - 1] === "?") {
       return SCORE.OPTIONAL_PARAM;
-    } else {
-      return SCORE.PARAMETER;
     }
+
+    if (s.indexOf(".") < 0) {
+      return SCORE.PARAM;
+    }
+
+    return SCORE.PARAM_WITH_SUFFIX;
   }
 
   return SCORE.STATIC;
 }
 
 /**
- * 2 つのパスを比較し、ルーティングの優先順位に基づいたソート順を決定します。
+ * 英語のロケール設定に基づき、大文字小文字などを標準化した文字列比較を行うための `Intl.Collator` インスタンスです。
+ *
+ * 決定論的な辞書順ソートを保証するために使用します。
+ */
+const enCollator = new Intl.Collator("en");
+
+/**
+ * 2つのルートパスの優先順位を比較し、ソート順を決定するための比較関数です。
  *
- * より具体的で深いパスが前方に配置されるように比較を行います。
+ * より具体的で制限の厳しいパス（詳細度スコアが高いパス）が、ソート結果においてより前方に配置されるように負の値を返します。
  *
- * @param pathA 比較対象のパス A です。
- * @param pathB 比較対象のパス B です。
- * @returns 比較結果を示す数値です（負数は pathA が優先、正数は pathB が優先）。
+ * @param pathA 比較対象となる1つ目のパス文字列です。
+ * @param pathB 比較対象となる2つ目のパス文字列です。
+ * @returns `pathA` を優先する場合は負の数、`pathB` を優先する場合は正の数、等価である場合は `0` を返します。
  */
 export default function compareRoutePaths(pathA: string, pathB: string): number {
   const partsA = pathA.split("/").filter(Boolean);
@@ -82,7 +96,7 @@ export default function compareRoutePaths(pathA: string, pathB: string): number
     }
     // スコアが同じ場合は、文字列の辞書順で比較します。
     if (a !== b) {
-      return a.localeCompare(b);
+      return enCollator.compare(a, b);
     }
   }