soseki 0.0.1

package/src/core/start-loaders.ts

@@ -0,0 +1,254 @@
+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 { MatchedRoute } from "./match-routes.js";
+import RouteRequest from "./route-request.js";
+import type { IAction, ILoader, ShouldReloadArgs } from "./route.types.js";
+
+/**
+ * `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;
+  });
+
+/**
+ * ルートに紐付くローダーの実行を開始し、データの同期や再読み込みの判定を行います。
+ *
+ * @param params ローダーの開始に必要なパラメーターオブジェクトです。
+ * @returns すべてのローダーの完了を待機する非同期関数を返します。ローダーが不要な場合は `undefined` を返します。
+ */
+export default function startLoaders(params: StartLoadersParams): undefined | {
+  /**
+   * 実行中のすべてのローダーが完了するまで待機します。
+   */
+  (): Promise<void>;
+} {
+  const {
+    signal,
+    prevEntry,
+    prevRoutes,
+    currentEntry,
+    currentRoutes,
+    actionDataStore,
+    loaderDataStore,
+    ...options
+  } = params;
+  // ローダーの実行前にアクションが実行された場合、その情報を使ってローダーの処理を分岐させます。
+  const actionContext = options.formData && {
+    formData: options.formData,
+    resultMap: options.actionResultMap,
+  };
+  // 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）を走査します。
+  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);
+        }
+      }
+
+      if (!loader) {
+        continue;
+      }
+
+      const prevLoaderData = prevLoaderDataMap?.get(loader);
+      if (!prevLoaderData) {
+        // 遷移前のローダーデータがない場合、新規ルートの描画と判定して、強制ロードします。
+        // ローダーの実行を遅延評価としてラップします。
+        const data = DeferredPromise.try(function executeLoader() {
+          return loader({
+            params: currentRoute.params,
+            request,
+          });
+        });
+        // ローダーの結果を待機、エラーハンドリングする処理は、この結果を参照するコンポーネントに任せます。
+        currentLoaderDataIncMap.set(loader, data);
+        continue;
+      }
+
+      // リロードすべきかどうかを判定します。
+      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),
+          });
+        }
+
+        // 特定のアクションが実行された後の再読み込み判定引数を構築します。
+        const {
+          formData,
+          resultMap,
+        } = actionContext;
+        let shouldArgs: ShouldReloadArgs = {
+          prevUrl: prevEntry.url,
+          formData,
+          currentUrl: prevEntry.url,
+          prevParams,
+          currentParams: currentRoute.params,
+          triggerMethod: "POST",
+          defaultShouldReload: resultMap.size > 0,
+        };
+        if (action && resultMap.has(action)) {
+          // アクションの結果があるときのみプロパティーを設定します。
+          shouldArgs.actionResult = resultMap.get(action);
+        }
+
+        return shouldReload(shouldArgs);
+      });
+
+      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;
+        }
+
+        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);
+            }
+          }
+
+          break;
+        }
+
+        default:
+          unreachable(should);
+      }
+
+      currentLoaderDataIncMap.set(loader, data);
+    }
+  }
+
+  // アクションデータの更新処理です。
+  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);
+    }
+  }
+
+  // ローダーデータの更新処理です。
+  const dataMap = loaderDataStore.get(currentEntry.id);
+  if (dataMap) {
+    for (const [loader, data] of currentLoaderDataIncMap) {
+      dataMap.set(loader, data);
+    }
+  } else {
+    loaderDataStore.set(currentEntry.id, currentLoaderDataIncMap);
+  }
+
+  return async function waitForLoadersComplete() {
+    await Promise.allSettled(currentLoaderDataIncMap.values());
+  };
+}

package/src/core.ts

@@ -0,0 +1,43 @@
+export { default as Router } from "./components/outlet.jsx";
+export type * from "./components/router.jsx";
+
+export type * from "./contexts/route-context.js";
+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";
+
+export type * from "./core/history-entry-id-schema.js";
+export { default as HistoryEntryIdSchema } from "./core/history-entry-id-schema.js";
+
+export type * from "./core/history-entry-url-schema.js";
+export { default as HistoryEntryUrlSchema } from "./core/history-entry-url-schema.js";
+
+export type * from "./core/init-loaders.js";
+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/start-actions.js";
+export { default as startActions } from "./core/start-actions.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";

