feat(toFormData): Add toFormData

docs/ja/reference/object/toFormData.md

@@ -0,0 +1,107 @@
+# toFormData
+
+オブジェクトを `FormData` インスタンスに変換します。この関数は、オブジェクト内の各キーと値のペアを再帰的に処理し、それを `FormData` インスタンスに追加します。ネストされたオブジェクトや配列、ファイル、およびさまざまなJavaScriptデータ型をサポートしており、複雑なデータ構造に対応できるように構成オプションでのカスタマイズが可能です。
+
+- **ディープ変換**: ネストされたオブジェクトや配列を再帰的に `FormData` フォーマットに変換します。
+- **ファイルサポート**: `File` および `Blob` オブジェクトを自動的に処理します。
+- **型変換**: `boolean`、`BigInt`、`Date` などの一般的なJavaScriptデータ型を `FormData` に適した文字列表現に変換します。
+- **構成オプション**: 配列、boolean、null値、ネストされたオブジェクトの処理方法をカスタマイズするためのオプションを提供します。
+
+## シグネチャ
+
+```typescript
+function toFormData({
+  data: Record<string, any>,
+  formData = new FormData(),
+  parentKey?: string,
+  config = formDataOptions
+}): FormData;
+```
+
+### パラメータ
+
+- `data` (`Record<string, any>`): `FormData` に変換されるオブジェクト。プリミティブ型、配列、オブジェクト、`File`、`Blob` などの一般的なデータ型をサポートします。
+- `formData` (`FormData`): データを追加するための既存の `FormData` インスタンスです。指定しない場合、新しい `FormData` インスタンスが作成されます。
+- `parentKey` (`string`): ネストされたオブジェクトや配列を処理するためのオプションのキー。再帰処理中に内部的に使用されます。
+- `config` (`object`): `FormData` 変換をカスタマイズするための構成オブジェクトです。
+
+### 構成オプション
+
+- `allowEmptyArrays` (`boolean`): `true` の場合、空の配列が空文字列として `FormData` に追加されます。デフォルトは `false` です。
+- `convertBooleansToIntegers` (`boolean`): `true` の場合、boolean 値 (`true`/`false`) が `'1'` および `'0'` に変換されます。デフォルトは `false` です。
+- `ignoreNullValues` (`boolean`): `true` の場合、`null` 値が `FormData` から省略されます。デフォルトは `false` です。
+- `noArrayNotationForFiles` (`boolean`): `true` の場合、ファイルの配列は `[]` 表記なしで `FormData` に追加されます。デフォルトは `false` です。
+- `noArrayNotationForNonFiles` (`boolean`): `true` の場合、ファイル以外の配列が `[]` 表記なしで `FormData` に追加されます。デフォルトは `false` です。
+- `useDotNotationForObjects` (`boolean`): `true` の場合、ネストされたオブジェクトプロパティは、ブラケット表記（例: `parent[child]`）ではなくドット表記（例: `parent.child`）で表されます。デフォルトは `false` です。
+
+### 戻り値
+
+(`FormData`): オブジェクトのキーと値のペアで埋められた `FormData` インスタンスです。
+
+### データ型のサポート
+
+この関数は、さまざまなJavaScriptデータ型を処理します：
+
+- `undefined`: スキップされ、`FormData` にエントリは作成されません。
+- `null`: 空の文字列 (`''`) が追加されるか、`ignoreNullValues` に基づいて無視されます。
+- `boolean`: `'true'` または `'false'` に変換されます。または、`convertBooleansToIntegers` が `true` の場合は `'1'` または `'0'` に変換されます。
+- `BigInt`: 文字列に変換されます。
+- `Date`: ISO 文字列に変換されます。
+- `File` / `Blob`: そのまま追加されます。
+- `Array`: 構成に基づき、インデックスまたは省略された `[]` 表記で再帰的に処理されます。
+- `Object`: 構成に基づき、ドット表記またはブラケット表記のネストされたキーで再帰的に処理されます。
+
+## 使用例
+
+### 基本的な使用例と構成
+
+```typescript
+const obj = { name: 'John', age: 30, preferences: { color: 'blue', food: 'pizza' } };
+const formData = toFormData({ data: obj, config: { useDotNotationForObjects: true } });
+// formDataには次が含まれます：
+// "name" -> "John"
+// "age" -> "30"
+// "preferences.color" -> "blue"
+// "preferences.food" -> "pizza"
+```
+
+### ファイルと空の配列の処理
+
+```typescript
+const file = new File(['file content'], 'file.txt', { type: 'text/plain' });
+const obj = { name: 'John', profilePicture: file, tags: [] };
+const formData = toFormData({ data: obj, config: { allowEmptyArrays: true } });
+// formDataには次が含まれます：
+// "name" -> "John"
+// "profilePicture" -> file
+// "tags" -> ""
+```
+
+### boolean の変換と null 値の無視
+
+```typescript
+const obj = { isActive: true, age: null };
+const formData = toFormData({ data: obj, config: { convertBooleansToIntegers: true, ignoreNullValues: true } });
+// formDataには次が含まれます：
+// "isActive" -> "1"
+// (null の "age" エントリは省略されます)
+```
+
+### ネストされたオブジェクトと配列
+
+```typescript
+const obj = {
+  name: 'Alice',
+  hobbies: ['reading', 'gaming'],
+  address: {
+    street: '123 Main St',
+    city: 'Wonderland',
+  },
+};
+const formData = toFormData({ data: obj, config: { noArrayNotationForNonFiles: true } });
+// formDataには次が含まれます：
+// "name" -> "Alice"
+// "hobbies" -> ["reading", "gaming"] // 非ファイル配列に配列表記がありません
+// "address[street]" -> "123 Main St"
+// "address[city]" -> "Wonderland"
+```

