docs: update flattenObject documentation with Map support

Author: sen2y

docs/ja/reference/object/flattenObject.md

@@ -1,27 +1,38 @@
 # flattenObject
 
-ネストされたオブジェクトを単純なオブジェクトに平坦化します。
+ネストされたオブジェクトを単純なオブジェクトに平坦化するか、Mapに直接変換します。
 
 - `Array`は平坦化されます。
 - `Buffer`や`TypedArray`のような純粋なオブジェクトでないものは平坦化されません。
 
 ## インターフェース
 
 ```typescript
-function flattenObject(object: object, { delimiter = '.' }: FlattenObjectOptions = {}): Record<string, any>;
+// Record<string, any>を返す
+function flattenObject(object: object, options?: { delimiter?: string }): Record<string, any>;
+
+// Map<string, any>を返す（レガシー構文）
+function flattenObject(object: object, target: Map<string, any>): Map<string, any>;
+
+// Map<string, any>を返す（区切り文字付き）
+function flattenObject(object: object, options: { delimiter?: string; target: Map<string, any> }): Map<string, any>;
 ```
 
 ### パラメータ
 
 - `object` (`object`): 平坦化するオブジェクト。
-- `delimiter` (`string`): ネストされたキーの区切り文字。デフォルトは `'.'`。
+- `options` (`object`, オプション): オプションオブジェクト。
+  - `delimiter` (`string`): ネストされたキーの区切り文字。デフォルトは `'.'`。
+  - `target` (`Map<string, any>`): 平坦化されたキーと値のペアで満たすMap。
 
 ### 戻り値
 
-(`T`): 平坦化されたオブジェクト。
+(`Record<string, any> | Map<string, any>`): 平坦化されたオブジェクトまたはMap。
 
 ## 例
 
+### 基本的な使用法（Record）
+
 ```typescript
 const nestedObject = {
   a: {
@@ -42,6 +53,8 @@ console.log(flattened);
 // }
 ```
 
+### カスタム区切り文字（Record）
+
 ```typescript
 const flattened = flattenObject(nestedObject, { delimiter: '/' });
 console.log(flattened);
@@ -52,3 +65,26 @@ console.log(flattened);
 //   'd/1': 3
 // }
 ```
+
+### Mapターゲット（レガシー構文）
+
+```typescript
+const map = flattenObject(nestedObject, new Map());
+console.log(map);
+// 出力: Map { 'a.b.c' => 1, 'd.0' => 2, 'd.1' => 3 }
+
+// 値へのアクセス
+console.log(map.get('a.b.c')); // 1
+console.log(map.size); // 3
+```
+
+### Map + カスタム区切り文字
+
+```typescript
+const customMap = flattenObject(nestedObject, {
+  delimiter: '_',
+  target: new Map(),
+});
+console.log(customMap);
+// 出力: Map { 'a_b_c' => 1, 'd_0' => 2, 'd_1' => 3 }
+```

docs/ko/reference/object/flattenObject.md

@@ -1,27 +1,38 @@
 # flattenObject
 
-중첩된 객체를 단순한 객체로 평탄화해요.
+중첩된 객체를 단순한 객체로 평탄화하거나 Map으로 직접 변환해요.
 
 - `Array`는 평탄화돼요.
 - 순수 객체가 아닌 `Buffer`나 `TypedArray`는 평탄화되지 않아요.
 
 ## 인터페이스
 
 ```typescript
-function flattenObject(object: object, { delimiter = '.' }: FlattenObjectOptions = {}): Record<string, any>;
+// Record<string, any> 반환
+function flattenObject(object: object, options?: { delimiter?: string }): Record<string, any>;
+
+// Map<string, any> 반환 (기존 문법)
+function flattenObject(object: object, target: Map<string, any>): Map<string, any>;
+
+// Map<string, any> 반환 (구분자 포함)
+function flattenObject(object: object, options: { delimiter?: string; target: Map<string, any> }): Map<string, any>;
 ```
 
 ### 파라미터
 
 - `object` (`object`): 평탄화할 객체.
-- `delimiter` (`string`): 중첩된 키의 구분자. 기본값은 `.`.
+- `options` (`object`, 선택): 옵션 객체.
+  - `delimiter` (`string`): 중첩된 키의 구분자. 기본값은 `.`.
+  - `target` (`Map<string, any>`): 평탄화된 키-값 쌍으로 채울 Map.
 
 ### 반환 값
 
