soseki 0.0.4 → 0.0.6

package/dist/src/core/route-request.d.ts

@@ -0,0 +1,149 @@
+import type { ReadonlyFormData } from "./readonly-form-data.types.js";
+import type { ReadonlyURL } from "./readonly-url.types.js";
+/**
+ * HTTP の GET メソッドによるルーティングリクエストを表すインターフェースです。
+ *
+ * GET リクエストの特性上、`formData` は常に `null` となります。
+ */
+interface RouteGetRequest {
+    /**
+     * HTTP メソッドを表します。常に `"GET"` です。
+     */
+    readonly method: "GET";
+    /**
+     * リクエスト対象の読み取り専用 URL オブジェクトです。
+     */
+    readonly url: ReadonlyURL;
+    /**
+     * 非同期処理やフェッチを中断するための中断シグナルです。
+     */
+    readonly signal: AbortSignal;
+    /**
+     * フォームデータです。GET リクエストではデータを本文に含めないため、常に `null` です。
+     */
+    readonly formData: null;
+    /**
+     * Web 標準の `Request` オブジェクトに変換します。
+     *
+     * @param init 変換時に上書きまたは追加するリクエストの設定オプションです。
+     * @returns 構築された `Request` インスタンスを返します。
+     */
+    toRequest(init?: RequestInit): Request;
+}
+/**
+ * HTTP の POST メソッドによるルーティングリクエストを表すインターフェースです。
+ *
+ * POST リクエストに伴う読み取り専用の `formData` を保持します。
+ */
+interface RoutePostRequest {
+    /**
+     * HTTP メソッドを表します。常に `"POST"` です。
+     */
+    readonly method: "POST";
+    /**
+     * リクエスト対象の読み取り専用 URL オブジェクトです。
+     */
+    readonly url: ReadonlyURL;
+    /**
+     * 非同期処理やフェッチを中断するための中断シグナルです。
+     */
+    readonly signal: AbortSignal;
+    /**
+     * リクエスト本文に紐付けられた、読み取り専用のフォームデータです。
+     */
+    readonly formData: ReadonlyFormData;
+    /**
+     * Web 標準の `Request` オブジェクトに変換します。
+     *
+     * @param init 変換時に上書きまたは追加するリクエストの設定オプションです。
+     * @returns 構築された `Request` インスタンスを返します。
+     */
+    toRequest(init?: RequestInit): Request;
+}
+/**
+ * GET または POST のルーティングリクエストを表す識別子付きユニオン型です。
+ */
+type RouteRequest = RouteGetRequest | RoutePostRequest;
+/**
+ * ルーティングコンテキストにおける HTTP リクエストを抽象化し、管理するクラスです。
+ *
+ * メソッドの種類（GET / POST）に応じて、型安全なリクエストの生成と Web 標準の `Request` オブジェクトへの変換を提供します。
+ */
+declare const RouteRequest: {
+    new (method: "GET", url: ReadonlyURL, signal: AbortSignal): {
+        /**
+         * 読み取り専用の URL オブジェクトです。
+         */
+        readonly url: ReadonlyURL;
+        /**
+         * 使用される HTTP メソッドです。
+         */
+        readonly method: "GET" | "POST";
+        /**
+         * 処理中断用の中断シグナルです。
+         */
+        readonly signal: AbortSignal;
+        /**
+         * 保持されている読み取り専用のフォームデータです。GET リクエストの場合は `null` となります。
+         */
+        readonly formData: ReadonlyFormData | null;
+        /**
+         * インスタンスが保持する情報を基に、Web 標準である Fetch API の `Request` オブジェクトを構築して返します。
+         *
+         * 外部から任意の `RequestInit` オプションが指定された場合は、インスタンス固有の既定値を上書きします。
+         *
+         * @param init リクエストの生成オプションを上書きするための初期化オブジェクトです。既定値は空のオブジェクトです。
+         * @returns Fetch API でそのまま利用可能な `Request` インスタンスです。
+         */
+        toRequest(init?: RequestInit): Request;
+    };
+    new (method: "POST", url: ReadonlyURL, signal: AbortSignal, formData: ReadonlyFormData): {
+        /**
+         * 読み取り専用の URL オブジェクトです。
+         */
+        readonly url: ReadonlyURL;
+        /**
+         * 使用される HTTP メソッドです。
+         */
+        readonly method: "GET" | "POST";
+        /**
+         * 処理中断用の中断シグナルです。
+         */
+        readonly signal: AbortSignal;
+        /**
+         * 保持されている読み取り専用のフォームデータです。GET リクエストの場合は `null` となります。
+         */
+        readonly formData: ReadonlyFormData | null;
+        /**
+         * インスタンスが保持する情報を基に、Web 標準である Fetch API の `Request` オブジェクトを構築して返します。
+         *
+         * 外部から任意の `RequestInit` オプションが指定された場合は、インスタンス固有の既定値を上書きします。
+         *
+         * @param init リクエストの生成オプションを上書きするための初期化オブジェクトです。既定値は空のオブジェクトです。
+         * @returns Fetch API でそのまま利用可能な `Request` インスタンスです。
+         */
+        toRequest(init?: RequestInit): Request;
+    };
+    /**
+     * GET メソッド用の `RouteGetRequest` インスタンスを生成するファクトリーメソッドです。
+     *
+     * @param method HTTP メソッド名（"GET"）です。
+     * @param url 読み取り専用の URL オブジェクトです。
+     * @param signal 処理中断用の中断シグナルです。
+     * @returns `RouteGetRequest` インターフェースを満たすインスタンスを返します。
+     */
+    "new"(method: "GET", url: ReadonlyURL, signal: AbortSignal): RouteGetRequest;
+    /**
+     * POST メソッド用の `RoutePostRequest` インスタンスを生成するファクトリーメソッドです。
+     *
+     * @param method HTTP メソッド名（"POST"）です。
+     * @param url 読み取り専用の URL オブジェクトです。
+     * @param signal 処理中断用の中断シグナルです。
+     * @param formData 読み取り専用のフォームデータです。
+     * @returns `RoutePostRequest` インターフェースを満たすインスタンスを返します。
+     */
+    "new"(method: "POST", url: ReadonlyURL, signal: AbortSignal, formData: ReadonlyFormData): RoutePostRequest;
+};
+export type { RouteGetRequest, RoutePostRequest };
+export default RouteRequest;
+//# sourceMappingURL=route-request.d.ts.map

