soseki 0.0.1

package/src/core/route.types.ts

@@ -0,0 +1,351 @@
+import type * as React from "react";
+import type { RouteParams } from "regexparam";
+import type { ReadonlyURL } from "./readonly-url.types.js";
+import type RouteRequest from "./route-request.js";
+
+/**
+ * パスパラメーターの内部的な型定義です。
+ *
+ * @template TParams `regexparam` から抽出されたパラメーターの型です。
+ */
+// dprint-ignore
+type PathParams_<TParams extends { [_ in string]?: string }> =
+    [keyof TParams] extends [never]
+  ? { readonly [_ in string]?: string }
+  : Readonly<TParams>
+
+/**
+ * 指定されたパス文字列からパラメーターを抽出するための型定義です。
+ *
+ * @template TPath 解析対象となるパス文字列の型です。
+ */
+export type PathParams<TPath extends string = string> = PathParams_<RouteParams<TPath>>;
+
+/**
+ * アクションを実行すべきかどうかを判定する関数（`shouldAction`）に渡される引数の型定義です。
+ *
+ * @template TPath パス文字列の型です。
+ */
+export type ShouldActionArgs<TPath extends string = string> = {
+  /**
+   * URL から抽出されたパスパラメーターのオブジェクトです。
+   */
+  params: PathParams<TPath>;
+
+  /**
+   * ルーティングに関するリクエスト情報です。
+   */
+  request: RouteRequest;
+
+  /**
+   * デフォルトのルールに基づいた判定結果です。
+   */
+  defaultShouldAction: boolean;
+};
+
+/**
+ * 特定の条件でアクションを実行するかどうかを制御するインターフェースです。
+ *
+ * @template TPath パス文字列の型です。
+ */
+export interface IShouldAction<TPath extends string = string> {
+  /**
+   * アクションの実行可否を判定します。
+   *
+   * @param args 判定に必要なパラメーターとリクエスト情報です。
+   * @returns アクションを実行する場合は `true`、そうでない場合は `false` を返します。
+   */
+  (args: ShouldActionArgs<TPath>): boolean;
+}
+
+/**
+ * アクション関数（`action`）に渡される引数の型定義です。
+ *
+ * @template TPath パス文字列の型です。
+ */
+export type ActionArgs<TPath extends string = string> = {
+  /**
+   * URL から抽出されたパスパラメーターのオブジェクトです。
+   */
+  params: PathParams<TPath>;
+
+  /**
+   * ルーティングに関するリクエスト情報です。
+   */
+  request: RouteRequest;
+};
+
+/**
+ * データの更新処理などを行うアクション関数のインターフェースです。
+ *
+ * @template TPath パス文字列の型です。
+ * @template TData アクションが返すデータの型です。
+ */
+export interface IAction<TPath extends string = string, TData = unknown> {
+  /**
+   * 指定された引数に基づいてアクションを実行します。
+   *
+   * @param args アクションの実行に必要なパラメーターとリクエスト情報です。
+   * @returns 処理結果として任意のデータを返します。
+   */
+  (args: ActionArgs<TPath>): TData;
+}
+
+/**
+ * データの再読み込み（リロード）を行うべきかどうかを判定する関数に渡される引数の型定義です。
+ *
+ * GET リクエスト時と POST リクエスト時で異なるプロパティーを持ちます。
+ *
+ * @template TPath 現在のパス文字列の型です。
+ */
+export type ShouldReloadArgs<TPath extends string = string> = {
+  /**
+   * 最読み込みをトリガーしたリクエストメソッドです。
+   */
+  triggerMethod: "GET";
+
+  /**
+   * 現在の URL オブジェクトです。
+   */
+  currentUrl: ReadonlyURL;
+
+  /**
+   * 現在のパスパラメーターです。
+   */
+  currentParams: PathParams<TPath>;
+
+  /**
+   * 遷移前の URL オブジェクトです。
+   */
+  prevUrl: ReadonlyURL;
+
+  /**
+   * 遷移前のパスパラメーターです。
+   */
+  prevParams: PathParams;
+
+  /**
+   * 送信されたフォームデータです。GET 時は常にありません。
+   */
+  formData?: undefined;
+
+  /**
+   * 直前に行われたアクションの結果です。GET 時は常にありません。
+   */
+  actionResult?: undefined;
+
+  /**
+   * デフォルトのルールに基づいた判定結果です。
+   */
+  defaultShouldReload: boolean;
+} | {
+  /**
+   * 最読み込みをトリガーしたリクエストメソッドです。
+   */
+  triggerMethod: "POST";
+
+  /**
+   * 現在の URL オブジェクトです。
+   */
+  currentUrl: ReadonlyURL;
+
+  /**
+   * 現在のパスパラメーターです。
+   */
+  currentParams: PathParams<TPath>;
+
+  /**
+   * 遷移前の URL オブジェクトです。
+   */
+  prevUrl: ReadonlyURL;
+
+  /**
+   * 遷移前のパスパラメーターです。
+   */
+  prevParams: PathParams;
+
+  /**
+   * 送信されたフォームデータです。
+   */
+  formData: FormData;
+
+  /**
+   * 直前に行われたアクションの結果です。
+   */
+  actionResult?: unknown;
+
+  /**
+   * デフォルトのルールに基づいた判定結果です。
+   */
+  defaultShouldReload: boolean;
+};
+
+/**
+ * データの再読み込みが必要かどうかを判定するインターフェースです。
+ *
+ * @template TPath パス文字列の型です。
+ */
+export interface IShouldReload<TPath extends string = string> {
+  /**
+   * 再読み込みの要否を判定します。
+   *
+   * @param args 遷移先後やアクションの結果を含む判定用データです。
+   * @returns 再読み込みを行う場合は `true`、そうでない場合は `false` を返します。
+   */
+  (args: ShouldReloadArgs<TPath>): boolean;
+}
+
+/**
+ * ローダー関数（`loader`）に渡される引数の型定義です。
+ *
+ * @template TPath パス文字列の型です。
+ */
+export type LoaderArgs<TPath extends string = string> = {
+  /**
+   * URL から抽出されたパスパラメーターのオブジェクトです。
+   */
+  params: PathParams<TPath>;
+
+  /**
+   * ルーティングに関するリクエスト情報です。
+   */
+  request: RouteRequest;
+};
+
+/**
+ * データを取得するためのローダー関数のインターフェースです。
+ *
+ * @template TPath パス文字列の型です。
+ * @template TData ローダーが取得するデータの型です。
+ */
+export interface ILoader<TPath extends string = string, TData = unknown> {
+  /**
+   * 指定された引数に基づいてデータを読み込みます。
+   *
+   * @param args データ取得に必要なパラメーターとリクエスト情報です。
+   * @returns 取得したデータを返します。
+   */
+  (args: LoaderArgs<TPath>): TData;
+}
+
+/**
+ * ルートに紐づくデータ処理用の関数群をまとめたオブジェクトの型定義です。
+ *
+ * @template TPath パス文字列の型です。
+ */
+export type DataFunctionObject<TPath extends string = string> = {
+  /**
+   * アクションを実行すべきか判定するオプションの関数です。
+   */
+  readonly shouldAction?: IShouldAction<TPath> | undefined;
+
+  /**
+   * データの更新などを行うオプションのアクション関数です。
+   */
+  readonly action?: IAction<TPath> | undefined;
+
+  /**
+   * データを再読み込みすべきか判定するオプションの関数です。
+   */
+  readonly shouldReload?: IShouldReload<TPath> | undefined;
+
+  /**
+   * データを取得するオプションのローダー関数です。
+   */
+  readonly loader?: ILoader<TPath> | undefined;
+};
+
+/**
+ * ルーティングの定義を表す型定義です。
+ *
+ * @template TPath パス文字列の型です。
+ */
+export type RouteDefinition<TPath extends string = string> = {
+  /**
+   * ルートのパス（パスパターン）です。
+   */
+  readonly path: TPath;
+
+  /**
+   * このルートで使用するデータ操作関数の配列です。
+   */
+  readonly dataFunctions?: readonly DataFunctionObject<TPath>[] | undefined;
+
+  /**
+   * このルートで描画される React コンポーネントです。
+   */
+  readonly component?: React.ComponentType<{}> | undefined;
+
+  /**
+   * 子ルートの定義リストです。
+   */
+  readonly children?: readonly RouteDefinition[] | undefined;
+};
+
+/**
+ * ルート情報を表す型定義です。
+ */
+export type Route = {
+  /**
+   * 正規化されたルートのパス（パスパターン）です。
+   */
+  readonly path: string;
+
+  /**
+   * このルートがインデックスルート（子ルートを持たない末端のルート）かどうかを示します。
+   */
+  readonly index: boolean;
+
+  /**
+   * パスマッチングに使用される正規表現オブジェクトです。
+   */
+  readonly pathPattern: RegExp;
+
+  /**
+   * パスから抽出されたパラメーター名の配列です。
+   */
+  readonly paramKeys: readonly string[];
+
+  /**
+   * このルートに紐づくデータ操作関数群の配列です。
+   *
+   * デフォルトの判定関数などが補完された状態で保持されます。
+   */
+  readonly dataFuncs: readonly {
+    /**
+     * アクションの実行可否を判定します。
+     *
+     * @param args 判定に必要なパラメーターとリクエスト情報です。
+     * @returns アクションを実行する場合は `true`、そうでない場合は `false` を返すはずです。
+     */
+    readonly shouldAction: (args: ShouldActionArgs) => unknown;
+
+    /**
+     * データの更新などを行うオプションのアクション関数です。
+     */
+    readonly action: IAction | undefined;
+
+    /**
+     * 再読み込みの要否を判定します。
+     *
+     * @param args 遷移先後やアクションの結果を含む判定用データです。
+     * @returns 再読み込みを行う場合は `true`、そうでない場合は `false` を返すはずです。
+     */
+    readonly shouldReload: (args: ShouldReloadArgs) => unknown;
+
+    /**
+     * データを取得するオプションのローダー関数です。
+     */
+    readonly loader: ILoader | undefined;
+  }[];
+
+  /**
+   * このルートで描画される React コンポーネントです。
+   */
+  readonly component: React.ComponentType<{}> | undefined;
+
+  /**
+   * 前処理済みの子ルートの配列です。
+   */
+  readonly children: readonly Route[];
+};

