README
¶
kv
Fluent operations on Go maps — filter, transform, extract.
// Before: five lines to extract active config values from a map
var active []Config
for _, cfg := range configs {
if cfg.Enabled {
active = append(active, cfg)
}
}
// After: intent only
// isEnabled returns true if the config is enabled.
isEnabled := func(_ string, cfg Config) bool { return cfg.Enabled }
active := kv.From(configs).KeepIf(isEnabled).Values()
Five lines become two.
What It Looks Like
// Transform map values (type change)
labels := kv.MapValues(counts, strconv.Itoa)
// Filter entries, then chain
valid := kv.MapValues(raw, parseConfig).KeepIf(configIsValid)
// Map entries to structs
items := kv.Map(s.Processes, toResult)
// Extract and filter values
actives := kv.Values(userMap).KeepIf(User.IsActive)
// Map entries to a built-in type
// formatEntry returns "key=value" for each map entry.
formatEntry := func(k string, v int) string { return fmt.Sprintf("%s=%d", k, v) }
labels := kv.From(m).ToString(formatEntry)
It's Just a Map
Entries[K,V] is map[K]V — a defined type, not a wrapper. The zero value is a nil map — safe for reads (len, range) but panics on write. Indexing, range, and len all work as with a plain map. From does not copy; the Entries and the original map share the same backing data.
entries := kv.From(m)
v := entries["key"] // indexing works
for k, v := range entries {} // range works
n := len(entries) // len works
Operations
Entries[K,V] is a map with fluent methods. Filter and mapping methods take func(K, V) T predicates/transforms — filtering considers both key and value. Iteration order is not guaranteed (standard Go map behavior).
- Wrap:
From - Filter:
KeepIf,RemoveIf— returnEntries[K,V]for chaining - Extract:
Values,Keys— returnMapper[V]/Mapper[K]for slice chaining - Transform (standalone):
Map,MapKeys,MapValues— standalone because Go methods can't introduce new type parameters - Mapping:
ToString,ToInt,ToFloat64,ToBool,ToAny,ToByte,ToError,ToFloat32,ToInt32,ToInt64,ToRune - Conversion:
ToPairs(map →Mapper[pair.Pair]),FromPairs([]pair.Pair→Entries) - Utilities:
Invert(swap keys/values),Merge(combine maps, last-wins),PickByKeys/OmitByKeys(filter by key set)
See pkg.go.dev for complete API documentation, the main README for installation, and the showcase for real-world rewrites.
Documentation
¶
Overview ¶
Package kv provides fluent operations on Go maps (key-value collections).
Index ¶
- func Invert[K, V comparable](m map[K]V) map[V]K
- func Keys[K comparable, V any](m map[K]V) base.Mapper[K]
- func Map[K comparable, V, T any](m map[K]V, fn func(K, V) T) base.Mapper[T]
- func MapKeys[K comparable, V any, K2 comparable](m map[K]V, fn func(K) K2) base.Entries[K2, V]
- func MapValues[K comparable, V, V2 any](m map[K]V, fn func(V) V2) base.Entries[K, V2]
- func Merge[K comparable, V any](maps ...map[K]V) map[K]V
- func OmitByKeys[K comparable, V any](m map[K]V, keys []K) map[K]V
- func PickByKeys[K comparable, V any](m map[K]V, keys []K) map[K]V
- func ToPairs[K comparable, V any](m map[K]V) base.Mapper[pair.Pair[K, V]]
- func Values[K comparable, V any](m map[K]V) base.Mapper[V]
- type Entries
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Invert ¶ added in v0.41.0
func Invert[K, V comparable](m map[K]V) map[V]K
Invert swaps keys and values. If multiple keys map to the same value, an arbitrary one wins (map iteration order). Both K and V must be comparable.
func Keys ¶
func Keys[K comparable, V any](m map[K]V) base.Mapper[K]
Keys extracts the keys of m as a Mapper for further transformation. Shortcut for From(m).Keys().
func Map ¶
func Map[K comparable, V, T any](m map[K]V, fn func(K, V) T) base.Mapper[T]
Map transforms each key-value pair in m using fn and returns the results as a Mapper. All type parameters are inferred from the arguments. Order is not guaranteed (map iteration order). Panics if fn is nil.
func MapKeys ¶ added in v0.41.0
func MapKeys[K comparable, V any, K2 comparable](m map[K]V, fn func(K) K2) base.Entries[K2, V]
MapKeys transforms each key in m using fn, preserving values. Returns Entries for chaining (e.g., MapKeys(m, fn).KeepIf(pred).Values()). If fn maps multiple keys to the same K2, last-wins (map iteration order). Panics if fn is nil.
func MapValues ¶ added in v0.40.0
func MapValues[K comparable, V, V2 any](m map[K]V, fn func(V) V2) base.Entries[K, V2]
MapValues transforms each value in m using fn, preserving keys. Returns Entries for chaining (e.g., MapValues(m, fn).KeepIf(pred).Values()). Panics if fn is nil.
func Merge ¶ added in v0.41.0
func Merge[K comparable, V any](maps ...map[K]V) map[K]V
Merge combines multiple maps. Later maps override earlier keys. Returns a new map; inputs are not modified.
func OmitByKeys ¶ added in v0.41.0
func OmitByKeys[K comparable, V any](m map[K]V, keys []K) map[K]V
OmitByKeys returns a new map containing entries whose keys do NOT appear in keys.
func PickByKeys ¶ added in v0.41.0
func PickByKeys[K comparable, V any](m map[K]V, keys []K) map[K]V
PickByKeys returns a new map containing only entries whose keys appear in keys. Keys not present in m are silently ignored.
Types ¶
type Entries ¶
type Entries[K comparable, V any] = base.Entries[K, V]
Entries is a defined type over map[K]V. Indexing, ranging, and len all work as with a plain map. The zero value is a nil map — safe for reads (len, range) but panics on write. From does not copy; the Entries and the original map share the same backing data.
func From ¶
func From[K comparable, V any](m map[K]V) Entries[K, V]
From converts a map to Entries for fluent operations.
Source Files