soseki 0.0.4 → 0.0.6

package/src/engines/engine.types.ts

@@ -1,216 +1,254 @@
-import type { IDataStore } from "../core/data-store.types.js";
+import type { NinjaPromise } from "ninja-promise";
+
 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 { ReadonlyFormData } from "../core/readonly-form-data.types.js";
 import type { ReadonlyURLSearchParams } from "../core/readonly-url.types.js";
-import type { IAction, ILoader, Route } from "../core/route.types.js";
+import type { Route, ActionFunction, LoaderFunction } from "../core/route.types.js";
 
 /**
- * ルーターの初期状態を生成する際に必要な引数の型定義です。
- */
-export type InitEngineArgs = {
-  /**
-   * 前処理済みのルート定義の配列です。
-   */
-  readonly routes: readonly Route[];
-
-  /**
-   * 現在の非同期処理を中断するためのシグナルを取得する関数です。
-   */
-  readonly getSignal: () => AbortSignal;
-
-  /**
-   * ロケーション ID ごとに管理されているローダーデータのマップです。
-   */
-  readonly loaderDataStore: IDataStore<ILoader>;
-};
-
-/**
- * ルーターの現在の状態を表す型定義です。
+ * ルーターが管理する現在の画面の状態を表す型定義です。
  */
 export type RouterState = {
   /**
-   * 現在のロケーションエントリー情報です。
+   * 現在のアクティブな履歴エントリーです。
    */
-  readonly entry: HistoryEntry;
+  entry: HistoryEntry;
 
   /**
-   * 現在の URL にマッチしたルートの階層構造です。
-   *
-   * 最低でも 1 つのマッチしたルートが含まれるタプル形式となります。
+   * 現在の URL にマッチしている子から親までの階層的なルートの配列です。
    */
-  readonly routes: readonly [MatchedRoute, ...MatchedRoute[]];
+  routes: readonly [MatchedRoute, ...MatchedRoute[]];
 };
 
 /**
- * ルーターの状態を更新するための関数インターフェースです。
- */
-export interface IUpdateRouter {
-  /**
-   * システムの状態を更新します。
-   */
-  (): void;
-
-  /**
-   * 新しいルーターの状態を受け取り、システムの状態を更新します。
-   *
-   * @param state 新しいルーターの状態オブジェクトです。
-   */
-  (state: RouterState | null): void;
-}
-
-/**
- * ルーターエンジンを開始する際に必要な引数の型定義です。
- */
-export type StartEngineArgs = {
-  /**
-   * 前処理済みのルート定義の配列です。
-   */
-  readonly routes: readonly Route[];
-
-  /**
-   * 状態を更新するためのセッター関数です。
-   */
-  readonly update: IUpdateRouter;
-
-  /**
-   * 現在の非同期処理を中断するためのシグナルを取得する関数です。
-   */
-  readonly getSignal: () => AbortSignal;
-
-  /**
-   * ロケーション ID ごとに管理されているアクションデータのマップです。
-   */
-  readonly actionDataStore: IDataStore<IAction>;
-
-  /**
-   * ロケーション ID ごとに管理されているローダーデータのマップです。
-   */
-  readonly loaderDataStore: IDataStore<ILoader>;
-};
-
-/**
- * エンジンの動作を停止するための関数インターフェースです。
+ * 実行中のルーティングエンジンを安全に停止させ、各種イベントリスナーや非同期処理をクリーンアップするための関数インターフェースです。
  */
 export interface IStopEngine {
-  /**
-   * 実行中のエンジンを停止し、イベントリスナーの解除などのクリーンアップを行います。
-   */
   (): void;
 }
 
 /**
- * 送信処理に渡される引数の型定義です。
+ * ルーティングエンジンに関わる各種引数や戻り値の型をまとめた名前空間です。
  */
