Add map value groups support to dig

[jquirke]

Summary

This PR implements map value groups for the dig dependency injection framework, allowing value groups to be consumed as map[string]T in addition to the existing []T slice format. This addresses issue #380 and related Fx dependent feature uber-go/fx#998, uber-go/fx#1036 which is co-implemented uber-go/fx#1279.

Key Features

1. Map Value Group Consumption

// Provide values with names
c.Provide(func() int{return 1}, dig.Name("first"), dig.Group("numbers"))
c.Provide(func() int{return 2}, dig.Name("second"), dig.Group("numbers"))

// Consume as map
type Params struct {
    dig.In
    NumMap map[string]int `group:"numbers"`     // {"first":1, "second":2}
    NumSlice []int         `group:"numbers"`     // [1, 2] - still works
    Individual int         `name:"first"`        // 1 - still works
}

2. Simultaneous Name + Group Support

• Removed mutual exclusivity between dig.Name() and dig.Group()
• Enables providing values with both name AND group annotations
• Names become map keys when consuming as map[string]T

3. Robust Decoration Validation

• Prevents incompatible slice decorator patterns with named value groups
• Provides clear error messages guiding users to correct decorator usage
• Ensures consistent behavior between slice and map consumption

Implementation Details

Core Changes

• Enhanced result processing to track map keys (names) alongside values
• Updated parameter building to support map construction from named values
• Robust validation ensuring all map entries have names
• Cross-scope behavior maintained consistently with existing slice patterns

Validation & Error Handling

• Map groups require names: Clear error if any value lacks a name
• String keys only: map[string]T enforced (validated at param creation)
• Decoration compatibility: Slice decorators blocked for named groups with helpful guidance

Comprehensive Test Coverage

• ✅ Basic map value group functionality
• ✅ Interface and pointer type support
• ✅ dig.As transformation compatibility
• ✅ Mixed consumption patterns (individual + slice + map)
• ✅ Edge cases: empty groups, invalid keys, decoration scenarios
• ✅ Cross-scope behavior documented and verified
• ✅ Error conditions with clear messages
• ✅ Soft value groups with map consumption

Breaking Changes

None - This is a purely additive feature that maintains full backward compatibility.

Decoration System Design Decision

Pattern Compatibility & Non-Breaking Nature

During development, we identified that slice decorators (func([]T) []T) are fundamentally incompatible with named value groups because:

1. Slice decorators lose key information (names) needed for map reconstruction
2. Cannot convert decorator output to map[string]T without keys

Important: This validation is not a breaking change because:

• Named groups were never supported before this PR - previously dig.Name() and dig.Group() were mutually exclusive
• No existing code could have been using this pattern - it was impossible until we enabled simultaneous name+group tags
• All existing decoration patterns continue to work unchanged

Design Rationale

We chose to block incompatible patterns rather than allow silent failures because:

1. Clear Error Messages: Users get immediate, actionable feedback instead of wondering why decorators seem ignored
2. Consistent Behavior: Both slice and map consumers get predictable results
3. Future-Proof: Prevents confusion as usage scales

Decorator Execution Clarification

Current Behavior: Slice decorators do execute when used with named groups, but their results are blocked during validation. This is the correct behavior given the current architecture:

• Decorators run first to produce their results
• Validation happens during consumption to block problematic patterns
• Error is properly returned preventing the invalid consumption

The tests document this behavior:

// Decorator executes but results are blocked
t.Log("Slice decorator called (results will be blocked)")

Solution: Clear Validation

Added execution-time validation that prevents this pattern and guides users:

// This now produces a clear error (only possible with this PR's new functionality):
c.Provide(func() int{return 1}, dig.Name("key"), dig.Group("nums"))
c.Decorate(func(nums []int) []int { return nums }) // slice decorator
// Error: "cannot use slice decoration for value group: group contains named values, use map[string]T decorator instead"

Correct Pattern:

// Use map decorators for named groups:
c.Decorate(func(p struct{
    dig.In
    NumMap map[string]int `group:"nums"`
}) struct{
    dig.Out
    NumMap map[string]int `group:"nums"`
} {
    // Modify map and return
    return struct{...}{NumMap: modifiedMap}
})

