soseki 0.0.1

package/src/hooks/use-submit.ts

@@ -0,0 +1,111 @@
+import * as React from "react";
+import type { ReadonlyFormData } from "../core/readonly-form-data.types.js";
+import type { ReadonlyURLSearchParams } from "../core/readonly-url.types.js";
+import type { IAction } from "../core/route.types.js";
+import useRouteContext from "./_use-route-context.js";
+import useRouterContext from "./_use-router-context.js";
+
+/**
+ * GET メソッドによる送信時のオプションです。
+ */
+export type SubmitGetOptions = {
+  /**
+   * 送信先のパスです。
+   */
+  readonly action?: string | undefined;
+
+  /**
+   * 現在の履歴エントリーを置き換えるかどうかを指定します。
+   */
+  readonly replace?: boolean | undefined;
+};
+
+/**
+ * POST メソッドによる送信時のオプションです。
+ */
+export type SubmitPostOptions = {
+  /**
+   * 送信先のパスです。
+   */
+  readonly action?: string | undefined;
+
+  /**
+   * 実行するアクションの定義です。
+   */
+  readonly actionId?: IAction | undefined;
+};
+
+/**
+ * 送信処理に使用するオプションの連合型です。
+ */
+export type SubmitOptions = SubmitGetOptions | SubmitPostOptions;
+
+/**
+ * データを送信するための関数インターフェースです。
+ */
+export interface ISubmit {
+  /**
+   * フォーム データを送信します。
+   *
+   * @param target 送信対象のフォームデータです。
+   * @param options 送信時のオプションです。
+   */
+  (target: ReadonlyFormData, options?: SubmitPostOptions | undefined): void;
+
+  /**
+   * URL クエリー パラメーターを送信します。
+   *
+   * @param target 送信対象の URL クエリーパラメーターです。
+   * @param options 送信時のオプションです。
+   */
+  (target: ReadonlyURLSearchParams, options?: SubmitGetOptions | undefined): void;
+
+  /**
+   * フォーム データまたは URL クエリーパラメーターを送信します。
+   *
+   * @param target 送信対象のデータです。
+   * @param options 送信時のオプションです。
+   */
+  (target: ReadonlyURLSearchParams | ReadonlyFormData, options?: SubmitOptions | undefined): void;
+}
+
+/**
+ * 命令的にデータを送信するための submit 関数を提供するフックです。
+ *
+ * @returns データを送信するための ISubmit 関数を返します。
+ */
+export default function useSubmit(): ISubmit {
+  const { urlPath } = useRouteContext();
+  const call = useRouterContext(router => router.submit);
+  return React.useCallback(
+    function submit(target, options = {}) {
+      if (target instanceof FormData) {
+        const {
+          action = urlPath,
+          actionId,
+        } = options as SubmitPostOptions;
+        return call({
+          target,
+          action,
+          actionId,
+        });
+      } else {
+        const {
+          action = urlPath,
+          replace,
+        } = options as SubmitGetOptions;
+        return call({
+          target: target as URLSearchParams,
+          action,
+          history: replace
+            ? "replace"
+            : "push",
+        });
+      }
+    },
+    [
+      call,
+      urlPath,
+    ],
+  );
+}

package/src/soseki.ts