docs/ko/reference/object/toFormData.md

@@ -0,0 +1,107 @@
+# toFormData
+
+객체를 `FormData` 인스턴스로 변환합니다. 이 함수는 객체 내의 각 키-값 쌍을 재귀적으로 처리하여 `FormData` 인스턴스에 추가합니다. 중첩된 객체와 배열, 파일 및 다양한 JavaScript 데이터 유형을 지원하며, 구성 옵션을 통해 복잡한 데이터 구조에 대해 사용자 정의 처리가 가능합니다.
+
+- **깊은 변환**: 중첩된 객체와 배열을 재귀적으로 `FormData` 형식으로 변환합니다.
+- **파일 지원**: `File` 및 `Blob` 객체를 자동으로 처리합니다.
+- **유형 변환**: `boolean`, `BigInt`, `Date` 등의 일반적인 JavaScript 데이터 유형을 `FormData`의 문자열 표현으로 변환합니다.
+- **구성 가능**: 배열, boolean, null 값, 중첩 객체 처리 방법을 사용자 지정할 수 있는 옵션을 제공합니다.
+
+## 시그니처
+
+```typescript
+function toFormData({
+  data: Record<string, any>,
+  formData = new FormData(),
+  parentKey?: string,
+  config = formDataOptions
+}): FormData;
+```
+
+### 매개변수
+
+- `data` (`Record<string, any>`): `FormData`로 변환할 객체입니다. 기본 유형, 배열, 객체, `File`, `Blob` 등 다양한 유형을 지원합니다.
+- `formData` (`FormData`): 데이터를 추가할 기존 `FormData` 인스턴스입니다. 제공되지 않으면 새로운 `FormData` 인스턴스가 생성됩니다.
+- `parentKey` (`string`): 중첩된 객체 및 배열을 처리하는 데 사용되는 선택적 키입니다. 재귀 처리 중에 내부적으로 사용됩니다.
+- `config` (`object`): `FormData` 변환을 사용자 지정할 수 있는 구성 객체입니다.
+
+### 구성 옵션
+
+- `allowEmptyArrays` (`boolean`): `true`인 경우, 빈 배열이 빈 문자열로 `FormData`에 추가됩니다. 기본값은 `false`입니다.
+- `convertBooleansToIntegers` (`boolean`): `true`인 경우, boolean 값(`true`/`false`)이 `'1'` 및 `'0'`으로 변환됩니다. 기본값은 `false`입니다.
+- `ignoreNullValues` (`boolean`): `true`인 경우, `null` 값이 `FormData`에 추가되지 않습니다. 기본값은 `false`입니다.
+- `noArrayNotationForFiles` (`boolean`): `true`인 경우, 파일 배열이 `[]` 표기 없이 `FormData`에 추가됩니다. 기본값은 `false`입니다.
+- `noArrayNotationForNonFiles` (`boolean`): `true`인 경우, 파일이 아닌 배열이 `[]` 표기 없이 `FormData`에 추가됩니다. 기본값은 `false`입니다.
+- `useDotNotationForObjects` (`boolean`): `true`인 경우, 중첩된 객체 속성이 괄호 표기(`parent[child]`) 대신 점 표기(`parent.child`)를 사용합니다. 기본값은 `false`입니다.
+
+### 반환값
+
+(`FormData`): 객체의 키-값 쌍이 포함된 `FormData` 인스턴스입니다.
+
+### 데이터 유형 지원
+
+이 함수는 다양한 JavaScript 데이터 유형을 처리합니다:
+
+- `undefined`: 무시되며, `FormData`에 항목이 생성되지 않습니다.
+- `null`: 빈 문자열 (`''`)을 추가하거나 `ignoreNullValues` 설정에 따라 무시됩니다.
+- `boolean`: `'true'` 또는 `'false'`로 변환되며, `convertBooleansToIntegers`가 `true`일 경우 `'1'` 또는 `'0'`으로 변환됩니다.
+- `BigInt`: 문자열로 변환됩니다.
+- `Date`: ISO 문자열로 변환됩니다.
+- `File` / `Blob`: 그대로 추가됩니다.
+- `Array`: 구성에 따라 인덱스 표기 또는 생략된 `[]` 표기로 재귀 처리됩니다.
+- `Object`: 구성에 따라 점 표기 또는 괄호 표기의 중첩 키로 재귀 처리됩니다.
+
+## 사용 예시
+
+### 기본 사용 예시와 구성
+
+```typescript
+const obj = { name: 'John', age: 30, preferences: { color: 'blue', food: 'pizza' } };
+const formData = toFormData({ data: obj, config: { useDotNotationForObjects: true } });
+// formData에는 다음이 포함됩니다:
+// "name" -> "John"
+// "age" -> "30"
+// "preferences.color" -> "blue"
+// "preferences.food" -> "pizza"
+```
+
+### 파일과 빈 배열 처리
+
+```typescript
+const file = new File(['file content'], 'file.txt', { type: 'text/plain' });
+const obj = { name: 'John', profilePicture: file, tags: [] };
+const formData = toFormData({ data: obj, config: { allowEmptyArrays: true } });
+// formData에는 다음이 포함됩니다:
+// "name" -> "John"
+// "profilePicture" -> file
+// "tags" -> ""
+```
+
+### boolean 변환 및 null 값 무시
+
+```typescript
+const obj = { isActive: true, age: null };
+const formData = toFormData({ data: obj, config: { convertBooleansToIntegers: true, ignoreNullValues: true } });
+// formData에는 다음이 포함됩니다:
+// "isActive" -> "1"
+// ("age" 항목 없음, null 값 무시됨)
+```
+
+### 중첩 객체와 배열 처리
+
+```typescript
+const obj = {
+  name: 'Alice',
+  hobbies: ['reading', 'gaming'],
+  address: {
+    street: '123 Main St',
+    city: 'Wonderland',
+  },
+};
+const formData = toFormData({ data: obj, config: { noArrayNotationForNonFiles: true } });
+// formData에는 다음이 포함됩니다:
+// "name" -> "Alice"
+// "hobbies" -> ["reading", "gaming"] // 비파일 배열의 경우 인덱스 생략
+// "address[street]" -> "123 Main St"
+// "address[city]" -> "Wonderland"
+```

