feat: Add Map support to flattenObject function Fixes #1388

[sen2y]

Add Map support to flattenObject function

Fixes #1388

Summary

This PR adds Map support to the flattenObject function as requested in issue #1388, allowing users to flatten objects directly into Map instances for improved performance and cleaner syntax.

However, during implementation, we discovered that simply adding Map support would break the existing delimiter customization feature. To maintain feature parity and ensure users don't lose functionality, we implemented an enhanced solution that supports both Map targets and custom delimiters simultaneously.

Changes

🆕 New Features

1. Direct Map Support - Users can now pass a Map as the second parameter
2. Map + Custom Delimiter - New syntax for using Maps with custom delimiters
3. Performance Optimization - Eliminates intermediate object/array creation

🔧 Implementation Details

• Added FlattenObjectMapOptions interface for Map-specific options
• Enhanced function signature to support multiple parameter types
• Added flattenObjectIntoMap function for direct Map operations
• Maintained full backward compatibility with existing API

Usage Examples

The flattenObject function now supports 4 different usage patterns:

1. Original Object Return (unchanged)

const result = flattenObject(nestedObject);
// Returns: { "a.b.c": 1, "d.0": 2, "d.1": 3 }

2. Object with Custom Delimiter (unchanged)

const result = flattenObject(nestedObject, { delimiter: '_' });
// Returns: { "a_b_c": 1, "d_0": 2, "d_1": 3 }

3. Map Target (new - addresses #1388)

const map = flattenObject(nestedObject, new Map());
// Returns: Map { 'a.b.c' => 1, 'd.0' => 2, 'd.1' => 3 }

4. Map with Custom Delimiter (new - enhancement)

const customMap = flattenObject(nestedObject, { 
  delimiter: '_', 
  target: new Map() 
});
// Returns: Map { 'a_b_c' => 1, 'd_0' => 2, 'd_1' => 3 }

Performance Benchmarks

Comprehensive performance testing shows significant improvements:

Test Case	Legacy Method (ops/sec)	New Method (ops/sec)	Performance Gain
Normal Data	137,671	204,929	1.49x faster
Large Data	125	716	5.7x faster
Very Large Data	0.096	0.677	7.08x faster
With Custom Delimiter	140,104	281,763	2.01x faster

Why is it faster?

Legacy approach (3 steps):

// 1. Create flattened object
const flattened = flattenObject(contents);
// 2. Convert to entries array  
const entries = Object.entries(flattened);
// 3. Create Map from array
const map = new Map(entries);

New approach (1 step):

// Direct Map creation
const map = flattenObject(contents, new Map());

The new approach eliminates intermediate object and array creation, resulting in significant memory and CPU savings.

Testing

• ✅ All existing tests pass (17 tests)
• ✅ Added comprehensive Map functionality tests (4 new tests)
• ✅ TypeScript compilation successful
• ✅ Performance benchmarks included
• ✅ Backward compatibility maintained

Commit History

1. feat: add Map support to flattenObject function (Feature Request: flattenObject into Map object #1388) - Core Map functionality
2. feat: add delimiter support for Map target in flattenObject - Enhanced delimiter support
3. test: add performance benchmark for flattenObject Map support - Performance validation

---

한국어 요약

이슈 #1388 요구사항대로 flattenObject 함수에 Map 지원 기능을 추가했습니다. 7ac4f06
그러나 구현 중 기존 delimiter 커스터마이징 기능이 누락되는 문제를 발견하여, Map 지원과 delimiter 지정을 모두 가능하도록 코드를 보완하였습니다. eba49df

주요 개선사항:

• ✅ 이슈 요구사항: Map 직접 지원 추가
• 성능 1.5~7배 향상 (데이터 크기에 따라)
• delimiter 커스터마이징 + Map 동시 사용 가능
• 완전한 하위 호환성 유지

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
es-toolkit	Ready	Preview	Comment	Sep 9, 2025 2:55pm

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.75%. Comparing base (2f40871) to head (2d572b0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1389   +/-   ##
=======================================
  Coverage   99.75%   99.75%           
=======================================
  Files         468      468           
  Lines        4439     4460   +21     
  Branches     1309     1316    +7     
=======================================
+ Hits         4428     4449   +21     
  Misses         11       11           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sen2y]

• 📚 다국어 문서 업데이트: docs/reference, docs/ko, docs/ja의 flattenObject.md에 Map 사용법 추가하였습니다. b4e03b1