package/src/core/start-actions.ts

@@ -0,0 +1,274 @@
+import actionIdRegistry from "./_action-id-registry.js";
+import unreachable from "./_unreachable.js";
+import { ACTION_ID_FORM_DATA_NAME } from "./constants.js";
+import type { IDataMap } from "./data-map.types.js";
+import type { IDataStore } from "./data-store.types.js";
+import DeferredPromise from "./deferred-promise.js";
+import { ActionConditionError, ActionExecutionError, MultipleRedirectError } from "./errors.js";
+import type { HistoryEntry } from "./expect-history-entry.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 { IAction } from "./route.types.js";
+
+/**
+ * アクションの開始に使用するパラメーターの型定義です。
+ */
+export type StartActionsParams = {
+  /**
+   * マッチしたルート情報のリストです。パラメーターとデータ関数を含みます。
+   */
+  readonly routes: readonly Pick<MatchedRoute, "params" | "urlPath" | "dataFuncs">[];
+
+  /**
+   * 履歴エントリーの情報です。 ID と URL を含みます。
+   */
+  readonly entry: Pick<HistoryEntry, "id" | "url">;
+
+  /**
+   * フォームから送信された読み取り専用のデータです。
+   */
+  readonly formData: ReadonlyFormData;
+
+  /**
+   * アクションの結果を保持するためのデータストアです。
+   */
+  readonly dataStore: IDataStore<IAction>;
+
+  /**
+   * 非同期処理を中断するためのシグナルです。
+   */
+  readonly signal: AbortSignal;
+};
+
+/**
+ * アクションの実行結果を表す型定義です。
+ */
+export type ActionsResult = {
+  /**
+   * リダイレクトが必要な場合のパス名です。リダイレクトが発生しない場合は undefined となります。
+   */
+  redirect: string | undefined;
+
+  /**
+   * 各アクションと実行結果を紐付けたマップです。
+   */
+  resultMap: ReadonlyMap<IAction, unknown>;
+};
+
+/**
+ * ルートに定義されたアクションの実行を開始します。
+ *
+ * 条件に合致するアクションが存在する場合、それらを待機するための非同期関数を返します。
+ *
+ * @param params アクションの開始に必要なパラメーターオブジェクトです。
+ * @returns アクションの完了を待機するための関数です。実行すべきアクションがない場合は undefined を返します。
+ */
+export default function startActions(params: StartActionsParams): undefined | {
+  /**
+   * アクションの完了を待機し、結果を集約して返す非同期関数です。
+   *
+   * @returns アクションの結果（リダイレクト先や実行結果のマップ）を返します。
+   */
+  (): Promise<ActionsResult>;
+} {
+  const {
+    entry,
+    routes,
+    signal,
+    formData,
+    dataStore,
+  } = params;
+  const request = new RouteRequest("POST", entry.url, signal, formData);
+  const redirects: string[] = [];
+  const dataIncMap: IDataMap<IAction> = new Map();
+  let encountered = false;
+  // ルートを走査し、実行すべきアクションを特定します。
+  for (const route of routes) {
+    for (const { action, shouldAction } of route.dataFuncs) {
+      if (!action) {
+        continue;
+      }
+
+      // アクションを持つルートが見つかったため、フラグを立てます。
+      encountered = true;
+
+      // アクションを実行すべきかどうかを判定します。
+      const should = DeferredPromise.try(function executeShouldAction() {
+        return shouldAction({
+          params: route.params,
+          request,
+          defaultShouldAction: formData.has(ACTION_ID_FORM_DATA_NAME)
+            ? formData.get(ACTION_ID_FORM_DATA_NAME) === actionIdRegistry.get(action)
+            : true,
+        });
+      });
+
+      let data: DeferredPromise<unknown>;
+      switch (should.status) {
+        case "pending": {
+          // shouldAction は同期的に真偽値を返す必要があるので、pending 状態（つまり非同期）であってはいけません。
+          const error = new ActionConditionError(request.url.href, shouldAction, should);
+          // エラーハンドリングは、このアクションデータを参照するコンポーネントに任せます。
+          data = DeferredPromise.reject(error);
+          break;
+        }
+
+        case "rejected":
+          // エラーハンドリングは、このアクションデータを参照するコンポーネントに任せます。
+          data = should;
+          break;
+
+        case "fulfilled": {
+          const { value } = should;
+          switch (value) {
+            case true: {
+              // 条件を満たす場合のみ、アクションの実行をスケジュールします。
+              const clientData = DeferredPromise.try(function executeAction() {
+                return action({
+                  params: route.params,
+                  request,
+                });
+              });
+              switch (clientData.status) {
+                case "pending": {
+                  // 特定の返り値を別の値に入れ替えるために中継 DeferredPromise をアクションデータとします。
+                  const proxy = DeferredPromise.withResolvers();
+                  data = proxy.promise;
+                  (async () => {
+                    try {
+                      const value = await clientData;
+                      switch (true) {
+                        case value instanceof RedirectResponse:
+                          // リダイレクトを指示する返り値を記録し、コンポーネントが参照するデータを undefined に置き換えます。
+                          redirects.push(value.pathname);
+                          proxy.resolve(undefined);
+                          break;
+
+                        default:
+                          proxy.resolve(value);
+                      }
+                    } catch (ex) {
+                      proxy.reject(ex);
+                    }
+                  })();
+                  break;
+                }
+
+                case "rejected":
+                  // エラーハンドリングは、このアクションデータを参照するコンポーネントに任せます。
+                  data = clientData;
+                  break;
+
+                case "fulfilled": {
+                  const { value } = clientData;
+                  switch (true) {
+                    case value instanceof RedirectResponse:
+                      // リダイレクトを指示する返り値を記録し、コンポーネントが参照するデータを undefined に置き換えます。
+                      redirects.push(value.pathname);
+                      data = DeferredPromise.resolve(undefined);
+                      break;
+
+                    default:
+                      data = clientData;
+                  }
+
+                  break;
+                }
+
+                default:
+                  unreachable(clientData);
+              }
+
+              break;
+            }
+
+            case false:
+              // 条件を満たさない場合はアクションの実行をスキップします。
+              continue;
+
+            default: {
+              // shouldAction が真偽値を返さなかった場合、エラーとします。
+              const error = new ActionConditionError(request.url.href, shouldAction, value);
+              // エラーハンドリングは、このアクションデータを参照するコンポーネントに任せます。
+              data = DeferredPromise.reject(error);
+            }
+          }
+
+          break;
+        }
+
+        default:
+          unreachable(should);
+      }
+
+      dataIncMap.set(action, data);
+    }
+
+    // アクションを持つルートが見つかった時点で走査を終了します。
+    if (encountered) {
+      break;
+    }
+  }
+
+  if (!encountered) {
+    // 実行されたアクションが無い場合は、これ以上することは何もありません。
+    return;
+  }
+
+  if (dataIncMap.size <= 0) {
+    return async () => ({
+      redirect: undefined,
+      resultMap: new Map(),
+    });
+  }
+
+  // 特定されたアクションのマップをデータストアに格納します。
+  const dataMap = dataStore.get(entry.id);
+  if (dataMap) {
+    for (const [action, data] of dataIncMap) {
+      dataMap.set(action, data);
+    }
+  } else {
+    dataStore.set(entry.id, dataIncMap);
+  }
+
+  return async function waitForActionsComplete() {
+    const resultMap: IDataMap<IAction, unknown> = new Map();
+    const promises: Promise<void>[] = [];
+    const rejected: { action: IAction; reason: unknown }[] = [];
+    for (const [action, data] of dataIncMap) {
+      const promise = (async () => {
+        try {
+          const value = await data;
+          resultMap.set(action, value);
+        } catch (ex) {
+          rejected.push({
+            action,
+            reason: ex,
+          });
+        }
+      })();
+      promises.push(promise);
+    }
+
+    // すべてのアクションの完了を待ちます。
+    await Promise.all(promises);
+
+    // エラーが発生したアクションがある場合は例外を投げます。
+    if (rejected.length > 0) {
+      throw new ActionExecutionError(request.url.href, rejected);
+    }
+
+    // 複数のアクションからリダイレクトが返された場合は不正な状態としてエラーを投げます。
+    if (redirects.length > 1) {
+      throw new MultipleRedirectError(request.url.href, redirects);
+    }
+
+    return {
+      redirect: redirects[0],
+      resultMap,
+    };
+  };
+}