-export type SubmitArgs = {
+export namespace IEngine {
   /**
-   * 送信対象となるフォームデータです。
+   * ルーター初期化メソッド `init` に渡される引数の型定義です。
    */
-  readonly target: ReadonlyFormData;
+  export type InitArgs = {
+    /**
+     * アプリケーションに登録されているすべての正規化済みルートの定義配列です。
+     */
+    routes: readonly Route[];
 
-  /**
-   * 送信先のパスです。
-   */
-  readonly action: string;
+    /**
+     * 各履歴エントリーに紐づくローダーの非同期状態を多重管理する、共有データストアへの参照です。
+     */
+    loaderDataStore: Map<HistoryEntryId, Map<LoaderFunction, NinjaPromise<unknown>>>;
 
-  /**
-   * 実行するアクションの定義です。
-   */
-  readonly actionId: IAction | undefined;
-} | {
-  /**
-   * 送信対象となる URL クエリーパラメーターです。
-   */
-  readonly target: ReadonlyURLSearchParams;
+    /**
+     * 中断シグナルを取得します。
+     */
+    getSignal: () => AbortSignal;
+  };
 
   /**
-   * 送信先のパスです。
-   */
-  readonly action: string;
-
-  /**
-   * 履歴の追加方法を指定します。
+   * ルーター初期化メソッド `init` が返す初期状態の型定義です。
    *
-   * "replace" は現在のエントリーを置き換え、"push" は新しいエントリーを追加します。
-   */
-  readonly history: "replace" | "push";
-};
-
-/**
- * ナビゲーションの移動先を示す型定義です。
- *
- * パス文字列または詳細なパス情報のオブジェクトを受け取ります。
- */
-export type NavigateTo = string | {
-  /**
-   * URL のパス名を表します。
-   */
-  readonly pathname?: string | undefined;
-
-  /**
-   * URL のクエリーパラメーターを表します。
+   * マッチするルートがあればその状態を返し、なければ `null` となります。
    */
-  readonly search?: string | undefined;
+  export type InitReturn = RouterState | null;
 
   /**
-   * URL のハッシュフラグメントを表します。
-   */
-  readonly hash?: string | undefined;
-};
-
-/**
- * エンジンの遷移関数に渡される引数の型定義です。
- */
-export type NavigateArgs = {
-  /**
-   * 遷移先です。
-   */
-  readonly to: NavigateTo;
-
-  /**
-   * 履歴の追加方法を指定します。
+   * エンジンの稼働開始メソッド `start` に渡される引数の型定義です。
    *
-   * "replace" は現在のエントリーを置き換え、"push" は新しいエントリーを追加します。
-   */
-  readonly history: "replace" | "push";
-} | {
-  /**
-   * 履歴スタックの相対位置です。
-   */
-  readonly delta: number;
-};
+   * ナビゲーションイベントの監視や状態同期に必要な依存関係を集約します。
+   */
+  export type StartArgs = {
+    /**
+     * アプリケーションに登録されているすべての正規化済みルートの定義配列です。
+     */
+    routes: readonly Route[];
+
+    /**
+     * 各履歴エントリーに紐づくアクションの非同期状態を保持する共有データストアです。
+     */
+    actionDataStore: Map<HistoryEntryId, Map<ActionFunction, NinjaPromise<unknown>>>;
+
+    /**
+     * 各履歴エントリーに紐づくローダーの非同期状態を保持する共有データストアです。
+     */
+    loaderDataStore: Map<HistoryEntryId, Map<LoaderFunction, NinjaPromise<unknown>>>;
+
+    /**
+     * エンジン内部で遷移が確定した際、新しい状態を Reactに通知して画面の再描画を要求するための更新関数です。
+     *
+     * 引数なしの呼び出しは、現在の状態を維持したままの強制再レンダリングを意味します。
+     */
+    update: {
+      /**
+       * 現在の状態を維持したまま強制的に再レンダリングします。
+       */
+      (): void;
+
+      /**
+       * ルーターの状態を更新します。
+       *
+       * @param newRouterState 新しいルーターの状態です。
+       */
+      (newRouterState: RouterState | null): void;
+    };
+
+    /**
+     * 中断シグナルを取得します。
+     */
+    getSignal: () => AbortSignal;
+  };
+
+  /**
+   * エンジンの稼働開始メソッド `start` の戻り値です。
+   *
+   * 監視イベントのリスナーを解除するためのクリーンアップ関数を返すか、環境によって何も返さない場合があります。
+   */
+  export type StartReturn = IStopEngine | void;
+
+  /**
+   * プログラムからのフォーム送信やクエリー更新を行う `submit` メソッドの引数の型定義です。
+   */
+  export type SubmitArgs =
+    | {
+        /**
+         * HTTP POST メソッドに相当する、マルチパートまたは URL エンコードされたフォームデータの送信です。
+         */
+        type: "FORM_DATA";
+
+        /**
+         * 送信する不変のフォームデータ本体です。
+         */
+        target: ReadonlyFormData;
+
+        /**
+         * アクションの送信先となる対象の URL パス文字列です。
+         */
+        action: string;
+      }
+    | {
+        /**
+         * HTTP GET メソッドに相当する、URL の検索クエリーの更新送信です。
+         */
+        type: "URL_SEARCH_PARAMS";
+
+        /**
+         * 更新対象となる検索クエリーパラメータです。
+         */
+        target: ReadonlyURLSearchParams;
+
+        /**
+         * クエリーの付与先となる対象の URL パス文字列です。
+         */
+        action: string;
+
+        /**
+         * 履歴スタックへの追加方法を指定します。
+         *
+         * - `"push"`: 履歴エントリーの新規追加
+         * - `"replace"`: 履歴エントリーの上書き
+         */
+        history: "replace" | "push";
+      };
+
+  /**
+   * 命令的な画面遷移を行う `navigate` メソッドの引数の型定義です。
+   *
+   * リンクをクリックした際のアドレス遷移か、ブラウザーの「戻る・進む」に相当する相対移動かで分岐します。
+   */
+  export type NavigateArgs =
+    | {
+        /**
+         * 明示的なアドレス指定による前方移動です。
+         */
+        type: "LINK";
+
+        /**
+         * 遷移先のアドレス表現の指定です。完全なパス文字列か、部分的なパーツの組み合わせかを選択します。
+         */
+        to:
+          | {
+              /**
+               * URL パスで前方移動する形式です。
+               */
+              type: "PATH";
+
+              /**
+               * URL パスです。
+               */
+              path: string;
+            }
+          | {
+              /**
+               * URL の各コンポーネントを個別に指定する形式です。
+               */
+              type: "PARTIAL";
+
+              /**
+               * 最初のスラッシュ `/` から始まる URL のパス部分です。
+               */
+              pathname?: string | undefined;
+
+              /**
+               * 先頭のクエスチョンマーク `?` を含む URL のクエリー文字列です。
+               */
+              search?: string | undefined;
+
+              /**
+               * URL のハッシュ（シャープ記号 `#` を含むフラグメント識別子）です。
+               */
+              hash?: string | undefined;
+            };
+
+        /**
+         * 履歴スタックへの追加方法を指定します。
+         *
+         * - `"push"`: 履歴エントリーの新規追加
+         * - `"replace"`: 履歴エントリーの上書き
+         */
+        history: "replace" | "push";
+      }
+    | {
+        /**
+         * 履歴スタック内の相対的な位置移動（例: `-1` で1つ戻る、`2` で2つ進む）です。
+         */
+        type: "MOVE";
+
+        /**
+         * 履歴を移動させる差分ステップ数です。
+         */
+        delta: number;
+      };
+}
 
 /**
- * ルーティングの基幹処理を担うエンジンのインターフェースです。
+ * ルーティングエンジンのインターフェース定義です。
  */
 export interface IEngine {
   /**
-   * 与えられた引数に基づいて、ルーターを初期化します。
-   *
-   * @param args 状態生成に必要なルート情報やデータマップです。
-   * @returns 生成されたルーター状態、またはマッチしなかった場合は `null` を返します。
+   * 現在の URL を基にルーターの初期状態を計算し、同期的に取得します。
    */
-  init(args: InitEngineArgs): RouterState | null;
+  init(args: IEngine.InitArgs): IEngine.InitReturn;
 
   /**
-   * エンジンの動作を開始します。履歴の変化の監視などを開始します。
-   *
-   * @param args エンジンの開始に必要な設定とコールバック関数です。
-   * @returns エンジンを停止するための関数を返します。停止処理が不要な場合は何も返しません。
+   * エンジンを稼働させ、ブラウザーの履歴変更やナビゲーションイベントの継続的な監視を開始します。
    */
-  start(args: StartEngineArgs): IStopEngine | void;
+  start(args: IEngine.StartArgs): IEngine.StartReturn;
 
   /**
-   * フォームデータやクエリーパラメーターを送信します。
-   *
-   * @param args 送信内容と送信先を含む引数です。
+   * ユーザーからの意図的なフォームデータまたはクエリーパラメータの送信を検知し、対応するルートのアクションやローダーを起動します。
    */
-  submit(args: SubmitArgs): void;
+  submit(args: IEngine.SubmitArgs): void;
 
   /**
-   * 指定されたパスへ遷移します。
-   *
-   * @param args 遷移先と遷移オプションを含む引数です。
+   * プログラムからの命令的なページ遷移を処理します。
    */
-  navigate(args: NavigateArgs): void;
+  navigate(args: IEngine.NavigateArgs): void;
 }