Existing Patterns Unchanged:

// Unnamed groups + slice decorators continue to work exactly as before:
c.Provide(func() int{return 1}, dig.Group("nums")) // no name
c.Provide(func() int{return 2}, dig.Group("nums")) // no name
c.Decorate(func(nums []int) []int { return nums }) // works fine

Soft Value Groups Integration

New Test Coverage

Added comprehensive testing for soft value groups with map consumption:

• Empty soft maps: Verify no providers called when only soft group consumed
• Selective execution: Only executed constructors contribute to soft maps
• Mixed consumption: Soft maps work alongside slice and regular map consumption
• Behavior consistency: Soft map and slice consumption behave identically

Key Findings

• ✅ Soft groups work correctly with maps - No additional implementation needed
• ✅ Consistent semantics - Same execution behavior as slice consumption
• ✅ Reliable operation - Existing soft group logic handles maps seamlessly

// Soft map groups only contain values from executed constructors
type Params struct {
    dig.In
    Service int                  `name:"config"`     // Forces provider execution
    SoftMap map[string]string   `group:"handlers,soft"` // Only executed handlers
}

Edge Cases Handled

Decoration System

• Multiple decorators: Correctly forbidden with "already decorated" errors
• Map decorators + unnamed values: Fails appropriately (maps require names)
• Cross-scope decoration: Consistent behavior between slice and map patterns
• Empty group decoration: Works correctly for both slices and maps

Type System

• Interface types: Full support with map value groups
• Pointer types: Complete compatibility
• dig.As transformations: Seamless integration with maps
• Invalid map keys: Clear validation errors

Soft Groups

• Empty soft maps: Correctly handle no executed providers
• Partial execution: Only include values from executed constructors
• Mixed consumption: Soft and regular consumption work together

Testing Strategy

Functional Testing

• 527+ new test lines covering comprehensive scenarios
• Edge case analysis with systematic coverage
• Cross-scope behavior baseline documentation
• Error condition testing with message validation
• Soft group integration with complete scenario coverage

Compatibility Testing

• All existing tests pass - no regressions
• Mixed consumption patterns verified
• Backward compatibility maintained

Performance Impact

Minimal - Map construction adds negligible overhead only when consuming groups as maps.

Documentation

• Comprehensive code comments explaining behavior
• Clear error messages for invalid usage patterns
• Test coverage serving as usage examples
• Complete package documentation in doc.go with examples and decorator guidance
• Edge case documentation for maintainers

Related Issues

• Closes Allow name and group Result Tags #380
• Addresses Allow name and group Result Tags fx#998
• Addresses Populate a map by combining name and group attributes fx#1036

---

🤖 Generated with Claude Code

[CLAassistant]

All committers have signed the CLA.

[zekth]

Any update on this? @JacobOaks could we make this go forward?

[jquirke]

🚀 Ready for Review (Updated)

This PR is now complete and ready for review!

✅ What's Included:

Core Feature: Map value groups - consume value groups as map[string]T in addition to existing []T slices

Development Enhancement: Added robust validation to ensure decoration patterns work correctly with the new map functionality

Comprehensive Testing: 527 lines of new tests covering edge cases, cross-scope behavior, and error conditions

🎯 Key Highlights:

1. Fully Backward Compatible - No breaking changes, purely additive feature
2. Robust Validation - Clear error messages for invalid usage patterns
3. Complete Edge Case Coverage - Extensive testing ensures production readiness
4. Documentation - Comprehensive code comments and test examples

🔍 Feature Implementation:

The PR successfully implements map value groups as requested in issue #380, with comprehensive validation to ensure slice and map decoration patterns work correctly together. During development, we ensured that decoration behavior remains consistent and provides clear guidance when incompatible patterns are attempted.

📋 Testing Status:

• ✅ All existing tests pass (no regressions)
• ✅ New comprehensive test suite (527 lines)
• ✅ Edge cases thoroughly covered
• ✅ Cross-scope behavior documented

@JacobOaks This addresses issue #380 and is ready for your review! Let me know if you have any questions or need clarification on any aspect of the implementation.

The PR implements map value groups as discussed, with robust validation and comprehensive testing to ensure production quality.