@@ -0,0 +1,75 @@
+export type * from "./components/action-id.jsx";
+export { default as ActionId } from "./components/action-id.jsx";
+
+export type * from "./components/browser-router.jsx";
+export { default as BrowserRouter } from "./components/browser-router.jsx";
+
+export type * from "./components/hidden-input.jsx";
+export { default as HiddenInput } from "./components/hidden-input.jsx";
+
+export type * from "./components/outlet.jsx";
+export { default as Outlet } from "./components/outlet.jsx";
+
+export type * from "./core/deferred-promise.js";
+export { default as DeferredPromise } from "./core/deferred-promise.js";
+
+export type { ErrorMeta, ErrorOptions, ISosekiErrorConstructor, Issue } from "./core/errors.js";
+export {
+  ActionConditionError,
+  ActionExecutionError,
+  ErrorBase,
+  LoaderConditionError,
+  MultipleRedirectError,
+  NavigationApiNotSupportedError,
+  RouteContextMissingError,
+  RouterContextMissingError,
+  setErrorMessage,
+  UnexpectedValidationError,
+  UnreachableError,
+  ValidationErrorBase,
+} from "./core/errors.js";
+
+export type * from "./core/readonly-form-data.types.js";
+
+export type * from "./core/readonly-url.types.js";
+
+export type * from "./core/route-request.js";
+export { default as RouteRequest } from "./core/route-request.js";
+
+export type * from "./core/route.types.js";
+
+export type * from "./hooks/use-action-data.js";
+export { default as useActionData } from "./hooks/use-action-data.js";
+
+export type * from "./hooks/use-loader-data.js";
+export { default as useLoaderData } from "./hooks/use-loader-data.js";
+
+export type * from "./hooks/use-navigate.js";
+export { default as useNavigate } from "./hooks/use-navigate.js";
+
+export type * from "./hooks/use-params.js";
+export { default as useParams } from "./hooks/use-params.js";
+
+export type * from "./hooks/use-pathname.js";
+export { default as usePathname } from "./hooks/use-pathname.js";
+
+export type * from "./hooks/use-submit.js";
+export { default as useSubmit } from "./hooks/use-submit.js";
+
+export type * from "./utils/get-action-id.js";
+export { default as getActionId } from "./utils/get-action-id.js";
+
+export type * from "./utils/href.js";
+export { default as href } from "./utils/href.js";
+
+export type * from "./utils/redirect.js";
+export { default as redirect } from "./utils/redirect.js";
+
+export type * from "./utils/route-index.js";
+export { default as index } from "./utils/route-index.js";
+
+export type * from "./utils/route-route.js";
+export { default as route } from "./utils/route-route.js";
+
+export type * from "./utils/set-action-id.js";
+export { default as setActionId } from "./utils/set-action-id.js";

package/src/utils/get-action-id.ts

@@ -0,0 +1,12 @@
+import { ACTION_ID_FORM_DATA_NAME } from "../core/constants.js";
+
+/**
+ * フォームデータからアクション ID を取得します。
+ *
+ * @param formData 取得対象のフォームデータです。
+ * @returns 取得したアクション ID を返します。文字列でない場合や存在しない場合は null を返します。
+ */
+export default function getActionId(formData: FormData): string | null {
+  const id = formData.get(ACTION_ID_FORM_DATA_NAME);
+  return typeof id === "string" ? id : null;
+}

package/src/utils/href.ts

@@ -0,0 +1,17 @@
+import { inject, type RouteParams } from "regexparam";
+import type { PathParams } from "../core/route.types.js";
+
+/**
+ * 指定されたパスのテンプレートにパラメーターを注入し、完全な URL パスを生成します。
+ *
+ * @template TPath パスのテンプレート文字列の型です。
+ * @param path パスのテンプレート文字列です（例: `/users/:id`）。
+ * @param params パスに注入するパラメーターのオブジェクトです。
+ * @returns パラメーターが注入された後の文字列を返します。
+ */
+export default function href<const TPath extends string>(
+  path: TPath,
+  params: PathParams<TPath>,
+): string {
+  return inject(path, params as RouteParams<TPath>);
+}

package/src/utils/redirect.ts

@@ -0,0 +1,13 @@
+import RedirectResponse from "../core/redirect-response.js";
+
+/**
+ * 指定されたパスネームへのリダイレクトを表すレスポンスオブジェクトを生成します。
+ *
+ * アクションの中で、別のページへ遷移させるために使用されます。
+ *
+ * @param pathname リダイレクト先のパスネームです。
+ * @returns 生成された `RedirectResponse` オブジェクトを返します。
+ */
+export default function redirect(pathname: string): RedirectResponse {
+  return new RedirectResponse(pathname);
+}

package/src/utils/route-index.ts

@@ -0,0 +1,70 @@
+import type { DataFunctionObject, RouteDefinition } from "../core/route.types.js";
+import route, { type RouteEntryModule, type RouteModule } from "./route-route.js";
+
+/**
+ * インデックスルートの定義を構成するモジュールの型定義です。
+ *
+ * @template TPath ルートのパス（パスパターン）の型です。
+ */
+export type IndexRouteModule<TPath extends string = string> = RouteModule<TPath>;
+
+/**
+ * インデックスルートの起点となるエントリーモジュールの型定義です。
+ *
+ * @template TPath ルートのパス（パスパターン）の型です。
+ */
+export type IndexRouteEntryModule<TPath extends string = string> = RouteEntryModule<TPath>;
+
+/**
+ * 複数のモジュール配列からインデックスルート定義を生成するオーバーロードです。
+ *
+ * @template TPath ルートのパスの型です。
+ * @param mods エントリーモジュールと追加のデータ操作関数の配列です。
+ * @returns 構成されたインデックスルート定義オブジェクトを返します。
+ */
+function index<const TPath extends string = string>(
+  mods: readonly [entry: IndexRouteEntryModule<TPath>, ...ui: DataFunctionObject<TPath>[]],
+): RouteDefinition<TPath>;
+
+/**
+ * 単一のルートモジュールからインデックスルート定義を生成するオーバーロードです。
+ *
+ * @template TPath ルートのパスの型です。
+ * @param mod ルートモジュールオブジェクトです。
+ * @returns 構成されたインデックスルート定義オブジェクトを返します。
+ */
+function index<const TPath extends string = string>(
+  mod: IndexRouteModule<TPath>,
+): RouteDefinition<TPath>;
+
+/**
+ * インデックスルートモジュールまたはモジュール配列を受け取り、インデックスルート定義を生成します。
+ *
+ * @template TPath ルートのパスの型です。
+ * @param modOrMods ルートモジュールまたはエントリーモジュールを含む配列です。
+ * @param children 子ルートの配列です（インデックスルートでは通常使用されません）。
+ * @returns 構成されたインデックスルート定義オブジェクトを返します。
+ */
+function index<const TPath extends string = string>(
+  modOrMods:
+    | IndexRouteModule<TPath>
+    | readonly [entry: IndexRouteEntryModule<TPath>, ...ui: DataFunctionObject<TPath>[]],
+  children: readonly RouteDefinition[],
+): RouteDefinition<TPath>;
+
+/**
+ * インデックスルート定義を構築する関数の実体です。
+ * `route` 関数を利用して定義を生成し、`children` を明示的に `undefined` に設定します。
+ */
+function index(
+  arg0:
+    | IndexRouteModule
+    | readonly [entry: IndexRouteEntryModule, ...ui: DataFunctionObject[]],
+): RouteDefinition {
+  // route 関数でベースとなる定義を生成した後、子ルートを持たないように上書きします。
+  return Object.assign(route(arg0, []), {
+    children: undefined,
+  });
+}
+
+export default index;

package/src/utils/route-route.ts