docs/reference/object/toFormData.md

@@ -0,0 +1,107 @@
+# toFormData
+
+Converts an object into a `FormData` instance, allowing customization through a configuration object. This function recursively processes each key-value pair in an object, appending them to the `FormData` instance. It supports nested objects, arrays, files, and various JavaScript data types, making it suitable for handling complex data structures. Configuration options control how different data types and structures are represented in the `FormData`.
+
+- **Deep Conversion**: Recursively converts nested objects and arrays into `FormData` format.
+- **Supports Files**: Automatically handles `File` and `Blob` objects.
+- **Type Conversion**: Converts common JavaScript types like `boolean`, `BigInt`, `Date`, and more into their appropriate string representations for `FormData`.
+- **Configurable Behavior**: Provides options to customize how arrays, booleans, null values, and nested objects are handled.
+
+## Signature
+
+```typescript
+function toFormData({
+  data: Record<string, any>,
+  formData = new FormData(),
+  parentKey?: string,
+  config = formDataOptions
+}): FormData;
+```
+
+### Parameters
+
+- `data` (`Record<string, any>`): The object to be converted into `FormData`. Supports primitives, arrays, objects, `File`, `Blob`, and other common data types.
+- `formData` (`FormData`): An optional existing `FormData` instance to append the data to. If not provided, a new `FormData` instance is created.
+- `parentKey` (`string`): An optional key to handle nested objects and arrays. Used internally during recursion.
+- `config` (`object`): Configuration object with options to customize the `FormData` conversion.
+
+### Configuration Options
+
+- `allowEmptyArrays` (`boolean`): When `true`, empty arrays are added to the `FormData` as empty strings. Default is `false`.
+- `convertBooleansToIntegers` (`boolean`): When `true`, boolean values (`true`/`false`) are converted to `'1'` and `'0'`. Default is `false`.
+- `ignoreNullValues` (`boolean`): When `true`, `null` values are omitted from the `FormData`. Default is `false`.
+- `noArrayNotationForFiles` (`boolean`): When `true`, file arrays are added to `FormData` without the `[]` notation. Default is `false`.
+- `noArrayNotationForNonFiles` (`boolean`): When `true`, non-file arrays are added to `FormData` without the `[]` notation. Default is `false`.
+- `useDotNotationForObjects` (`boolean`): When `true`, nested object properties use dot notation (e.g., `parent.child`) instead of bracket notation (e.g., `parent[child]`). Default is `false`.
+
+### Returns
+
+(`FormData`): A `FormData` instance populated with the object's key-value pairs.
+
+### Data Type Support
+
+This function handles various JavaScript data types:
+
+- `undefined`: Skipped, no entry is created in `FormData`.
+- `null`: Appends an empty string (`''`) or is ignored based on `ignoreNullValues`.
+- `boolean`: Converted to `'true'` or `'false'` or to `'1'`/`'0'` if `convertBooleansToIntegers` is `true`.
+- `BigInt`: Converted to a `string`.
+- `Date`: Converted to an ISO `string`.
+- `File` / `Blob`: Appended as-is.
+- `Array`: Recursively processed, with or without `[]` notation based on configuration.
+- `Object`: Recursively processed with dot or bracket notation based on configuration.
+
+## Examples
+
+### Basic Usage with Configuration
+
+```typescript
+const obj = { name: 'John', age: 30, preferences: { color: 'blue', food: 'pizza' } };
+const formData = toFormData({ data: obj, config: { useDotNotationForObjects: true } });
+// formData will contain:
+// "name" -> "John"
+// "age" -> "30"
+// "preferences.color" -> "blue"
+// "preferences.food" -> "pizza"
+```
+
+### Handling Files and Empty Arrays
+
+```typescript
+const file = new File(['file content'], 'file.txt', { type: 'text/plain' });
+const obj = { name: 'John', profilePicture: file, tags: [] };
+const formData = toFormData({ data: obj, config: { allowEmptyArrays: true } });
+// formData will contain:
+// "name" -> "John"
+// "profilePicture" -> file
+// "tags" -> ""
+```
+
+### Converting Booleans and Ignoring Null Values
+
+```typescript
+const obj = { isActive: true, age: null };
+const formData = toFormData({ data: obj, config: { convertBooleansToIntegers: true, ignoreNullValues: true } });
+// formData will contain:
+// "isActive" -> "1"
+// (No "age" entry, as null values are ignored)
+```
+
+### Nested Objects and Arrays
+
+```typescript
+const obj = {
+  name: 'Alice',
+  hobbies: ['reading', 'gaming'],
+  address: {
+    street: '123 Main St',
+    city: 'Wonderland',
+  },
+};
+const formData = toFormData({ data: obj, config: { noArrayNotationForNonFiles: true } });
+// formData will contain:
+// "name" -> "Alice"
+// "hobbies" -> ["reading", "gaming"] // No array notation for non-files
+// "address[street]" -> "123 Main St"
+// "address[city]" -> "Wonderland"
+```