soseki 0.0.5 → 0.0.7

package/src/core/start-action.ts

@@ -0,0 +1,164 @@
+import { NinjaPromise } from "ninja-promise";
+
+import unreachable from "./_unreachable.js";
+import type { HistoryEntryUrl } from "./history-entry-url-schema.js";
+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";
+
+/**
+ * アクション処理の実行開始時に必要となる、起点リクエスト情報の型定義です。
+ */
+export type ActionStartRequest = {
+  /**
+   * アクションの送信先（トリガーされた現在）の正規化済み URL オブジェクトです。
+   */
+  readonly url: HistoryEntryUrl;
+
+  /**
+   * クライアントから送信された、書き換え用の不変なフォームデータです。
+   */
+  readonly formData: ReadonlyFormData;
+
+  /**
+   * 実行中の非同期アクションを外部から中断するための中断シグナルです。
+   */
+  readonly signal: AbortSignal;
+};
+
+/**
+ * 起動されたアクションの実行コンテキストおよび非同期状態を追跡・制御するためのインターフェースです。
+ */
+export interface StartedAction {
+  /**
+   * アクションの実行結果、または現在進行中の非同期状態を表す `NinjaPromise` です。
+   */
+  data: NinjaPromise<unknown>;
+
+  /**
+   * 実際に実行対象として選出されたアクション関数の参照です。
+   */
+  func: ActionFunction;
+
+  /**
+   * アクションの非同期処理が完了してアイドル状態に移行するのを待機し、処理結果に伴うリダイレクト要求の有無を回収します。
+   *
+   * @returns 処理結果に伴うリダイレクト要求を含むオブジェクトです。
+   */
+  idle: () => Promise<{
+    redirectTo: RedirectResponse | undefined;
+  }>;
+}
+
+/**
+ * マッチしたルート配列から、アクションの送信先に近い親ルートのアクション関数を 1 つだけ選出して実行し、リダイレクトの傍受や応答データの型正規化などを行う、POST 処理の開始関数です。
+ *
+ * @param routes 現在の URL にマッチしたルート情報の配列です。
+ * @param request アクションを起動するための URL、フォームデータ、および中断シグナルを含むオブジェクトです。
+ * @returns 実行対象のアクション関数が検出された場合は `StartedAction` オブジェクトを返し、1つも定義されていなかった場合は `null` を返します。
+ */
+export default function startAction(
+  routes: readonly Pick<MatchedRoute, "params" | "action" | "urlPath">[],
+  request: ActionStartRequest,
+): StartedAction | null {
+  let action: ActionFunction | undefined;
+  let params: RoutePathParams;
+  let urlPath: string;
+
+  for ({ action, params, urlPath } of routes) {
+    if (
+      // アクションを実行するために、関数が定義されている必要があります。
+      typeof action === "function" &&
+      // アクションの送信先に近い親ルートを選出します。
+      request.url.pathname.startsWith(urlPath)
+    ) {
+      break;
+    }
+  }
+
+  if (typeof action !== "function") {
+    return null;
+  }
+
+  let actionData: NinjaPromise<unknown> | undefined;
+  let redirectTo: RedirectResponse | undefined;
+
+  const actionReturn = NinjaPromise.try(function executeAction() {
+    return action({
+      params,
+      request: RouteRequest.new("POST", request.url, request.signal, request.formData),
+    });
+  });
+
+  switch (actionReturn.status) {
+    case "pending": {
+      // アクションの戻り値が非同期（Promise）である場合、中継用のプロミスを作成して状態変化をコントロールします。
+      const proxy = NinjaPromise.withResolvers();
+      actionData = proxy.promise;
+
+      // 非同期の完了を追跡します。
+      void (async () => {
+        const value = await actionReturn;
+        switch (true) {
+          // アクションの非同期結果がリダイレクト応答（RedirectResponse）であった場合、
+          // 内部状態にリダイレクト先を記録し、画面側のコンポーネントが参照するデータとしては undefined を返してデータ露出を抑制します。
+          case value instanceof RedirectResponse:
+            redirectTo = value;
+            return undefined;
+
+          default:
+            return value;
+        }
+      })()
+        .then((value) => proxy.resolve(value))
+        .catch((reason) => proxy.reject(reason)); // 例外が発生した場合はそのまま下流へ伝播させます。
+
+      break;
+    }
+
+    case "rejected":
+      // 同期的な実行の段階で既に例外が発生している場合は、特別な加工をせずそのままエラー状態を引き継ぎます。
+      // エラーハンドリングの責務は、このアクションデータを参照・購読するコンポーネント側に一任されます。
+      actionData = actionReturn;
+
+      break;
+
+    case "fulfilled": {
+      // 同期的に実行が完了し、すでに値が確定している場合の処理です。
+      const { value } = actionReturn;
+      switch (true) {
+        case value instanceof RedirectResponse:
+          // 返り値がリダイレクト指示である場合は、リダイレクト先を記録し、データを undefined に置き換えた解決済みのプロミスを作成します。
+          redirectTo = value;
+          actionData = NinjaPromise.resolve(undefined);
+          break;
+
+        default:
+          // 通常のデータであれば、そのままの完了状態をアクションデータとして引き継ぎます。
+          actionData = actionReturn;
+      }
+
+      break;
+    }
+
+    default:
+      unreachable(actionReturn);
+  }
+
+  return {
+    data: actionData,
+    func: action,
+    async idle() {
+      try {
+        // アクションデータのエラーハンドリングはコンポーネント側に一任されます。
+        await actionData;
+      } catch {}
+
+      return {
+        redirectTo,
+      };
+    },
+  };
+}

package/src/core/start-loaders.ts

@@ -1,254 +1,232 @@
+import { NinjaPromise } from "ninja-promise";
+
 import unreachable from "./_unreachable.js";
-import type { IDataMap, IReadonlyDataMap } from "./data-map.types.js";
-import type { IDataStore } from "./data-store.types.js";
-import DeferredPromise from "./deferred-promise.js";
 import { LoaderConditionError } from "./errors.js";
 import type { HistoryEntry } from "./expect-history-entry.js";
+import type { HistoryEntryId } from "./history-entry-id-schema.js";
 import type { MatchedRoute } from "./match-routes.js";
 import RouteRequest from "./route-request.js";
-import type { IAction, ILoader, ShouldReloadArgs } from "./route.types.js";
+import type { LoaderFunction } from "./route.types.js";
 
 /**
- * `startLoaders` 関数に渡すパラメーターの型定義です。
+ * `startLoaders` 関数を実行する際に必要となる引数オブジェクトの型定義です。
  */
-export type StartLoadersParams =
-  & {
-    /**
-     * 直前のルート情報の配列です。初回遷移時は `null` になります。
-     */
-    readonly prevRoutes: readonly Pick<MatchedRoute, "path" | "params">[] | null;
-
-    /**
-     * 現在の遷移先ルート情報の配列です。
-     */
-    readonly currentRoutes: readonly Pick<MatchedRoute, "path" | "params" | "dataFuncs">[];
-
-    /**
-     * 直前の履歴エントリー情報です。
-     */
-    readonly prevEntry: Pick<HistoryEntry, "id" | "url">;
-
-    /**
-     * 現在の履歴エントリー情報です。
-     */
-    readonly currentEntry: Pick<HistoryEntry, "id" | "url">;
-
-    /**
-     * アクションの実行結果を保持するデータストアーです。
-     */
-    readonly actionDataStore: IDataStore<IAction>;
-
-    /**
-     * ローダーの実行結果を保持するデータストアーです。
-     */
-    readonly loaderDataStore: IDataStore<ILoader>;
-
-    /**
-     * 非同期処理を中断するためのシグナルです。
-     */
-    readonly signal: AbortSignal;
-  }
-  & ({
-    /**
-     * 送信されたフォームデータです。
-     */
-    readonly formData: FormData;
-
-    /**
-     * アクションの実行結果を格納したマップです。
-     */
-    readonly actionResultMap: IReadonlyDataMap<IAction, unknown>;
-  } | {
-    /**
-     * フォームデータが存在しないことを示します。
-     */
-    readonly formData?: undefined;
-
-    /**
-     * アクション結果マップが存在しないことを示します。
-     */
-    readonly actionResultMap?: undefined;
-  });
+export type StartLoadersArgs = {
+  /**
+   * 遷移前にマッチしていたルート情報の配列です。
+   */
+  readonly prevRoutes: readonly Pick<MatchedRoute, "path" | "params">[] | null;
+
+  /**
+   * 遷移先の URL にマッチしている全ルート情報の配列です。
+   */
+  readonly currentRoutes: readonly Pick<
+    MatchedRoute,
+    "path" | "params" | "action" | "loader" | "shouldReload"
+  >[];
+
+  /**
+   * 遷移前の履歴エントリー情報です。
+   */
+  readonly prevEntry: Pick<HistoryEntry, "id" | "url">;
+
+  /**
+   * 遷移先（現在）の履歴エントリー情報です。
+   */
+  readonly currentEntry: Pick<HistoryEntry, "id" | "url">;
+
+  /**
+   * 履歴エントリー ID ごとに、各ローダーの実行結果を多重管理しているグローバルなデータストアです。
+   */
+  readonly loaderDataStore: Map<HistoryEntryId, Map<LoaderFunction, NinjaPromise<unknown>>>;
+
+  /** 進行中のローダーの非同期処理を外部から中断するためのシグナルオブジェクトです。 */
+  readonly signal: AbortSignal;
+};
 
 /**
- * ルートに紐付くローダーの実行を開始し、データの同期や再読み込みの判定を行います。
- *
- * @param params ローダーの開始に必要なパラメーターオブジェクトです。
- * @returns すべてのローダーの完了を待機する非同期関数を返します。ローダーが不要な場合は `undefined` を返します。
+ * 直前にアクションが実行されていた場合に、追加の文脈として渡されるオプションオブジェクトの型定義です。
  */