package/src/engines/engine.types.ts

@@ -0,0 +1,216 @@
+import type { IDataStore } from "../core/data-store.types.js";
+import type { HistoryEntry } from "../core/expect-history-entry.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";
+
+/**
+ * ルーターの初期状態を生成する際に必要な引数の型定義です。
+ */
+export type InitEngineArgs = {
+  /**
+   * 前処理済みのルート定義の配列です。
+   */
+  readonly routes: readonly Route[];
+
+  /**
+   * 現在の非同期処理を中断するためのシグナルを取得する関数です。
+   */
+  readonly getSignal: () => AbortSignal;
+
+  /**
+   * ロケーション ID ごとに管理されているローダーデータのマップです。
+   */
+  readonly loaderDataStore: IDataStore<ILoader>;
+};
+
+/**
+ * ルーターの現在の状態を表す型定義です。
+ */
+export type RouterState = {
+  /**
+   * 現在のロケーションエントリー情報です。
+   */
+  readonly entry: HistoryEntry;
+
+  /**
+   * 現在の URL にマッチしたルートの階層構造です。
+   *
+   * 最低でも 1 つのマッチしたルートが含まれるタプル形式となります。
+   */
+  readonly 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 = {
+  /**
+   * 送信対象となるフォームデータです。
+   */
+  readonly target: ReadonlyFormData;
+
+  /**
+   * 送信先のパスです。
+   */
+  readonly action: string;
+
+  /**
+   * 実行するアクションの定義です。
+   */
+  readonly actionId: IAction | undefined;
+} | {
+  /**
+   * 送信対象となる URL クエリーパラメーターです。
+   */
+  readonly target: ReadonlyURLSearchParams;
+
+  /**
+   * 送信先のパスです。
+   */
+  readonly action: string;
+
+  /**
+   * 履歴の追加方法を指定します。
+   *
+   * "replace" は現在のエントリーを置き換え、"push" は新しいエントリーを追加します。
+   */
+  readonly history: "replace" | "push";
+};
+
+/**
+ * ナビゲーションの移動先を示す型定義です。
+ *
+ * パス文字列または詳細なパス情報のオブジェクトを受け取ります。
+ */
+export type NavigateTo = string | {
+  /**
+   * URL のパス名を表します。
+   */
+  readonly pathname?: string | undefined;
+
+  /**
+   * URL のクエリーパラメーターを表します。
+   */
+  readonly search?: string | undefined;
+
+  /**
+   * URL のハッシュフラグメントを表します。
+   */
+  readonly hash?: string | undefined;
+};
+
+/**
+ * エンジンの遷移関数に渡される引数の型定義です。
+ */
+export type NavigateArgs = {
+  /**
+   * 遷移先です。
+   */
+  readonly to: NavigateTo;
+
+  /**
+   * 履歴の追加方法を指定します。
+   *
+   * "replace" は現在のエントリーを置き換え、"push" は新しいエントリーを追加します。
+   */
+  readonly history: "replace" | "push";
+} | {
+  /**
+   * 履歴スタックの相対位置です。
+   */
+  readonly delta: number;
+};
+
+/**
+ * ルーティングの基幹処理を担うエンジンのインターフェースです。
+ */
+export interface IEngine {
+  /**
+   * 与えられた引数に基づいて、ルーターを初期化します。
+   *
+   * @param args 状態生成に必要なルート情報やデータマップです。
+   * @returns 生成されたルーター状態、またはマッチしなかった場合は `null` を返します。
+   */
+  init(args: InitEngineArgs): RouterState | null;
+
+  /**
+   * エンジンの動作を開始します。履歴の変化の監視などを開始します。
+   *
+   * @param args エンジンの開始に必要な設定とコールバック関数です。
+   * @returns エンジンを停止するための関数を返します。停止処理が不要な場合は何も返しません。
+   */
+  start(args: StartEngineArgs): IStopEngine | void;
+
+  /**
+   * フォームデータやクエリー パラメーターを送信します。
+   *
+   * @param args 送信内容と送信先を含む引数です。
+   */
+  submit(args: SubmitArgs): void;
+
+  /**
+   * 指定されたパスへ遷移します。
+   *
+   * @param args 遷移先と遷移オプションを含む引数です。
+   */
+  navigate(args: NavigateArgs): void;
+}