package/dist/src/core/route-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-request.d.ts","sourceRoot":"","sources":["../../../src/core/route-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,UAAU,eAAe;IACvB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;CACxC;AAED;;;;GAIG;AACH,UAAU,gBAAgB;IACxB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAEpC;;;;;OAKG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;CACxC;AAED;;GAEG;AACH,KAAK,YAAY,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAWvD;;;;GAIG;AACH,QAAA,MAAM,YAAY;iBAsDW,KAAK,OAAO,WAAW,UAAU,WAAW;QAvBvE;;WAEG;sBACkB,WAAW;QAEhC;;WAEG;yBACqB,KAAK,GAAG,MAAM;QAEtC;;WAEG;yBACqB,WAAW;QAEnC;;WAEG;2BACuB,gBAAgB,GAAG,IAAI;QAkCjD;;;;;;;WAOG;yBACoB,WAAW,GAAQ,OAAO;;iBA/BvC,MAAM,OACT,WAAW,UACR,WAAW,YACT,gBAAgB;QAhC5B;;WAEG;sBACkB,WAAW;QAEhC;;WAEG;yBACqB,KAAK,GAAG,MAAM;QAEtC;;WAEG;yBACqB,WAAW;QAEnC;;WAEG;2BACuB,gBAAgB,GAAG,IAAI;QAkCjD;;;;;;;WAOG;yBACoB,WAAW,GAAQ,OAAO;;IA1FjD;;;;;;;OAOG;kBACuB,KAAK,OAAO,WAAW,UAAU,WAAW,GAAG,eAAe;IAExF;;;;;;;;OAQG;kBAEO,MAAM,OACT,WAAW,UACR,WAAW,YACT,gBAAgB,GACzB,gBAAgB;CAkFpB,CAAC;AAEF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC;AAElD,eAAe,YAAY,CAAC"}

