Skip to content

Conversation

@jquirke
Copy link

@jquirke jquirke commented Sep 29, 2025

Summary

Implements support for map value groups consumption via map[string]T for named value groups, enabling both individual named access and map-based access to the same providers.

This implements feature requests #1036 #998 by integrating the map value groups functionality from uber-go/dig#381 into fx with comprehensive test coverage.

Changes

  • map_groups_test.go: Comprehensive tests for map consumption, interfaces, pointer types, name+group combinations, edge cases including invalid key type validation, and mixed consumption patterns
  • module_test.go: Module scoping tests for map value groups across fx.Module boundaries
  • decorate_test.go: Enhanced with map decoration tests and validation of slice decorator restrictions for named value groups
  • go.mod: Updated to use dig fork with map value groups support
  • CHANGELOG.md: Updated to document the new functionality

Key Features

  • Consume value groups as map[string]T indexed by provider names
  • Combine name and group annotations for dual access patterns
  • Map-based decoration support for value groups
  • Proper validation that blocks slice decorators for named value groups
  • Module scoping behavior consistent with existing value groups
  • Mixed consumption patterns (same group as both map and slice)
  • Backward compatibility with existing slice-based consumption

Test Coverage

  • Basic map consumption with interfaces and pointer types
  • Name+Group combination scenarios
  • Map decoration functionality
  • Module scoping across fx.Module boundaries
  • Mixed consumption patterns (map and slice of same group)
  • Edge cases (empty groups, duplicate names, invalid key types, validation errors)
  • Slice decorator blocking for named value groups
  • All existing fx tests continue to pass

Dependencies

Important: This PR currently uses a forked dig dependency (github.com/jquirke/dig v0.0.0-20250929003136-0b0022552f09) that implements the map value groups functionality. This PR cannot be merged until:

  1. Add map value groups support to dig dig#381 is reviewed, approved, and merged into the upstream dig repository
  2. A new dig release is published containing the map value groups functionality
  3. This PR is updated to use the official dig release instead of the fork

The fx implementation and tests are complete and ready, but the underlying dig dependency must be officially released first.

Implements #1036

Add support for consuming named value groups as map[string]T, enabling
both individual named access and map-based consumption of the same
providers. While the core functionality is implemented in dig PR uber-go#381,
this commit adds comprehensive fx integration and test coverage.

Changes:
- Add map_groups_test.go with extensive test coverage for map consumption,
  interfaces, pointer types, name+group combinations, and edge cases
- Enhance decorate_test.go with map decoration tests and validation of
  slice decorator restrictions for named value groups
- Update go.mod to use dig fork with map value groups support
- Update CHANGELOG.md to document the new functionality

Fixes uber-go#1036

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
@jquirke jquirke changed the title Add map value groups support to dig Implement map value groups support in fx Sep 29, 2025
@jquirke jquirke marked this pull request as ready for review September 29, 2025 03:44
jquirke and others added 8 commits September 28, 2025 20:51
Test that value groups properly reject non-string map keys (using int as example)
with the expected error message from dig validation.
Test map value groups behavior across fx.Module boundaries:
- Map consumption across child and parent modules
- Nested module hierarchies
- Global visibility of groups across all modules
- Name conflict detection across module boundaries

Verified behavior is consistent with existing slice value groups
where all modules see the global group state.

Moved tests to module_test.go where they belong since they
specifically test fx.Module behavior.
Test that the same value group can be consumed as both map and slice
in different parts of the same application. This validates an important
real-world use case where hybrid consumption patterns are needed.
This test verifies that map value group decoration chains properly
across module boundaries, demonstrating the correct behavior for
named value groups as implemented in uber-go/dig#381.
- Add test for soft map group consumption in annotated_test.go
- Add test for soft map group decoration in decorate_test.go
- Verify soft groups only contain values from executed constructors when consumed as maps
- Test both decoration and consumption scenarios with soft map groups

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
Demos should be placed in proper location, will be fixed later.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
…ption

- Add Named Value Groups and Map Consumption section to doc.go
- Document providing values with both name and group tags
- Show multiple consumption patterns: map, slice, and individual access
- Include practical examples with fx.Annotate and struct tags
- Explain constraints for map consumption (string keys, all values must have names)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
- Add demo code in docs/ex/value-groups/maps/ with handlers, feeding, consuming examples
- Create documentation in docs/src/value-groups/maps/ explaining map consumption
- Update mkdocs.yml to include new map documentation pages
- Add dig replace directive to docs/go.mod for map groups support
- Include decoration restrictions and error conditions in documentation
- Provide working tests demonstrating map vs slice consumption

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
@jquirke
Copy link
Author

jquirke commented Sep 29, 2025

Documentation Update

Added comprehensive documentation and examples for map value groups:

New Documentation

  • docs/src/value-groups/maps/feed.md: How to feed values into map groups with name+group tags
  • docs/src/value-groups/maps/consume.md: Map vs slice consumption patterns and best practices

Demo Code

  • docs/ex/value-groups/maps/: Complete working examples with handlers, tests, and usage patterns
  • Updated mkdocs.yml navigation to include the new documentation

Key Documentation Topics

  • Basic map feeding and consumption syntax
  • Mixed consumption (map + slice from same group)
  • Decoration restrictions for map groups
  • Error conditions and validation requirements
  • Performance benefits and when to use maps vs slices

The documentation follows the existing fx docs pattern with code snippets and comprehensive examples. Ready for review alongside the implementation!

- Update annotated.go docs to remove outdated mutual exclusivity restriction
- Enhance doc.go with clearer examples showing both fx.Out and fx.ResultTags approaches
- Add comprehensive test demonstrating fx.Out struct with both name and group tags

This confirms that fx.Out structs fully support combining name and group annotations,
which was already working but not properly documented or tested.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant