soseki 0.0.5 → 0.0.7

package/src/core/expect-history-entry.ts

@@ -4,84 +4,83 @@ import HistoryEntryIdSchema, { type HistoryEntryId } from "./history-entry-id-sc
 import HistoryEntryUrlSchema, { type HistoryEntryUrl } from "./history-entry-url-schema.js";
 
 /**
- * 履歴エントリーのバリデーションスキーマを生成、または取得します。
+ * 履歴エントリーオブジェクト全体の構造を検証するためのスキーマを作成する関数です。
  *
- * 識別子、URL、および 0 以上の整数であるインデックスを持つオブジェクト構造を定義します。
- *
- * @returns 履歴エントリーのスキーマです。
+ * スキーマの構築処理は一度だけ実行され、以降はシングルトンインスタンスとしてキャッシュから再利用されます。
  */
-const HistoryEntrySchema = () => (singleton("HistoryEntrySchema", () => (
-  v.object({
-    id: HistoryEntryIdSchema(),
-    url: v.nullable(HistoryEntryUrlSchema()),
-    index: v.pipe(
-      v.number(),
-      v.safeInteger(),
-      v.minValue(0),
-    ),
-  })
-)));
+const HistoryEntrySchema = () =>
+  singleton("HistoryEntrySchema", () =>
+    v.object({
+      /**
+       * 履歴エントリーの識別子です。
+       */
+      id: HistoryEntryIdSchema(),
+
+      /**
+       * 履歴エントリーの絶対 URL です。
+       */
+      url: v.nullable(HistoryEntryUrlSchema()),
+
+      /**
+       * 履歴エントリーリスト内の履歴エントリーのインデックスです。
+       */
+      index: v.pipe(v.number(), v.safeInteger(), v.minValue(-1)),
+    }),
+  );
 
 /**
- * 履歴エントリーとして受け入れ可能な入力型の定義です。
+ * `HistoryEntrySchema` による検証と構造変換を行う前の、生の入力オブジェクトに対応する型定義です。
  */
-export type HistoryEntryLike = Readonly<v.InferInput<ReturnType<typeof HistoryEntrySchema>>>;
+export type HistoryEntryLike = v.InferInput<ReturnType<typeof HistoryEntrySchema>>;
 
 /**
- * バリデーション済みの履歴エントリーを表す型定義です。
+ * `expectHistoryEntry` 関数による検証を通過した、ランタイムで確定的に使用可能な履歴エントリーの型定義です。
  */
 export type HistoryEntry = {
   /**
-   * 履歴エントリーを一意に識別する ID です。
+   * 履歴エントリーの識別子です。
    */
   readonly id: HistoryEntryId;
 
   /**
-   * 正規化済みの URL オブジェクトです。
+   * 履歴エントリーの絶対 URL です。
    */
   readonly url: HistoryEntryUrl;
 
   /**
-   * 0 以上の整数で表される履歴のインデックスです。
+   * 履歴エントリーリスト内の履歴エントリーのインデックスです。
    */
   readonly index: number;
 };
 
 /**
- * 入力値が履歴エントリーの形式を満たしているか検証します。
+ * 履歴エントリーオブジェクトを検証し、仕様を満たしている場合に確定的な `HistoryEntry` 型へと変換します。
  *
- * @param entry 検証対象のオブジェクトです。
- * @returns バリデーション済み、かつ URL が存在する履歴エントリーです。
+ * @param entry スキーマの基本構造を満たしていると予想される生の入力値です。
+ * @returns すべてのプロパティーが完全に確定した `HistoryEntry` を返します。
  */
 function expectHistoryEntry(entry: HistoryEntryLike): HistoryEntry;
 
 /**
- * 入力値が履歴エントリーの形式を満たしているか検証します。
+ * 履歴エントリーオブジェクトを検証し、仕様を満たしている場合に確定的な `HistoryEntry` 型へと変換します。
  *
- * @param entry 検証対象のオブジェクト、または null 系値です。
- * @returns 検証に成功した場合は履歴エントリーを、入力が null もしくは URL が欠損している場合は null を返します。
+ * @param entry スキーマの入力形式を満たすオブジェクト、または空値です。
+ * @returns 入力値が空であった場合、あるいは検証の過程で必要なデータが欠落していた場合は `null` を返します。
  */
 function expectHistoryEntry(entry: HistoryEntryLike | null | undefined): HistoryEntry | null;
 
-/**
- * 入力値が履歴エントリーの形式を満たしているか検証します。
- *
- * @param entry 検証対象のデータです。
- * @returns 検証結果に基づく履歴エントリー、または null です。
- */
 function expectHistoryEntry(entry: HistoryEntryLike | null | undefined): HistoryEntry | null {
   if (entry == null) {
     return null;
   }
 
-  const {
-    id,
-    url,
-    index,
-  } = v.expect(HistoryEntrySchema(), entry);
-
-  // URL が nullable として定義されていますが、この関数では URL が存在することを必須とします。
-  if (!url) {
+  const { id, url, index } = v.expect(HistoryEntrySchema(), entry);
+  if (
+    // 特定の条件下で null に設定される場合があるので、そのときは null を返します。
+    !url ||
+    // 現在のドキュメントが完全にアクティブでない場合は -1 になってしまうので、そのときは null を返します。
+    index < 0
+  ) {
     return null;
   }
 

package/src/core/form-data-to-html-form-element.ts

@@ -0,0 +1,37 @@
+import type { ReadonlyFormData } from "./readonly-form-data.types.js";
+
+/**
+ * 読み取り専用のフォームデータを基に、プログラムによって仮想的な `HTMLFormElement` を動的に構築する関数です。
+ *
+ * 生成されたフォーム要素は画面上のレイアウトを崩さないよう非表示（`display: none`）に設定され、内包する各データは適切な `<input>` 要素にラップされてフォーム内に追加されます。
+ *
+ * @param formData 変換元となる読み取り専用のフォームデータです。
+ * @returns 子要素としてデータが詰め込まれた、DOM に未配置の非表示 `HTMLFormElement` を返します。
+ */
+export default function formDataToHTMLFormElement(formData: ReadonlyFormData): HTMLFormElement {
+  const form = document.createElement("form");
+
+  // 画面のレンダリングや視覚的なレイアウトに影響を及ぼさないよう、非表示スタイルを強制します。
+  form.style.display = "none";
+
+  formData.forEach((value, name) => {
+    const input = document.createElement("input");
+    if (value instanceof File) {
+      // DataTransfer オブジェクトを仲介役として利用し、FileList を安全に再構成します。
+      const df = new DataTransfer();
+      df.items.add(value);
+
+      input.type = "file";
+      input.name = name;
+      input.files = df.files;
+    } else {
+      input.type = "hidden";
+      input.name = name;
+      input.value = value;
+    }
+
+    form.appendChild(input);
+  });
+
+  return form;
+}

package/src/core/history-entry-id-schema.ts

@@ -2,25 +2,20 @@ import singleton from "./_singleton.js";
 import * as v from "./_valibot.js";
 
 /**
- * 履歴エントリー ID のバリデーションスキーマを作成、または取得します。
+ * 履歴エントリーの識別子を検証およびブランド化するためのスキーマを作成する関数です。
  *
- * @returns 履歴エントリー ID のスキーマです。
+ * スキーマの生成処理は一度だけ実行され、以降はシングルトンインスタンスとしてキャッシュから再利用されます。
  */
-const HistoryEntryIdSchema = () => (singleton("HistoryEntryIdSchema", () => (
-  v.pipe(
-    v.string(),
-    v.uuid(),
-    v.brand("HistoryEntryId"),
-  )
-)));
+const HistoryEntryIdSchema = () =>
+  singleton("HistoryEntryIdSchema", () => v.pipe(v.string(), v.uuid(), v.brand("HistoryEntryId")));
 
 /**
- * 履歴エントリー ID として受け入れ可能な入力型の定義です（バリデーション前の文字列など）。
+ * `HistoryEntryIdSchema` による検証を通過する前の、入力値に対応する型定義です。
  */
 export type HistoryEntryIdLike = v.InferInput<ReturnType<typeof HistoryEntryIdSchema>>;
 
 /**
- * バリデーション済みでブランド化された、履歴エントリー ID の出力型の定義です。
+ * `HistoryEntryIdSchema` による検証および解析が正常に完了した、安全な出力値の型定義です。
  */
 export type HistoryEntryId = v.InferOutput<ReturnType<typeof HistoryEntryIdSchema>>;
 

package/src/core/history-entry-url-schema.ts

@@ -1,34 +1,41 @@
 import singleton from "./_singleton.js";
 import * as v from "./_valibot.js";
 import type { ReadonlyURL } from "./readonly-url.types.js";
+import RoutePath from "./route-path.js";
 
 /**
- * 履歴エントリー URL のバリデーションおよび変換スキーマを作成、または取得します。
+ * 履歴エントリーで使用される URL 文字列を検証、正規化、およびブランド化するためのスキーマを作成する関数です。
  *
- * 文字列が有効な URL であるかを確認し、クエリーパラメーターをソートして正規化した `ReadonlyURL` オブジェクトを返します。
- *
- * @returns 履歴エントリー URL のスキーマです。
+ * スキーマの構築処理は一度だけ実行され、以降はシングルトンインスタンスとしてキャッシュから再利用されます。
  */
-const HistoryEntryUrlSchema = () => (singleton("HistoryEntryUrlSchema", () => (
-  v.pipe(
-    v.string(),
-    v.url(),
-    v.transform(function createNormalizedUrl(s): ReadonlyURL {
-      const u = new URL(s);
-      // 同一の URL として比較しやすくするため、クエリーパラメーターを昇順にソートします。
-      u.searchParams.sort();
-      return u;
-    }),
-  )
-)));
+const HistoryEntryUrlSchema = () =>
+  singleton("HistoryEntryUrlSchema", () =>
+    v.pipe(
+      v.string(),
+      v.url(),
+      // 検証を通過した URL 文字列を、読み取り専用の ReadonlyURL オブジェクトへと構造変換および正規化します。
+      v.transform(function toNormalizedReadonlyURL(s): ReadonlyURL {
+        const u = new URL(s);
+
+        // 正規化します。
+        const { hash, search, pathname } = new RoutePath(u);
+        u.hash = hash;
+        u.search = search;
+        u.pathname = pathname;
+
+        return u;
+      }),
+      v.brand("HistoryEntryUrl"),
+    ),
+  );
 
 /**
- * 履歴エントリー URL として受け入れ可能な入力型の定義です（バリデーション前の文字列など）。
+ * `HistoryEntryUrlSchema` による検証と変換を行う前の、入力値に対応する型定義です。
  */
 export type HistoryEntryUrlLike = v.InferInput<ReturnType<typeof HistoryEntryUrlSchema>>;
 
 /**
- * バリデーションおよび正規化が行われた後の、履歴エントリー URL の出力型の定義です。
+ * `HistoryEntryUrlSchema` による検証、並び替え、および変換が正常に完了した、安全な出力値の型定義です。
  */
 export type HistoryEntryUrl = v.InferOutput<ReturnType<typeof HistoryEntryUrlSchema>>;
 

package/src/core/init-loaders.ts

@@ -1,79 +1,57 @@
-import type { IDataMap } from "./data-map.types.js";
-import type { IDataStore } from "./data-store.types.js";
-import DeferredPromise from "./deferred-promise.js";
-import type { HistoryEntry } from "./expect-history-entry.js";
+import { NinjaPromise } from "ninja-promise";
+
+import type { HistoryEntryUrl } from "./history-entry-url-schema.js";
 import type { MatchedRoute } from "./match-routes.js";
 import RouteRequest from "./route-request.js";
-import type { ILoader } from "./route.types.js";
+import type { LoaderFunction } from "./route.types.js";
 
 /**
- * ローダーの初期化に使用するパラメーターの型定義です。
+ * 各ローダー関数を初期化する際に必要となるリクエスト情報の型定義です。
  */
-export type InitLoadersParams = {
-  /**
-   * マッチしたルート情報のリストです。パラメーターとデータ関数を含みます。
-   */
-  readonly routes: readonly Pick<MatchedRoute, "params" | "dataFuncs">[];
-
-  /**
-   * 履歴エントリーの情報です。 ID と URL を含みます。
-   */
-  readonly entry: Pick<HistoryEntry, "id" | "url">;
-
+export type LoaderInitRequest = {
   /**
-   * データを永続化するためのデータストアです。
+   * 読み込み対象となる現在の履歴エントリーの正規化済み URL オブジェクトです。
    */
-  readonly dataStore: IDataStore<ILoader>;
+  readonly url: HistoryEntryUrl;
 
   /**
-   * 非同期処理を中断するためのシグナルです。
+   * 進行中の非同期データ取得処理を外部から中断するための中断シグナルです。
    */
   readonly signal: AbortSignal;
 };
 
 /**
- * ルートに定義されたローダーを初期化し、実行します。
+ * マッチしたすべてのルートに紐づくデータ取得用のローダー関数を一斉に起動し、その実行コンテキストと遅延非同期状態を管理するためのマップを作成して返す関数です。
  *
- * 各ローダーの実行結果はデータストアに格納され、すべての実行開始を待機します。
+ * 階層的な並行データフェッチをサポートするために、各ローダーの実行結果を個別のプロミスとしてラップします。
  *
- * @param params ローダーの初期化に必要なパラメーターオブジェクトです。
- * @returns すべてのローダーの処理が開始（Settled）されるまで待機する Promise です。
+ * @param routes 現在の URL にマッチしたルート情報の配列です。各ルートから `loader` 関数と解析済みの `params` のみを抽出して利用します。
+ * @param request 各ローダー関数を初期化する際に必要となるリクエスト情報です。
+ * @returns 各ローダー関数をキーとし、その実行結果または進行状態を表す `NinjaPromise` を値としたマップです。
  */
-export default function initLoaders(params: InitLoadersParams): {
-  (): Promise<void>;
-} {
-  const {
-    entry,
-    routes,
-    signal,
-    dataStore,
-  } = params;
-  const dataMap: IDataMap<ILoader> = new Map();
-  const request = new RouteRequest("GET", entry.url, signal);
-  // 各ルートおよびそのデータ関数に含まれるローダーを走査します。
-  for (const route of routes) {
-    for (const { loader } of route.dataFuncs) {
-      if (!loader) {
-        continue;
-      }
+export default function initLoaders(
+  routes: readonly Pick<MatchedRoute, "loader" | "params">[],
+  request: LoaderInitRequest,
+): Map<LoaderFunction, NinjaPromise<unknown>> {
+  const dataMap = new Map<LoaderFunction, NinjaPromise<unknown>>();
+
+  // マッチしたすべてのローダーで共有可能なリクエストオブジェクトを 1 つだけ作成します。
+  // すべてのプロパティーが読み取り専用なので、ローダー間で共有できます。
+  const req = RouteRequest.new("GET", request.url, request.signal);
+
+  for (const { loader, params } of routes) {
+    if (typeof loader !== "function") {
+      continue;
+    }
 
-      // ローダーの実行を遅延評価としてラップします。
-      const data = DeferredPromise.try(function executeLoader() {
-        return loader({
-          params: route.params,
-          request,
-        });
+    const data = NinjaPromise.try(function executeLoader() {
+      return loader({
+        params,
+        request: req,
       });
-      // ローダーの結果を待機、エラーハンドリングする処理は、この結果を参照するコンポーネントに任せます。
-      dataMap.set(loader, data);
-    }
+    });
+    dataMap.set(loader, data);
   }
 
-  // 生成されたデータマップを履歴エントリーの ID に紐付けて保存します。
-  dataStore.set(entry.id, dataMap);
-
-  return async function waitForLoadersComplete() {
-    // すべてのローダーの Promise が確定するまで待機します。
-    await Promise.allSettled(dataMap.values());
-  };
+  return dataMap;
 }

package/src/core/match-routes.ts

@@ -1,90 +1,58 @@
 import { inject } from "regexparam";
+
 import matchRoutePath from "./_match-route-path.js";
-import type { PathParams, Route } from "./route.types.js";
+import type { ReadonlyURL } from "./readonly-url.types.js";
+import type { Route, RoutePathParams } from "./route.types.js";
 
 /**
- * マッチしたルートの情報に、抽出されたパスパラメーターを統合した型定義です。
+ * URL とのマッチングが確認されたルート情報を表す型定義です。
+ *
+ * 基本となる `Route` オブジェクトの構造を引き継ぎつつ、抽出された動的パラメーターと、それらを埋め戻して構築された具体的な URL パス文字列が追加されています。
  */
-export type MatchedRoute = Pick<Route, "path" | "index" | "dataFuncs" | "component"> & {
+export type MatchedRoute = Route & {
   /**
-   * パス名から抽出された動的なパラメーターのオブジェクトです。
+   * 現在の URL パスから抽出された、このルート固有の動的パスパラメーターです。
    */
-  readonly params: PathParams;
+  readonly params: RoutePathParams;
 
   /**
-   * ルートのパスパターンに基づく URL のパスです。
-   *
-   * @example
-   * ```ts
-   * const route = matchRoutes(routes, "/user/123/setting");
-   * route.path;     // "/user/:id"
-   * route.params;   // { id: "123" }
-   * route.urlPath;  // "/user/123"
-   * ```
+   * ルートの定義パターン（例: `/users/:id`）に抽出したパラメーター（例: `{ id: "42" }`）を流し込み、具現化されたリクエストパス（例: `/users/42`）です。
    */
   readonly urlPath: string;
 };
 
 /**
- * 単一のルートとその子ルートに対して、再帰的にパスマッチングを試みます。
+ * 事前に詳細度順でソートされたルート定義の配列から、指定された URL に適合するすべてのルートを探索・抽出し、マッチした順に正規化して返す関数です。
  *
- * @param route マッチングを確認する対象のルートオブジェクトです。
- * @param pathname マッチング対象のパス名です。
- * @returns マッチした場合は親から子への階層構造を保持した配列を返し、マッチしない場合は `null` を返します。
- */
-function matchRoute(
-  route: Route,
-  pathname: string,
-): readonly [MatchedRoute, ...MatchedRoute[]] | null {
-  const result = matchRoutePath(route, pathname);
-  if (!result) {
-    return null;
-  }
-
-  const matched: MatchedRoute = {
-    path: route.path,
-    index: route.index,
-    params: result.params,
-    urlPath: inject(route.path, result.params),
-    dataFuncs: route.dataFuncs,
-    component: route.component,
-  };
-
-  // インデックスルート（末端）の場合は、現在のルートを配列に含めて返します。
-  if (route.index) {
-    return [matched];
-  }
-
-  // 子ルートの中にマッチするものがあるか探索します。
-  for (const childRoute of route.children) {
-    const childMathced = matchRoute(childRoute, pathname);
-    if (childMathced) {
-      return [
-        ...childMathced,
-        matched,
-      ];
-    }
-  }
-
-  return [matched];
-}
-
-/**
- * ルート定義のリスト全体から、指定されたパス名にマッチするルートを探索します。
+ * ネストされた階層的なルーティング構造において、親ルートから子ルートまで、現在の URL に部分一致または完全一致するルートの連鎖を構成する目的で使用します。
  *
- * @param routes 探索対象となるルートオブジェクトの配列です。
- * @param pathname マッチング対象のパス名です。
- * @returns 最初にマッチしたルートとその階層構造を返し、どのルートにもマッチしない場合は `null` を返します。
+ * @param routes あらかじめ正規化およびソートが完了しているルートオブジェクトの読み取り専用配列です。
+ * @param url マッチングの判定元となる、読み取り専用の URL オブジェクトです。
+ * @returns マッチしたルートが 1 つ以上存在する場合は、最低 1 つの要素を持つことが保証された `MatchedRoute` の読み取り専用タプル配列を返します。1 つもマッチしなかった場合は `null` を返します。
  */
 export default function matchRoutes(
   routes: readonly Route[],
-  pathname: string,
+  url: ReadonlyURL,
 ): readonly [MatchedRoute, ...MatchedRoute[]] | null {
+  const matched: MatchedRoute[] = [];
+
+  // 登録されているすべてのルートを前方から順番に走査します。
+  // routes 配列は詳細度が高い順に並んでいることが前提となります。
   for (const route of routes) {
-    const matched = matchRoute(route, pathname);
-    if (matched) {
-      return matched;
+    const result = matchRoutePath(route, url);
+    if (!result) {
+      continue;
     }
+
+    matched.push({
+      ...route,
+      params: result.params,
+      urlPath: inject(route.path, result.params),
+    });
+  }
+
+  if (matched.length > 0) {
+    return matched as [any];
   }
 
   return null;

package/src/core/readonly-form-data.types.ts

@@ -1,63 +1,83 @@
 /**
- * **`ReadonlyFormData`** インターフェースは、フォームフィールドとその値のセットをキーと値のペアで構築する方法を提供します。
+ * フォームデータを読み取り専用で操作するためのインターフェースです。
  *
- * 構築したデータは、`fetch()`、`XMLHttpRequest.send()`、または `navigator.sendBeacon()` メソッドを使用して送信できます。
+ * データの追加、削除、更新といった変更処理を禁止し、データの参照や走査のみを許可する目的で使用します。
  *
  * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData)
  */
 export interface ReadonlyFormData {
   /**
-   * ReadonlyFormData インターフェースの **`get()`** メソッドは、`FormData` オブジェクト内にある指定したキーに関連付けられた最初の値を返します。
+   * 指定された名前に一致する最初のフォームデータの値を取得します。
+   *
+   * @param name 検索するフォームコントロールのキー名です。
+   * @returns 一致したデータを返します。データは文字列または `File` オブジェクトのいずれかです。指定された名前のキーが存在しない場合は `null` を返します。
    *
    * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/get)
    */
   get(name: string): FormDataEntryValue | null;
 
   /**
-   * ReadonlyFormData インターフェースの **`getAll()`** メソッドは、`FormData` オブジェクト内にある指定したキーに関連付けられたすべての値を返します。
+   * 指定された名前に一致するすべてのフォームデータの値を配列として取得します。
+   *
+   * @param name 検索するフォームコントロールのキー名です。
+   * @returns 一致したすべてのデータを含む配列です。キーが存在しない場合は空の配列を返します。
    *
    * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/getAll)
    */
   getAll(name: string): FormDataEntryValue[];
 
   /**
-   * ReadonlyFormData インターフェースの **`has()`** メソッドは、`FormData` オブジェクトに特定のキーが含まれているかどうかを返します。
+   * 指定された名前を持つフォームデータが存在するかどうかを判定します。
+   *
+   * @param name 検証するフォームコントロールのキー名です。
+   * @returns 指定されたキーが存在する場合は `true` を、存在しない場合は `false` を返します。
    *
    * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/has)
    */
   has(name: string): boolean;
 
   /**
-   * FormData オブジェクトに含まれるすべてのキーと値のペアに対して、指定されたコールバック関数を一度ずつ実行します。
+   * コールバック関数を使用して、格納されているすべてのフォームデータに対して反復処理を実行します。
+   *
+   * @param callbackfn 各データに対して実行するコールバック関数です。
+   * @param thisArg コールバック関数を実行する際に `this` として使用する値です。
    */
   forEach(
     callbackfn: (value: FormDataEntryValue, key: string, parent: ReadonlyFormData) => void,
     thisArg?: any,
   ): void;
 
-  // /**
-  //  * ReadonlyFormData インターフェースの **`entries()`** メソッドは、このオブジェクトに含まれるすべてのキーと値のペアを順に走査するためのイテレーターを返します。
-  //  *
-  //  * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/entries)
-  //  */
-  // entries(): IterableIterator<[string, FormDataEntryValue]>;
+  /**
+   * 格納されているすべてのキーと値のペアを順に処理するための反復子（イテレーター）を返します。
+   *
+   * @returns キーと値のペアを要素とする `IterableIterator` オブジェクトです。
+   *
+   * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/entries)
+   */
+  entries(): IterableIterator<[string, FormDataEntryValue]>;
 
-  // /**
-  //  * ReadonlyFormData インターフェースの **`keys()`** メソッドは、このオブジェクトに含まれるすべてのキー（name）を順に走査するためのイテレーターを返します。
-  //  *
-  //  * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/keys)
-  //  */
-  // keys(): IterableIterator<string>;
+  /**
+   * 格納されているすべてのキー名を順に処理するための反復子を返します。
+   *
+   * @returns 各データのキー名を要素とする `IterableIterator` オブジェクトです。
+   *
+   * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/keys)
+   */
+  keys(): IterableIterator<string>;
 
-  // /**
-  //  * ReadonlyFormData インターフェースの **`values()`** メソッドは、このオブジェクトに含まれるすべての値を順に走査するためのイテレーターを返します。
-  //  *
-  //  * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/values)
-  //  */
-  // values(): IterableIterator<FormDataEntryValue>;
+  /**
+   * 格納されているすべての値のみを順に処理するための反復子を返します。
+   *
+   * @returns 各データの値（文字列または `File` オブジェクト）を要素とする `IterableIterator` オブジェクトです。
+   *
+   * [MDN リファレンス](https://developer.mozilla.org/docs/Web/API/FormData/values)
+   */
+  values(): IterableIterator<FormDataEntryValue>;
 
-  // /**
-  //  * FormData オブジェクトのデフォルトのイテレーターです。これにより `for...of` ループで直接 `entries()` と同様の挙動（キーと値のペアの取得）が可能になります。
-  //  */
-  // [Symbol.iterator](): IterableIterator<[string, FormDataEntryValue]>;
+  /**
+   * オブジェクトの既定の反復子を定義します。 `for...of` 構文などで直接オブジェクトを走査することを可能にします。
+   *
+   * @returns `entries` メソッドと同様に、キーと値のペアを要素とする `IterableIterator` オブジェクトです。
+   */
+  [Symbol.iterator](): IterableIterator<[string, FormDataEntryValue]>;
 }