package/dist/src/core/route-request.js

@@ -0,0 +1,41 @@
+/**
+ * ルーティングコンテキストにおける HTTP リクエストを抽象化し、管理するクラスです。
+ *
+ * メソッドの種類（GET / POST）に応じて、型安全なリクエストの生成と Web 標準の `Request` オブジェクトへの変換を提供します。
+ */
+const RouteRequest = class RouteRequest {
+    static new(...args) {
+        return new RouteRequest(...args);
+    }
+    /**
+     * `RouteRequest` コンストラクターの実装本体です。
+     *
+     * 渡された引数をそれぞれのプロパティーに代入して内部状態を初期化します。
+     */
+    constructor(method, url, signal, formData = null) {
+        this.url = url;
+        this.method = method;
+        this.signal = signal;
+        this.formData = formData;
+    }
+    /**
+     * インスタンスが保持する情報を基に、Web 標準である Fetch API の `Request` オブジェクトを構築して返します。
+     *
+     * 外部から任意の `RequestInit` オプションが指定された場合は、インスタンス固有の既定値を上書きします。
+     *
+     * @param init リクエストの生成オプションを上書きするための初期化オブジェクトです。既定値は空のオブジェクトです。
+     * @returns Fetch API でそのまま利用可能な `Request` インスタンスです。
+     */
+    toRequest(init = {}) {
+        const { 
+        // 内部の型定義の整合性を維持するため、読み取り専用のインターフェースである formData を、標準の Request の body に適合する FormData 型にキャストしています。
+        body = this.formData, method = this.method, signal = this.signal, ...other } = init;
+        return new Request(this.url.href, {
+            body,
+            method,
+            signal,
+            ...other,
+        });
+    }
+};
+export default RouteRequest;

package/dist/src/core/route.types.d.ts