-export default function startLoaders(params: StartLoadersParams): undefined | {
+export type StartLoadersOptions = {
+  /**
+   * アクション実行時に送信された標準のフォームデータです。
+   */
+  readonly formData: FormData;
+
   /**
-   * 実行中のすべてのローダーが完了するまで待機します。
+   * 直前のアクション関数が返した実行結果データです。
    */
-  (): Promise<void>;
-} {
-  const {
-    signal,
-    prevEntry,
-    prevRoutes,
-    currentEntry,
-    currentRoutes,
-    actionDataStore,
-    loaderDataStore,
-    ...options
-  } = params;
-  // ローダーの実行前にアクションが実行された場合、その情報を使ってローダーの処理を分岐させます。
-  const actionContext = options.formData && {
+  readonly actionData: unknown;
+};
+
+/**
+ * 起動されたローダー群のライフサイクルおよび完了待機を制御するインターフェースです。
+ */
+export interface StartedLoaders {
+  /**
+   * 現在のフェーズでスケジュールされたすべてのローダーの処理が完了するまで待機します。
+   */
+  idle: () => Promise<void>;
+}
+
+/**
+ * 画面遷移やデータ更新の発生に伴い、現在マッチしているルートのローダー関数群を精査し、キャッシュの再利用または読み込みを動的に判定・実行する関数です。
+ *
+ * @param args ローダーの評価に必要な現旧のルートおよび履歴コンテキストです。
+ * @param options 直前のアクション実行コンテキストを含むオプションです。
+ * @returns スケジュールされたローダー全体の処理完了を待機するための `StartedLoaders` オブジェクトを返します。
+ */
+export default function startLoaders(
+  args: StartLoadersArgs,
+  options?: StartLoadersOptions,
+): StartedLoaders {
+  const { signal, prevEntry, prevRoutes, currentEntry, currentRoutes, loaderDataStore } = args;
+
+  // アクション契機でのデータリロードであるか、通常の GET 遷移であるかを識別するためのコンテキストを構築します。
+  const actionContext = options && {
     formData: options.formData,
-    resultMap: options.actionResultMap,
+    actionData: options.actionData,
   };
-  // prevRoutes は「子ルート」->「親ルート」の順で並んでいるので、最初の要素がすべてのルートのパラメーターを保持しています。
+
+  // マッチした配列は「子ルート（詳細度高）」から「親ルート（詳細度低）」の順にソートされているため、先頭の要素から、ルート全体の動的パスパラメーターを一括して回収できます。
   const prevParams = prevRoutes?.[0]?.params || {};
-  const prevRoutePathSet: ReadonlySet<string> = new Set(prevRoutes?.map(r => r.path));
-  const prevActionDataMap: IReadonlyDataMap<IAction> | undefined = actionDataStore
-    .get(prevEntry.id);
-  const prevLoaderDataMap: IReadonlyDataMap<ILoader> | undefined = loaderDataStore
-    .get(prevEntry.id);
-  const currentActionDataIncMap: IDataMap<IAction> = new Map();
-  const currentLoaderDataIncMap: IDataMap<ILoader> = new Map();
-  const request = new RouteRequest("GET", currentEntry.url, signal);
-
-  // 各ルートおよびルートに定義されたデータ関数（action/loader）を走査します。
+  const prevRoutePathSet: ReadonlySet<string> = new Set(prevRoutes?.map((r) => r.path));
+
+  // 遷移前の履歴 ID に紐づくローダーデータのキャッシュマップをストアから取得します。
+  const prevLoaderDataMap: ReadonlyMap<LoaderFunction, NinjaPromise<unknown>> | undefined =
+    loaderDataStore.get(prevEntry.id);
+
+  // 今回の実行フェーズで収集・確定させる新しいローダーデータマップを初期化します。
+  const currentLoaderDataMap = new Map<LoaderFunction, NinjaPromise<unknown>>();
+  const request = RouteRequest.new("GET", currentEntry.url, signal);
+
+  // 現在マッチしているすべてのルートセグメントを個別に精査します。
   for (const currentRoute of currentRoutes) {
-    for (const { action, loader, shouldReload } of currentRoute.dataFuncs) {
-      if (actionContext && action) {
-        const prevActionData = prevActionDataMap?.get(action);
-        if (prevActionData) {
-          // 遷移前のアクションデータを引き継ぐことで、アクションの結果に応じて変更された描画内容を表示させ続けることができます。
-          currentActionDataIncMap.set(action, prevActionData);
-        }
-      }
+    const { loader: currentLoader, params: currentParams, shouldReload } = currentRoute;
 
-      if (!loader) {
-        continue;
-      }
+    // ローダー関数が定義されていないルートセグメントはスキップします。
+    if (typeof currentLoader !== "function") {
+      continue;
+    }
 
-      const prevLoaderData = prevLoaderDataMap?.get(loader);
-      if (!prevLoaderData) {
-        // 遷移前のローダーデータがない場合、新規ルートの描画と判定して、強制ロードします。
-        // ローダーの実行を遅延評価としてラップします。
-        const data = DeferredPromise.try(function executeLoader() {
-          return loader({
-            params: currentRoute.params,
-            request,
-          });
+    // 過去に同じローダー関数が実行され、かつそのキャッシュデータが存在するかをチェックします。
+    const prevLoaderData = prevLoaderDataMap?.get(currentLoader);
+    if (!prevLoaderData) {
+      // 過去のキャッシュが存在しない＝今回新しくマッチした未知のルート階層であると判定し、判定の余地なく新規にローダーを起動します。
+      const data = NinjaPromise.try(function executeLoader() {
+        return currentLoader({
+          params: currentParams,
+          request,
         });
-        // ローダーの結果を待機、エラーハンドリングする処理は、この結果を参照するコンポーネントに任せます。
-        currentLoaderDataIncMap.set(loader, data);
-        continue;
-      }
+      });
+      // ローダーの結果を待機、エラーハンドリングする処理は、この結果を参照するコンポーネントに任せます。
+      currentLoaderDataMap.set(currentLoader, data);
 
-      // リロードすべきかどうかを判定します。
-      const should = DeferredPromise.try(function executeShouldReload() {
-        if (!actionContext) {
-          // 通常の GET 遷移時の再読み込み判定引数を構築します。
-          return shouldReload({
-            prevUrl: prevEntry.url,
-            currentUrl: currentEntry.url,
-            prevParams,
-            currentParams: currentRoute.params,
-            triggerMethod: "GET",
-            defaultShouldReload: !prevRoutePathSet.has(currentRoute.path),
-          });
-        }
+      continue;
+    }
 
-        // 特定のアクションが実行された後の再読み込み判定引数を構築します。
-        const {
-          formData,
-          resultMap,
-        } = actionContext;
-        let shouldArgs: ShouldReloadArgs = {
+    // キャッシュが存在する場合、ユーザー定義の `shouldReload` に照らし合わせて再読み込みが必要かを安全に検証します。
+    const should = NinjaPromise.try(function executeShouldReload() {
+      if (!actionContext) {
+        // 通常の GET 遷移時における再読み込み判定用引数を組み立てて実行します。
+        return shouldReload({
+          prevUrl: prevEntry.url,
+          currentUrl: currentEntry.url,
+          prevParams,
+          currentParams,
+          triggerMethod: "GET",
+          // 遷移前のルート群に今回精査しているパスが含まれていなければ、新規表示扱いとして、既定値を true とします。
+          defaultShouldReload: !prevRoutePathSet.has(currentRoute.path),
+        });
+      } else {
+        // フォームデータの送信を伴う更新契機の場合の判定引数です。
+        return shouldReload({
+          ...actionContext,
           prevUrl: prevEntry.url,
-          formData,
           currentUrl: prevEntry.url,
           prevParams,
-          currentParams: currentRoute.params,
+          currentParams,
           triggerMethod: "POST",
-          defaultShouldReload: resultMap.size > 0,
-        };
-        if (action && resultMap.has(action)) {
-          // アクションの結果があるときのみプロパティーを設定します。
-          shouldArgs.actionResult = resultMap.get(action);
-        }
+          // データ更新後は原則として全再取得が安全なため、既定値を true とします。
+          defaultShouldReload: true,
+        });
+      }
+    });
+
+    let data: NinjaPromise<unknown>;
+    // `shouldReload` の同期的な実行結果に基づいて処理を分岐します。
+    switch (should.status) {
+      case "pending": {
+        // shouldReload は仕様上「同期的」に真偽値を返す必要があります（Promise を返してはならない）。
+        // もし pending であれば LoaderConditionError を生成して拒否状態のプロミスとしてラップします。
+        const error = new LoaderConditionError({
+          url: request.url.href,
+          returnValue: should,
+          shouldReload,
+        });
+        data = NinjaPromise.reject(error);
+        break;
+      }
 
-        return shouldReload(shouldArgs);
-      });
+      case "rejected":
+        // shouldReload の実行中に同期的な例外が発生した場合は、そのエラー状態をそのまま引き継ぎ、ハンドリングを画面側に委ねます。
+        data = should;
+        break;
+
+      case "fulfilled": {
+        const { value } = should;
+        switch (value) {
+          case true:
+            // 明示的にリロードの指示が出た場合のみ、ローダーを新規に再実行します。
+            data = NinjaPromise.try(function executeLoader() {
+              return currentLoader({
+                params: currentParams,
+                request,
+              });
+            });
 
-      let data: DeferredPromise<unknown>;
-      switch (should.status) {
-        case "pending": {
-          // shouldReload は同期的に真偽値を返す必要があるので、pending 状態（つまり非同期）であってはいけません。
-          const error = new LoaderConditionError(request.url.href, shouldReload, should);
-          // エラーハンドリングは、このローダーデータを参照するコンポーネントに任せます。
-          data = DeferredPromise.reject(error);
-          break;
-        }
+            break;
 
-        case "rejected":
-          // エラーハンドリングは、このアクションデータを参照するコンポーネントに任せます。
-          data = should;
-          break;
-
-        case "fulfilled": {
-          const { value } = should;
-          switch (value) {
-            case true:
-              // 条件を満たす場合のみ、ローダーの実行をスケジュールします。
-              data = DeferredPromise.try(function executeLoader() {
-                return loader({
-                  params: currentRoute.params,
-                  request,
-                });
-              });
-              break;
-
-            case false:
-              // 再読み込みが不要な場合は、前回のデータを引き継ぎま
-              data = prevLoaderData;
-              break;
-
-            default: {
-              // shouldReload が真偽値を返さなかった場合、エラーとします。
-              const error = new LoaderConditionError(request.url.href, shouldReload, value);
-              // エラーハンドリングは、このローダーデータを参照するコンポーネントに任せます。
-              data = DeferredPromise.reject(error);
-            }
-          }
+          case false:
+            // 再読み込みが不要（現状維持）と判定された場合は、前回のキャッシュプロミスをそのまま無加工で引き継ぎます。
+            data = prevLoaderData;
+
+            break;
 
-          break;
+          default: {
+            // 戻り値が boolean 型（true / false）ではなかった場合、仕様不適合としてエラーを割り当てます。
+            const error = new LoaderConditionError({
+              url: request.url.href,
+              returnValue: value,
+              shouldReload,
+            });
+            // エラーハンドリングは、このローダーデータを参照するコンポーネントに任せます。
+            data = NinjaPromise.reject(error);
+          }
         }
 
-        default:
-          unreachable(should);
+        break;
       }
 
-      currentLoaderDataIncMap.set(loader, data);
+      default:
+        unreachable(should);
     }
-  }
 
-  // アクションデータの更新処理です。
-  if (actionContext) {
-    const dataMap = actionDataStore.get(currentEntry.id);
-    if (dataMap) {
-      for (const [action, data] of currentActionDataIncMap) {
-        dataMap.set(action, data);
-      }
-    } else {
-      actionDataStore.set(currentEntry.id, currentActionDataIncMap);
-    }
+    // 確定したプロミスを今回のマップに登録します。
+    currentLoaderDataMap.set(currentLoader, data);
   }
 
-  // ローダーデータの更新処理です。
-  const dataMap = loaderDataStore.get(currentEntry.id);
-  if (dataMap) {
-    for (const [loader, data] of currentLoaderDataIncMap) {
-      dataMap.set(loader, data);
-    }
-  } else {
-    loaderDataStore.set(currentEntry.id, currentLoaderDataIncMap);
+  // 今回の実行フェーズで収集・更新されたローダーデータが存在する場合、グローバルなキャッシュストアへマージして永続化します。
+  if (currentLoaderDataMap.size > 0) {
+    loaderDataStore.set(
+      currentEntry.id,
+      new Map([...(loaderDataStore.get(currentEntry.id) || []), ...currentLoaderDataMap]),
+    );
   }
 
-  return async function waitForLoadersComplete() {
-    await Promise.allSettled(currentLoaderDataIncMap.values());
+  return {
+    async idle() {
+      await Promise.allSettled(currentLoaderDataMap.values());
+    },
   };
 }

package/src/core.ts

@@ -1,5 +1,7 @@
-export { default as Router } from "./components/router.jsx";
 export type * from "./components/router.jsx";
+export { default as Router } from "./components/router.jsx";
+
+/**************************************************************************************************/
 
 export type * from "./contexts/route-context.js";
 export { default as RouteContext } from "./contexts/route-context.js";
@@ -7,11 +9,7 @@ export { default as RouteContext } from "./contexts/route-context.js";
 export type * from "./contexts/router-context.js";
 export { default as RouterContext } from "./contexts/router-context.js";
 
-export { ACTION_ID_FORM_DATA_NAME } from "./core/constants.js";
-
-export type * from "./core/data-map.types.js";
-
-export type * from "./core/data-store.types.js";
+/**************************************************************************************************/
 
 export type * from "./core/expect-history-entry.js";
 export { default as expectHistoryEntry } from "./core/expect-history-entry.js";
@@ -28,16 +26,11 @@ export { default as initLoaders } from "./core/init-loaders.js";
 export type * from "./core/match-routes.js";
 export { default as matchRoutes } from "./core/match-routes.js";
 
-export type * from "./core/redirect-response.js";
-export { default as RedirectResponse } from "./core/redirect-response.js";
+export type * from "./core/route-path.js";
+export { default as RoutePath } from "./core/route-path.js";
 
-export type * from "./core/start-actions.js";
-export { default as startActions } from "./core/start-actions.js";
+export type * from "./core/start-action.js";
+export { default as startAction } from "./core/start-action.js";
 
 export type * from "./core/start-loaders.js";
 export { default as startLoaders } from "./core/start-loaders.js";
-
-export type * from "./engines/engine.types.js";
-
-export type * from "./engines/navigation-api-engine.js";
-export { default as NavigationApiEngine } from "./engines/navigation-api-engine.js";