-(`T`): 평탄화된 객체.
+(`Record<string, any> | Map<string, any>`): 평탄화된 객체 또는 Map.
 
 ## 예시
 
+### 기본 사용법 (Record)
+
 ```typescript
 const nestedObject = {
   a: {
@@ -42,6 +53,8 @@ console.log(flattened);
 // }
 ```
 
+### 구분자 지정 (Record)
+
 ```typescript
 const flattened = flattenObject(nestedObject, { delimiter: '/' });
 console.log(flattened);
@@ -52,3 +65,26 @@ console.log(flattened);
 //   'd/1': 3
 // }
 ```
+
+### Map 대상 (기존 문법)
+
+```typescript
+const map = flattenObject(nestedObject, new Map());
+console.log(map);
+// Output: Map { 'a.b.c' => 1, 'd.0' => 2, 'd.1' => 3 }
+
+// 값 접근
+console.log(map.get('a.b.c')); // 1
+console.log(map.size); // 3
+```
+
+### Map + 구분자 지정
+
+```typescript
+const customMap = flattenObject(nestedObject, {
+  delimiter: '_',
+  target: new Map(),
+});
+console.log(customMap);
+// Output: Map { 'a_b_c' => 1, 'd_0' => 2, 'd_1' => 3 }
+```

docs/reference/object/flattenObject.md

@@ -1,27 +1,38 @@
 # flattenObject
 
-Flattens a nested object into a single-level object with dot-separated keys.
+Flattens a nested object into a single-level object with dot-separated keys or directly into a Map.
 
 - `Array`s are flattened.
 - Non-plain objects, like `Buffer`s or `TypedArray`s, are not flattened.
 
 ## Signature
 
 ```typescript
-function flattenObject(object: object, { delimiter = '.' }: FlattenObjectOptions = {}): Record<string, any>;
+// Return Record<string, any>
+function flattenObject(object: object, options?: { delimiter?: string }): Record<string, any>;
+
+// Return Map<string, any> (legacy syntax)
+function flattenObject(object: object, target: Map<string, any>): Map<string, any>;
+
+// Return Map<string, any> (with custom delimiter)
+function flattenObject(object: object, options: { delimiter?: string; target: Map<string, any> }): Map<string, any>;
 ```
 
 ### Parameters
 
 - `object` (`object`): The object to flatten.
-- `delimiter` (`string`): The delimiter to use between nested keys. Defaults to `'.'`.
+- `options` (`object`, optional): The options object.
+  - `delimiter` (`string`): The delimiter to use between nested keys. Defaults to `'.'`.
+  - `target` (`Map<string, any>`): The target Map to populate with flattened key-value pairs.
 
 ### Returns
 
-(`T`): The flattened object.
+(`Record<string, any> | Map<string, any>`): The flattened object or Map.
 
 ## Examples
 
+### Basic Usage (Record)
+
 ```typescript
 const nestedObject = {
   a: {
@@ -42,6 +53,8 @@ console.log(flattened);
 // }
 ```
 
+### Custom Delimiter (Record)
+
 ```typescript
 const flattened = flattenObject(nestedObject, { delimiter: '/' });
 console.log(flattened);
@@ -52,3 +65,38 @@ console.log(flattened);
 //   'd/1': 3
 // }
 ```
+
+### Map Target (Legacy Syntax)
+
+```typescript
+const map = flattenObject(nestedObject, new Map());
+console.log(map);
+// Output: Map { 'a.b.c' => 1, 'd.0' => 2, 'd.1' => 3 }
+
+// Access values
+console.log(map.get('a.b.c')); // 1
+console.log(map.size); // 3
+```
+
+### Map with Custom Delimiter
+
+```typescript
+const customMap = flattenObject(nestedObject, {
+  delimiter: '_',
+  target: new Map(),
+});
+console.log(customMap);
+// Output: Map { 'a_b_c' => 1, 'd_0' => 2, 'd_1' => 3 }
+```
+
+### Performance Comparison
+
+Using Map targets provides better performance compared to converting Records to Maps:
+
+```typescript
+// Slower: Object → Array → Map (3 steps)
+const slowMap = new Map(Object.entries(flattenObject(largeObject)));
+
+// Faster: Object → Map (1 step)
+const fastMap = flattenObject(largeObject, new Map());
+```