@@ -0,0 +1,296 @@
+import type * as React from "react";
+import type { ReadonlyURL } from "./readonly-url.types.js";
+import type { RouteGetRequest, RoutePostRequest } from "./route-request.js";
+/**
+ * 個別のパスパラメーターを解析し、適切なプロパティーの型オブジェクトへと変換する内部ユーティリティー型です。
+ *
+ * パラメーターの末尾の形状を条件付き型により詳細に選別します。
+ *
+ * @template Param 解析対象となる単一のパラメーター文字列です。
+ */
+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;
+};
+/**
+ * パス文字列のセグメントから動的なパラメーターやワイルドカードを再帰的に抽出し、型安全なオブジェクト構造を構築するユーティリティー型です。
+ *
+ * 開発者が指定した文字列リテラル型の形状に基づいて、ルーティングに必要なパラメーターの型を静的に決定します。
+ *
+ * このユーティリティー型は、ライブラリー `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
+ */
+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;
+} : {};
+/**
+ * 文字列リテラルとして定義されたパスの形状から、含まれるパスパラメーターを解析し、静的に型付けされたオブジェクトとして抽出する型定義です。
+ *
+ * @template TRoutePath パラメーター抽出の対象となるパス文字列リテラル型です。
+ */
+export type RoutePathParams<TRoutePath extends string = string> = Readonly<RouteParams<TRoutePath>>;
+/**
+ * データ更新などのアクション処理を実行する際に、該当する関数へ渡される引数の型定義です。
+ *
+ * 解析済みのパスパラメーターと、HTTP の POST メソッドを抽象化したリクエストオブジェクトを含みます。
+ *
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ */
+export type ActionFunctionArgs<TRoutePath extends string = string> = {
+    /**
+     * 現在の URL パスから抽出されたパラメーターオブジェクトです。
+     */
+    params: RoutePathParams<TRoutePath>;
+    /**
+     * フォームデータなどを内包する、HTTP の POST メソッドに特化したルーティングリクエストオブジェクトです。
+     */
+    request: RoutePostRequest;
+};
+/**
+ * データの登録、更新、削除といった副作用を伴うアクション処理を定義するための関数インターフェースです。
+ *
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @template TData アクション関数が返す戻り値の型定義です。既定値は `unknown` です。
+ */
+export interface ActionFunction<TRoutePath extends string = string, TData = unknown> {
+    (args: ActionFunctionArgs<TRoutePath>): TData;
+}
+/**
+ * ページ遷移やデータ更新が発生した際、現在の画面データを再読み込みすべきかどうかを判定する関数へ渡される引数の型定義です。
+ *
+ * アクションを実行した契機となる HTTP メソッドの種類（GET / POST）に応じて、含まれるコンテキスト情報が分岐します。
+ *
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ */
+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 TRoutePath 対象となるルートのパス文字列リテラル型です。
+ * @returns データを再読み込みする場合は `true`、スキップする場合は `false` を返します。
+ */
+export interface ShouldReloadFunction<TRoutePath extends string = string> {
+    (args: ShouldReloadFunctionArgs<TRoutePath>): boolean;
+}
+/**
+ * 画面の描画に必要なデータを取得（ロード）する際に、該当する関数へ渡される引数の型定義です。
+ *
+ * 解析済みのパスパラメーターと、HTTP の GET メソッドを抽象化したリクエストオブジェクトを含みます。
+ *
+ * @template TRoutePath 対象となるルートのパス文字列リテラル型です。
+ */
+export type LoaderFunctionArgs<TRoutePath extends string = string> = {
+    /**
+     * 現在の URL パスから抽出されたパラメーターオブジェクトです。
+     */
+    params: RoutePathParams<TRoutePath>;
+    /**
+     * HTTP の GET メソッドに特化したルーティングリクエストオブジェクトです。
+     */
+    request: RouteGetRequest;
+};
+/**
+ * 画面の初期描画時や遷移時にデータをオンデマンドで取得するための関数インターフェースです。
+ *
+ * @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 パスのパターン文字列です。
+     */
+    readonly path: TPath;
+    /**
+     * 親ルートのパスにおいて、インデックスルートとして機能させるかどうかのフラグです。
+     */
+    readonly index?: boolean | undefined;
+    /**
+     * このルートで実行されるデータ更新用のアクション関数です。
+     */
+    readonly action?: ActionFunction<TPath> | undefined;
+    /**
+     * このルートのデータ再読み込み動作を制御する判定関数です。
+     */
+    readonly shouldReload?: ShouldReloadFunction<TPath> | undefined;
+    /**
+     * このルートの画面描画に必要なデータを取得する関数です。
+     */
+    readonly loader?: LoaderFunction<TPath> | undefined;
+    /**
+     * このルートに対応して描画される React のコンポーネントです。
+     */
+    readonly component?: React.ComponentType<{}> | undefined;
+};
+/**
+ * ルーティング設定をインポート経由で定義するための構造体型定義です。
+ *
+ * @template TPath ルートに関連付けるパス文字列リテラル型です。
+ */
+export type RouteDefinitionModule<TPath extends string = string> = {
+    /**
+     * マッチングの対象となる URL パスのパターン文字列です。
+     */
+    readonly path: TPath;
+    /**
+     * 親ルートのパスにおいて、インデックスルートとして機能させるかどうかのフラグです。
+     */
+    readonly index?: boolean | undefined;
+    /**
+     * このルートで実行されるデータ更新用のアクション関数です。
+     */
+    readonly action?: ActionFunction<TPath> | undefined;
+    /**
+     * このルートのデータ再読み込み動作を制御する判定関数です。
+     */
+    readonly shouldReload?: ShouldReloadFunction<TPath> | undefined;
+    /**
+     * このルートの画面描画に必要なデータを取得する関数です。
+     */
+    readonly loader?: LoaderFunction<TPath> | undefined;
+    /**
+     * このルートに対応して描画される React のコンポーネントです。
+     *
+     * `default` プロパティーよりこちらが優先されます。
+     */
+    readonly component?: React.ComponentType<{}> | undefined;
+    /**
+     * ES モジュールのデフォルトエクスポートとして定義された、描画対象となる React のコンポーネントです。
+     *
+     * `component` プロパティーがない場合はこちらにフォールバックされます。
+     */
+    readonly default?: React.ComponentType<{}> | undefined;
+    /**
+     * オブジェクトの文字列表現をカスタマイズするための組み込みタグプロパティーです。
+     *
+     * モジュールオブジェクトとしての識別に使用します。
+     */
+    get [Symbol.toStringTag](): string;
+};
+/**
+ * アプリケーションのルーティング設定を定義するためのオブジェクトの型定義です。
+ *
+ * @template TPath ルートに関連付けるパス文字列リテラル型です。
+ */
+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 action: ActionFunction | undefined;
+    /**
+     * データの再読み込み動作を制御する確定的な判定関数です。定義がない場合はシステム既定の挙動を行う関数が割り当てられます。
+     */
+    readonly shouldReload: ShouldReloadFunction;
+    /**
+     * 画面描画に必要なデータを取得する関数です。未定義の場合は `undefined` となります。
+     */
+    readonly loader: LoaderFunction | undefined;
+    /**
+     * 表示対象となる React のコンポーネントです。未定義の場合は `undefined` となります。
+     */
+    readonly component: React.ComponentType<{}> | undefined;
+};
+export {};
+//# sourceMappingURL=route.types.d.ts.map