@@ -0,0 +1,111 @@
+import type { DataFunctionObject, RouteDefinition } from "../core/route.types.js";
+
+/**
+ * ルートの定義を構成するモジュールの型定義です。
+ *
+ * @template TPath ルートのパス（パスパターン）の型です。
+ */
+export type RouteModule<TPath extends string = string> = DataFunctionObject<TPath> & {
+  /**
+   * ルートのパス（パスパターン）です。
+   */
+  readonly path: TPath;
+
+  /**
+   * このルートで描画される React コンポーネントです。
+   */
+  readonly default?: React.ComponentType<{}> | undefined;
+};
+
+/**
+ * ルートの起点となるエントリーモジュールの型定義です。
+ *
+ * データ操作関数の定義を直接含みます。
+ *
+ * @template TPath ルートのパス（パスパターン）の型です。
+ */
+export type RouteEntryModule<TPath extends string = string> = DataFunctionObject<TPath> & {
+  /**
+   * ルートのパス（パスパターン）です。
+   */
+  readonly path: TPath;
+
+  /**
+   * このルートで描画される React コンポーネントです。
+   */
+  readonly default?: React.ComponentType<{}> | undefined;
+};
+
+/**
+ * 複数のモジュール配列からルート定義を生成するオーバーロードです。
+ *
+ * @template TPath ルートのパスの型です。
+ * @param mods エントリーモジュールと追加のデータ操作関数の配列です。
+ * @param children 子ルートの配列です。
+ * @returns 構成されたルート定義オブジェクトを返します。
+ */
+function route<const TPath extends string = string>(
+  mods: readonly [entry: RouteEntryModule<TPath>, ...ui: DataFunctionObject<TPath>[]],
+  children: readonly RouteDefinition[],
+): RouteDefinition<TPath>;
+
+/**
+ * 単一のルートモジュールからルート定義を生成するオーバーロードです。
+ *
+ * @template TPath ルートのパスの型です。
+ * @param mod ルートモジュールオブジェクトです。
+ * @param children 子ルートの配列です。
+ * @returns 構成されたルート定義オブジェクトを返します。
+ */
+function route<const TPath extends string = string>(
+  mod: RouteModule<TPath>,
+  children: readonly RouteDefinition[],
+): RouteDefinition<TPath>;
+
+/**
+ * ルートモジュールまたはモジュール配列を受け取り、ルート定義を生成します。
+ *
+ * @template TPath ルートのパスの型です。
+ * @param modOrMods ルートモジュールまたはエントリーモジュールを含む配列です。
+ * @param children 子ルートの配列です。
+ * @returns 構成されたルート定義オブジェクトを返します。
+ */
+function route<const TPath extends string = string>(
+  modOrMods:
+    | RouteModule<TPath>
+    | readonly [entry: RouteEntryModule<TPath>, ...ui: DataFunctionObject<TPath>[]],
+  children: readonly RouteDefinition[],
+): RouteDefinition<TPath>;
+
+/**
+ * ルート定義を構築する関数の実体です。
+ */
+function route(
+  modOrMods:
+    | RouteModule
+    | readonly [entry: RouteEntryModule, ...ui: DataFunctionObject[]],
+  children: readonly RouteDefinition[],
+): RouteDefinition {
+  // 配列形式で渡された場合の処理です。
+  if (Array.isArray(modOrMods)) {
+    const mods = modOrMods;
+    const [entry, ...ui] = mods;
+    return {
+      path: entry.path,
+      children,
+      component: entry.default,
+      dataFunctions: [entry, ...ui],
+    };
+  }
+
+  // オブジェクト形式で渡された場合の処理です。
+  const mod = modOrMods;
+  return {
+    path: mod.path,
+    children,
+    component: mod.default,
+    dataFunctions: [mod],
+  };
+}
+
+export default route;

package/src/utils/set-action-id.ts

@@ -0,0 +1,14 @@
+import actionIdRegistry from "../core/_action-id-registry.js";
+import { ACTION_ID_FORM_DATA_NAME } from "../core/constants.js";
+import type { IAction } from "../core/route.types.js";
+
+/**
+ * フォームデータに対してアクション ID を発行し、設定します。
+ *
+ * @param formData アクション ID を設定する対象のフォームデータです。
+ * @param action アクション関数です。
+ */
+export default function setActionId(formData: FormData, action: IAction): void {
+  const id = actionIdRegistry.set(action);
+  formData.set(ACTION_ID_FORM_DATA_NAME, id);
+}

package/tests/core/_capture-stack-trace.test.ts

@@ -0,0 +1,46 @@
+import { test, vi } from "vitest";
+import captureStackTrace from "../../src/core/_capture-stack-trace.js";
+
+test("Error.captureStackTrace が定義されている環境で実行したとき、対象のオブジェクトにスタックトレースが設定される", ({ expect }) => {
+  // Arrange
+  const targetObject = {};
+  const constructorOpt = () => {};
+  // @ts-expect-error グローバルの型系義に captureStackTrace メソッドがない
+  const mockCapture = vi.spyOn(Error, "captureStackTrace");
+
+  try {
+    // Act
+    captureStackTrace(targetObject, constructorOpt);
+
+    // Assert
+    expect(mockCapture).toHaveBeenCalledWith(targetObject, constructorOpt);
+  } finally {
+    mockCapture.mockRestore();
+  }
+});
+
+test("Error.captureStackTrace が未定義の環境で実行したとき、エラーを投げずに正常終了する", ({ expect }) => {
+  // Arrange
+  const targetObject = {};
+  const constructorOpt = () => {};
+
+  // Error.captureStackTrace を一時的に削除して、非サポート環境をシミュレートする
+  // @ts-expect-error グローバルの型系義に captureStackTrace メソッドがない
+  const originalCaptureStackTrace = Error.captureStackTrace;
+  // @ts-expect-error: テストのためにプロパティを削除する
+  delete Error.captureStackTrace;
+
+  try {
+    // Act & Assert
+    // 例外が発生せず、undefined が返る（void 関数の正常終了）ことを確認する
+    expect(() => {
+      captureStackTrace(targetObject, constructorOpt);
+    })
+      .not
+      .toThrow();
+  } finally {
+    // 環境を元に戻す
+    // @ts-expect-error グローバルの型系義に captureStackTrace メソッドがない
+    Error.captureStackTrace = originalCaptureStackTrace;
+  }
+});

