soseki 0.0.5 → 0.0.7

package/src/core/route.types.ts

@@ -1,351 +1,375 @@
 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";
+import type { RouteGetRequest, RoutePostRequest } from "./route-request.js";
 
 /**
- * パスパラメーターの内部的な型定義です。
+ * 個別のパスパラメーターを解析し、適切なプロパティーの型オブジェクトへと変換する内部ユーティリティー型です。
+ *
+ * パラメーターの末尾の形状を条件付き型により詳細に選別します。
  *
- * @template TParams `regexparam` から抽出されたパラメーターの型です。
+ * @template Param 解析対象となる単一のパラメーター文字列です。
  */
-// dprint-ignore
-type PathParams_<TParams extends { [_ in string]?: string }> =
-    [keyof TParams] extends [never]
-  ? { readonly [_ in string]?: string }
-  : Readonly<TParams>
+// oxfmt-ignore
+type ParamRecord<Param extends string> =
+  // パラメーター末尾に「?」がある場合、オプショナルなプロパティー型に変換します
+    Param extends `${infer Name}?`
+    ? { [K in Name]?: string }
+
+  // パラメーターに拡張子が含まれている場合、拡張子を除いた名前を必須のプロパティー型に変換します。
+  : Param extends `${infer Name}.${string}`
+    ? { [K in Name]: string }
+
+  // 上記のいずれのパターンにも該当しない場合は、パラメーター名をそのまま必須のプロパティー型に変換します。
+  : { [K in Param]: string };
 
 /**
- * 指定されたパス文字列からパラメーターを抽出するための型定義です。
+ * パス文字列のセグメントから動的なパラメーターやワイルドカードを再帰的に抽出し、型安全なオブジェクト構造を構築するユーティリティー型です。
  *
- * @template TPath 解析対象となるパス文字列の型です。
+ * 開発者が指定した文字列リテラル型の形状に基づいて、ルーティングに必要なパラメーターの型を静的に決定します。
+ *
+ * このユーティリティー型は、ライブラリー `regexparam` の改良版です。
+ *
+ * @template T 解析対象となる URL パス全体の文字列リテラル型です。
+ * @see https://github.com/lukeed/regexparam
+ * @see https://github.com/lukeed/regexparam/issues/31
+ * @see https://github.com/lukeed/regexparam/pull/33
  */
-export type PathParams<TPath extends string = string> = PathParams_<RouteParams<TPath>>;
+// oxfmt-ignore
+type RouteParams<T extends string> =
+  // 与えられた型が具体的なリテラルでなく文字列型である場合は、汎用的なレコード型へとフォールバックします。
+    string extends T
+    ? { [K in string]?: string }
+
+  // パスの中間にワイルドカードが存在する場合、前後のパラメーターに加えて、必須のワイルドカードプロパティーを結合します。
+  : T extends `${infer Prev}/*/${infer Rest}`
+    ? & RouteParams<Prev>
+      & { wild: string }
+      & RouteParams<`/${Rest}`>
+
+  // パスの先頭がコロンで開始されている場合、先頭にスラッシュ（/）を補正して再帰的に再評価します。
+  : T extends `:${infer Rest}`
+    ? RouteParams<`/:${Rest}`>
+
+  // パスの中間にコロンで始まるパラメーターが含まれている場合、そのセグメントの型情報を抽出し、スラッシュ以降の残りのパスの解析結果と交差型で結合します。
+  : T extends `${string}:${infer Param}/${infer Rest}`
+    ? & ParamRecord<Param>
+      & RouteParams<`/${Rest}`>
+
+  // パスの末尾がコロンで始まるパラメーターで終了している場合、そのセグメントの型情報を判定して抽出を完了します。
+  : T extends `${string}/:${infer Param}`
+    ? ParamRecord<Param>
+
+  // パスの末尾がオプショナルワイルドカードで終了している場合、キー名を「"*"」としたオプショナルなプロパティー型を返します。
+  : T extends `${string}/*?`
+    ? { "*"?: string }
+
+  // パスの末尾が通常のワイルドカードで終了している場合、キー名を「"*"」とした必須のプロパティー型を返します。
+  : T extends `${string}/*`
+    ? { "*": string }
+
+  // 抽出可能なパラメーターやワイルドカードが一切検出されなかった場合は、空のオブジェクト型を返します。
+  : {};
 
 /**
- * アクションを実行すべきかどうかを判定する関数（`shouldAction`）に渡される引数の型定義です。
+ * 文字列リテラルとして定義されたパスの形状から、含まれるパスパラメーターを解析し、静的に型付けされたオブジェクトとして抽出する型定義です。
  *
- * @template TPath パス文字列の型です。
+ * @template TRoutePath パラメーター抽出の対象となるパス文字列リテラル型です。
  */
-export type ShouldActionArgs<TPath extends string = string> = {
-  /**
-   * URL から抽出されたパスパラメーターのオブジェクトです。
-   */
-  params: PathParams<TPath>;
+export type RoutePathParams<TRoutePath extends string = string> = Readonly<RouteParams<TRoutePath>>;
 
+/**
+ * データ更新などのアクション処理を実行する際に、該当する関数へ渡される引数の型定義です。
+ *
+ * 解析済みのパスパラメーターと、HTTP の POST メソッドを抽象化したリクエストオブジェクトを含みます。
+ *
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ */
+export type ActionFunctionArgs<TRoutePath extends string = string> = {
   /**
-   * ルーティングに関するリクエスト情報です。
+   * 現在の URL パスから抽出されたパラメーターオブジェクトです。
    */
-  request: RouteRequest;
+  params: RoutePathParams<TRoutePath>;
 
   /**
-   * デフォルトのルールに基づいた判定結果です。
+   * フォームデータなどを内包する、HTTP の POST メソッドに特化したルーティングリクエストオブジェクトです。
    */
-  defaultShouldAction: boolean;
+  request: RoutePostRequest;
 };
 
 /**
- * 特定の条件でアクションを実行するかどうかを制御するインターフェースです。
+ * データの登録、更新、削除といった副作用を伴うアクション処理を定義するための関数インターフェースです。
  *
- * @template TPath パス文字列の型です。
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TData アクション関数が返す戻り値の型定義です。既定値は `unknown` です。
  */
-export interface IShouldAction<TPath extends string = string> {
-  /**
-   * アクションの実行可否を判定します。
-   *
-   * @param args 判定に必要なパラメーターとリクエスト情報です。
-   * @returns アクションを実行する場合は `true`、そうでない場合は `false` を返します。
-   */
-  (args: ShouldActionArgs<TPath>): boolean;
+export interface ActionFunction<TRoutePath extends string = string, TData = unknown> {
+  (args: ActionFunctionArgs<TRoutePath>): TData;
 }
 
 /**
- * アクション関数（`action`）に渡される引数の型定義です。
+ * ページ遷移やデータ更新が発生した際、現在の画面データを再読み込みすべきかどうかを判定する関数へ渡される引数の型定義です。
+ *
+ * アクションを実行した契機となる HTTP メソッドの種類（GET / POST）に応じて、含まれるコンテキスト情報が分岐します。
  *
- * @template TPath パス文字列の型です。
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
  */
-export type ActionArgs<TPath extends string = string> = {
-  /**
-   * URL から抽出されたパスパラメーターのオブジェクトです。
-   */
-  params: PathParams<TPath>;
-
-  /**
-   * ルーティングに関するリクエスト情報です。
-   */
-  request: RouteRequest;
-};
+export type ShouldReloadFunctionArgs<TRoutePath extends string = string> =
+  | {
+      /**
+       * 再読み込みを引き起こした HTTP メソッドの種別です。
+       */
+      triggerMethod: "GET";
+
+      /**
+       * 現在の画面に対応する読み取り専用 URL オブジェクトです。
+       */
+      currentUrl: ReadonlyURL;
+
+      /**
+       * 現在の URL から抽出されたパスパラメーターです。
+       */
+      currentParams: RoutePathParams<TRoutePath>;
+
+      /**
+       * POST リクエストが発生する直前の読み取り専用 URL オブジェクトです。
+       */
+      prevUrl: ReadonlyURL;
+
+      /**
+       * POST リクエストが発生する直前の URL から抽出されたパスパラメーターです。
+       */
+      prevParams: RoutePathParams;
+
+      /**
+       * システムが内部ロジックに基づいて判断した、再読み込み実行の既定の判定フラグです。
+       */
+      defaultShouldReload: boolean;
+    }
+  | {
+      /**
+       * 再読み込みを引き起こした HTTP メソッドの種別です。
+       */
+      triggerMethod: "POST";
+
+      /**
+       * 現在の画面に対応する読み取り専用 URL オブジェクトです。
+       */
+      currentUrl: ReadonlyURL;
+
+      /**
+       * 現在の URL から抽出されたパスパラメーターです。
+       */
+      currentParams: RoutePathParams<TRoutePath>;
+
+      /**
+       * POST リクエストが発生する直前の読み取り専用 URL オブジェクトです。
+       */
+      prevUrl: ReadonlyURL;
+
+      /**
+       * POST リクエストが発生する直前の URL から抽出されたパスパラメーターです。
+       */
+      prevParams: RoutePathParams;
+
+      /**
+       * POST リクエストと共に送信された標準のフォームデータオブジェクトです。
+       */
+      formData: FormData;
+
+      /**
+       * 直前に実行されたアクション関数から返されたデータです。
+       */
+      actionData: unknown;
+
+      /**
+       * システムが内部ロジックに基づいて判断した、再読み込み実行の既定の判定フラグです。
+       */
+      defaultShouldReload: boolean;
+    };
 
 /**
- * データの更新処理などを行うアクション関数のインターフェースです。
+ * ルートデータの再読み込みが不必要な場合に、余分な通信や再取得処理を抑制するための判定関数インターフェースです。
  *
- * @template TPath パス文字列の型です。
- * @template TData アクションが返すデータの型です。
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @returns データを再読み込みする場合は `true`、スキップする場合は `false` を返します。
  */
-export interface IAction<TPath extends string = string, TData = unknown> {
-  /**
-   * 指定された引数に基づいてアクションを実行します。
-   *
-   * @param args アクションの実行に必要なパラメーターとリクエスト情報です。
-   * @returns 処理結果として任意のデータを返します。
-   */
-  (args: ActionArgs<TPath>): TData;
+export interface ShouldReloadFunction<TRoutePath extends string = string> {
+  (args: ShouldReloadFunctionArgs<TRoutePath>): boolean;
 }
 
 /**
- * データの再読み込み（リロード）を行うべきかどうかを判定する関数に渡される引数の型定義です。
+ * 画面の描画に必要なデータを取得（ロード）する際に、該当する関数へ渡される引数の型定義です。
  *
- * GET リクエスト時と POST リクエスト時で異なるプロパティーを持ちます。
+ * 解析済みのパスパラメーターと、HTTP の GET メソッドを抽象化したリクエストオブジェクトを含みます。
  *
- * @template TPath 現在のパス文字列の型です。
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
  */
-export type ShouldReloadArgs<TPath extends string = string> = {
+export type LoaderFunctionArgs<TRoutePath extends string = string> = {
   /**
-   * 最読み込みをトリガーしたリクエストメソッドです。
+   * 現在の URL パスから抽出されたパラメーターオブジェクトです。
    */
-  triggerMethod: "GET";
+  params: RoutePathParams<TRoutePath>;
 
   /**
-   * 現在の URL オブジェクトです。
+   * HTTP の GET メソッドに特化したルーティングリクエストオブジェクトです。
    */
-  currentUrl: ReadonlyURL;
-
-  /**
-   * 現在のパスパラメーターです。
-   */
-  currentParams: PathParams<TPath>;
-
-  /**
-   * 遷移前の URL オブジェクトです。
-   */
-  prevUrl: ReadonlyURL;
-
-  /**
-   * 遷移前のパスパラメーターです。
-   */
-  prevParams: PathParams;
-
-  /**
-   * 送信されたフォームデータです。GET 時は常にありません。
-   */
-  formData?: undefined;
-
-  /**
-   * 直前に行われたアクションの結果です。GET 時は常にありません。
-   */
-  actionResult?: undefined;
-
-  /**
-   * デフォルトのルールに基づいた判定結果です。
-   */
-  defaultShouldReload: boolean;
-} | {
-  /**
-   * 最読み込みをトリガーしたリクエストメソッドです。
-   */
-  triggerMethod: "POST";
+  request: RouteGetRequest;
+};
 
-  /**
-   * 現在の URL オブジェクトです。
-   */
-  currentUrl: ReadonlyURL;
+/**
+ * 画面の初期描画時や遷移時にデータをオンデマンドで取得するための関数インターフェースです。
+ *
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TData ローダー関数が返す戻り値の型定義です。既定値は `unknown` です。
+ */
+export interface LoaderFunction<TRoutePath extends string = string, TData = unknown> {
+  (args: LoaderFunctionArgs<TRoutePath>): TData;
+}
 
+/**
+ * アプリケーションのルーティング設定を定義するためのオブジェクトの型定義です。
+ *
+ * 開発者が宣言的にルーティングのツリーやリストを記述する際に使用します。
+ *
+ * @template TPath ルートに関連付けるパス文字列リテラル型です。
+ */
+export type RouteDefinitionObject<TPath extends string = string> = {
   /**
-   * 現在のパスパラメーターです。
+   * マッチングの対象となる URL パスのパターン文字列です。
    */
-  currentParams: PathParams<TPath>;
+  readonly path: TPath;
 
   /**
-   * 遷移前の URL オブジェクトです。
+   * 親ルートのパスにおいて、インデックスルートとして機能させるかどうかのフラグです。
    */
-  prevUrl: ReadonlyURL;
+  readonly index?: boolean | undefined;
 
   /**
-   * 遷移前のパスパラメーターです。
+   * このルートで実行されるデータ更新用のアクション関数です。
    */
-  prevParams: PathParams;
+  readonly action?: ActionFunction<TPath> | undefined;
 
   /**
-   * 送信されたフォームデータです。
+   * このルートのデータ再読み込み動作を制御する判定関数です。
    */
-  formData: FormData;
+  readonly shouldReload?: ShouldReloadFunction<TPath> | undefined;
 
   /**
-   * 直前に行われたアクションの結果です。
+   * このルートの画面描画に必要なデータを取得する関数です。
    */
-  actionResult?: unknown;
+  readonly loader?: LoaderFunction<TPath> | undefined;
 
   /**
-   * デフォルトのルールに基づいた判定結果です。
+   * このルートに対応して描画される React のコンポーネントです。
    */
-  defaultShouldReload: boolean;
+  readonly component?: React.ComponentType<{}> | undefined;
 };
-
 /**
- * データの再読み込みが必要かどうかを判定するインターフェースです。
+ * ルーティング設定をインポート経由で定義するための構造体型定義です。
  *
- * @template TPath パス文字列の型です。
+ * @template TPath ルートに関連付けるパス文字列リテラル型です。
  */
-export interface IShouldReload<TPath extends string = string> {
+export type RouteDefinitionModule<TPath extends string = string> = {
   /**
-   * 再読み込みの要否を判定します。
-   *
-   * @param args 遷移先後やアクションの結果を含む判定用データです。
-   * @returns 再読み込みを行う場合は `true`、そうでない場合は `false` を返します。
+   * マッチングの対象となる URL パスのパターン文字列です。
    */
-  (args: ShouldReloadArgs<TPath>): boolean;
-}
+  readonly path: TPath;
 
-/**
- * ローダー関数（`loader`）に渡される引数の型定義です。
- *
- * @template TPath パス文字列の型です。
- */
-export type LoaderArgs<TPath extends string = string> = {
   /**
-   * URL から抽出されたパスパラメーターのオブジェクトです。
+   * 親ルートのパスにおいて、インデックスルートとして機能させるかどうかのフラグです。
    */
-  params: PathParams<TPath>;
+  readonly index?: boolean | undefined;
 
   /**
-   * ルーティングに関するリクエスト情報です。
+   * このルートで実行されるデータ更新用のアクション関数です。
    */
-  request: RouteRequest;
-};
+  readonly action?: ActionFunction<TPath> | undefined;
 
-/**
- * データを取得するためのローダー関数のインターフェースです。
- *
- * @template TPath パス文字列の型です。
- * @template TData ローダーが取得するデータの型です。
- */
-export interface ILoader<TPath extends string = string, TData = unknown> {
   /**
-   * 指定された引数に基づいてデータを読み込みます。
-   *
-   * @param args データ取得に必要なパラメーターとリクエスト情報です。
-   * @returns 取得したデータを返します。
+   * このルートのデータ再読み込み動作を制御する判定関数です。
    */
-  (args: LoaderArgs<TPath>): TData;
-}
+  readonly shouldReload?: ShouldReloadFunction<TPath> | undefined;
 
-/**
- * ルートに紐づくデータ処理用の関数群をまとめたオブジェクトの型定義です。
- *
- * @template TPath パス文字列の型です。
- */
-export type DataFunctionObject<TPath extends string = string> = {
   /**
-   * アクションを実行すべきか判定するオプションの関数です。
+   * このルートの画面描画に必要なデータを取得する関数です。
    */
-  readonly shouldAction?: IShouldAction<TPath> | undefined;
+  readonly loader?: LoaderFunction<TPath> | undefined;
 
   /**
-   * データの更新などを行うオプションのアクション関数です。
+   * このルートに対応して描画される React のコンポーネントです。
+   *
+   * `default` プロパティーよりこちらが優先されます。
    */
-  readonly action?: IAction<TPath> | undefined;
+  readonly component?: React.ComponentType<{}> | undefined;
 
   /**
-   * データを再読み込みすべきか判定するオプションの関数です。
+   * ES モジュールのデフォルトエクスポートとして定義された、描画対象となる React のコンポーネントです。
+   *
+   * `component` プロパティーがない場合はこちらにフォールバックされます。
    */
-  readonly shouldReload?: IShouldReload<TPath> | undefined;
+  readonly default?: React.ComponentType<{}> | undefined;
 
   /**
-   * データを取得するオプションのローダー関数です。
+   * オブジェクトの文字列表現をカスタマイズするための組み込みタグプロパティーです。
+   *
+   * モジュールオブジェクトとしての識別に使用します。
    */
-  readonly loader?: ILoader<TPath> | undefined;
+  get [Symbol.toStringTag](): string;
 };
 
 /**
- * ルーティングの定義を表す型定義です。
+ * アプリケーションのルーティング設定を定義するためのオブジェクトの型定義です。
  *
- * @template TPath パス文字列の型です。
+ * @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 RouteDefinition<TPath extends string = string> =
+  | RouteDefinitionObject<TPath>
+  | RouteDefinitionModule<TPath>;
 
 /**
- * ルート情報を表す型定義です。
+ * `RouteDefinition` を基にシステム内部で解析・コンパイルされ、ルーティングエンジンが直接処理を行うための実体化されたルートオブジェクトの型定義です。
+ *
+ * 省略可能だったプロパティーが正規化され、正規表現によるマッチング機構が追加されています。
  */
 export type Route = {
   /**
-   * 正規化されたルートのパス（パスパターン）です。
+   * マッチングの対象となる URL パスのパターン文字列です。
    */
   readonly path: string;
 
   /**
-   * このルートがインデックスルート（子ルートを持たない末端のルート）かどうかを示します。
+   * インデックスルートであるかどうかの確定的なフラグです。
    */
   readonly index: boolean;
 
   /**
-   * パスマッチングに使用される正規表現オブジェクトです。
+   * 実際の URL パスがこのルートに合致するかを検証するために動的に生成された正規表現オブジェクトです。
    */
   readonly pathPattern: RegExp;
 
   /**
-   * パスから抽出されたパラメーター名の配列です。
+   * パスパターン内に含まれるパラメーターのキー名を、順番通りに格納した読み取り専用の配列です。
    */
   readonly paramKeys: readonly string[];
 
   /**
-   * このルートに紐づくデータ操作関数群の配列です。
-   *
-   * デフォルトの判定関数などが補完された状態で保持されます。
+   * データ更新用のアクション関数です。未定義の場合は `undefined` となります。
    */
-  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;
-  }[];
+  readonly action: ActionFunction | undefined;
 
   /**
-   * このルートで描画される React コンポーネントです。
+   * データの再読み込み動作を制御する確定的な判定関数です。定義がない場合はシステム既定の挙動を行う関数が割り当てられます。
    */
-  readonly component: React.ComponentType<{}> | undefined;
+  readonly shouldReload: ShouldReloadFunction;
+
+  /**
+   * 画面描画に必要なデータを取得する関数です。未定義の場合は `undefined` となります。
+   */
+  readonly loader: LoaderFunction | undefined;
 
   /**
-   * 前処理済みの子ルートの配列です。
+   * 表示対象となる React のコンポーネントです。未定義の場合は `undefined` となります。
    */
-  readonly children: readonly Route[];
+  readonly component: React.ComponentType<{}> | undefined;
 };