package/dist/src/core/route.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.types.d.ts","sourceRoot":"","sources":["../../../src/core/route.types.ts"],"names":[],"mappings":"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"}

package/dist/src/core/start-action.d.ts

@@ -0,0 +1,53 @@
+import { NinjaPromise } from "ninja-promise";
+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 type { ActionFunction } 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;
+//# sourceMappingURL=start-action.d.ts.map

package/dist/src/core/start-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-action.d.ts","sourceRoot":"","sources":["../../../src/core/start-action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAE5B;;OAEG;IACH,IAAI,EAAE,cAAc,CAAC;IAErB;;;;OAIG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC;QAClB,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAAC;KAC1C,CAAC,CAAC;CACJ;AAED;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,CACjC,MAAM,EAAE,SAAS,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC,EAAE,EACtE,OAAO,EAAE,kBAAkB,GAC1B,aAAa,GAAG,IAAI,CAmGtB"}

package/dist/src/core/start-action.js

@@ -0,0 +1,95 @@
+import { NinjaPromise } from "ninja-promise";
+import unreachable from "./_unreachable.js";
+import RedirectResponse from "./redirect-response.js";
+import RouteRequest from "./route-request.js";
+/**
+ * マッチしたルート配列から、アクションの送信先に近い親ルートのアクション関数を 1 つだけ選出して実行し、リダイレクトの傍受や応答データの型正規化などを行う、POST 処理の開始関数です。
+ *
+ * @param routes 現在の URL にマッチしたルート情報の配列です。
+ * @param request アクションを起動するための URL、フォームデータ、および中断シグナルを含むオブジェクトです。
+ * @returns 実行対象のアクション関数が検出された場合は `StartedAction` オブジェクトを返し、1つも定義されていなかった場合は `null` を返します。
+ */
+export default function startAction(routes, request) {
+    let action;
+    let params;
+    let urlPath;
+    for ({ action, params, urlPath } of routes) {
+        if (
+        // アクションを実行するために、関数が定義されている必要があります。
+        typeof action === "function" &&
+            // アクションの送信先に近い親ルートを選出します。
+            request.url.pathname.startsWith(urlPath)) {
+            break;
+        }
+    }
+    if (typeof action !== "function") {
+        return null;
+    }
+    let actionData;
+    let redirectTo;
+    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,
+            };
+        },
+    };
+}