package/tests/core/_compare-route-paths.test.ts

@@ -0,0 +1,134 @@
+import { describe, test } from "vitest";
+import compareRoutePaths from "../../src/core/_compare-route-paths.js";
+
+describe("静的なパスと動的なパスの比較", () => {
+  test("静的なパスが、パラメーターを含むパスより優先されるとき、戻り値が負数になる", ({ expect }) => {
+    // Arrange
+    const staticPath = "/books/horror";
+    const paramPath = "/books/:genre";
+
+    // Act
+    const result = compareRoutePaths(staticPath, paramPath);
+
+    // Assert
+    expect(result).toBeLessThan(0);
+  });
+
+  test("パラメーターを含むパスが、ワイルドカードを含むパスより優先されるとき、戻り値が負数になる", ({ expect }) => {
+    // Arrange
+    const paramPath = "/books/:genre";
+    const wildcardPath = "/*";
+
+    // Act
+    const result = compareRoutePaths(paramPath, wildcardPath);
+
+    // Assert
+    expect(result).toBeLessThan(0);
+  });
+});
+
+describe("パラメーターの具体性による比較", () => {
+  test("必須パラメーターが、任意パラメーターより優先されるとき、戻り値が負数になる", ({ expect }) => {
+    // Arrange
+    const requiredParam = "/books/:genre";
+    const optionalParam = "/books/:genre?";
+
+    // Act
+    const result = compareRoutePaths(requiredParam, optionalParam);
+
+    // Assert
+    expect(result).toBeLessThan(0);
+  });
+
+  test("任意パラメーターが、ワイルドカードより優先されるとき、戻り値が負数になる", ({ expect }) => {
+    // Arrange
+    const optionalParam = "/users/:id?";
+    const wildcard = "/users/*";
+
+    // Act
+    const result = compareRoutePaths(optionalParam, wildcard);
+
+    // Assert
+    expect(result).toBeLessThan(0);
+  });
+});
+
+describe("パスの深さによる比較", () => {
+  test("より深い階層を持つ静的パスが、浅い静的パスより優先されるとき、戻り値が負数になる", ({ expect }) => {
+    // Arrange
+    const deepPath = "/books/horror/goosebumps";
+    const shallowPath = "/books/horror";
+
+    // Act
+    const result = compareRoutePaths(deepPath, shallowPath);
+
+    // Assert
+    expect(result).toBeLessThan(0);
+  });
+
+  test("同じ深さでスコアが等しいとき、文字列の辞書順で比較される", ({ expect }) => {
+    // Arrange
+    const pathA = "/books/apple";
+    const pathB = "/books/banana";
+
+    // Act
+    const result = compareRoutePaths(pathA, pathB);
+
+    // Assert
+    // 'apple' は 'banana' より辞書順で前のため、負数を期待する
+    expect(result).toBeLessThan(0);
+  });
+});
+
+describe("複雑なルート群のソート結果の検証", () => {
+  test("複数のルートをソートしたとき、仕様で定義された優先順位に従って並ぶ", ({ expect }) => {
+    // Arrange
+    const routes = [
+      "/*",
+      "/books/:genre",
+      "/books/horror",
+      "/books/:genre/:title?",
+      "/users/*?",
+      "/books/horror/goosebumps",
+    ];
+
+    // Act
+    const sorted = [...routes].sort(compareRoutePaths);
+
+    // Assert
+    const expected = [
+      "/books/horror/goosebumps", // 最も深い静的パス
+      "/books/horror", // 静的パス
+      "/books/:genre/:title?", // 深いパラメーター
+      "/books/:genre", // パラメーター
+      "/users/*?", // 任意ワイルドカード
+      "/*", // 必須ワイルドカード
+    ];
+    expect(sorted).toStrictEqual(expected);
+  });
+});
+
+describe("エッジケース", () => {
+  test("全く同じパスを比較したとき、0 を返す", ({ expect }) => {
+    // Arrange
+    const path = "/books/:genre";
+
+    // Act
+    const result = compareRoutePaths(path, path);
+
+    // Assert
+    expect(result).toBe(0);
+  });
+
+  test("末尾のスラッシュの有無に関わらず、セグメントの内容が同じであれば同一とみなす", ({ expect }) => {
+    // Arrange
+    const pathA = "/books/horror";
+    const pathB = "/books/horror/";
+
+    // Act
+    const result = compareRoutePaths(pathA, pathB);
+
+    // Assert
+    expect(result).toBe(0);
+  });
+});

package/tests/core/_encode-pathname.test.ts

@@ -0,0 +1,77 @@
+import { describe, test } from "vitest";
+import encodePathname from "../../src/core/_encode-pathname.js";
+
+describe("パスの正規化に関する振る舞い", () => {
+  test("スラッシュから始まるパス名を渡したとき、そのままの形で返る", ({ expect }) => {
+    // Arrange
+    const pathname = "/foo/bar";
+
+    // Act
+    const result = encodePathname(pathname);
+
+    // Assert
+    expect(result).toBe("/foo/bar");
+  });
+
+  test("スラッシュから始まらないパス名を渡したとき、先頭にスラッシュが付与される", ({ expect }) => {
+    // Arrange
+    const pathname = "foo/bar";
+
+    // Act
+    const result = encodePathname(pathname);
+
+    // Assert
+    expect(result).toBe("/foo/bar");
+  });
+
+  test("連続したスラッシュが含まれる場合、それらは 1 にまとめられる", ({ expect }) => {
+    // Arrange
+    const input = "///assets//images///logo.png";
+
+    // Act
+    const result = encodePathname(input);
+
+    // Assert
+    expect(result).toBe("/assets/images/logo.png");
+  });
+});
+
+describe("URL エンコードに関する振る舞い", () => {
+  test("日本語の文字列が含まれる場合、パーセントエンコーディングされたパスが返る", ({ expect }) => {
+    // Arrange
+    const input = "/ディレクトリ/ファイル.txt";
+
+    // Act
+    const result = encodePathname(input);
+
+    // Assert
+    expect(result).toBe(
+      "/%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA/%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt",
+    );
+  });
+
+  test("特殊文字やスペースが含まれる場合、適切にエンコードされたパスが返る", ({ expect }) => {
+    // Arrange
+    const input = "/path with spaces/test?query";
+
+    // Act
+    const result = encodePathname(input);
+
+    // Assert
+    // URL オブジェクトの仕様に基づき、 '?' 以降は query と見なされ pathname からは除外される振る舞いを検証
+    expect(result).toBe("/path%20with%20spaces/test");
+  });
+
+  test("一部が既にエンコードされている場合、未エンコードの箇所のみがエンコードされ、二重エンコードにならない", ({ expect }) => {
+    // Arrange
+    // "テスト" はエンコード済み（ %E3%83%86%E3%82%B9%E3%83%88 ）、 "データ" は未エンコード
+    const input = "/%E3%83%86%E3%82%B9%E3%83%88/データ.txt";
+
+    // Act
+    const result = encodePathname(input);
+
+    // Assert
+    // 既にエンコードされた部分は維持され、 "データ" のみがエンコードされることを確認
+    expect(result).toBe("/%E3%83%86%E3%82%B9%E3%83%88/%E3%83%87%E3%83%BC%E3%82%BF.txt");
+  });
+});