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.
Entries is a defined type over map[K]V that exposes chainable methods (Keys, Values, KeepIf) while preserving normal map indexing and range. Standalone functions (Map, MapValues, MapKeys, Merge, Invert) handle cross-type transforms that methods cannot express.
From converts a plain map to Entries without copying. Start there for method chaining; use standalone functions when the result type differs from the input.
Many operations return [slice.Mapper] for further chaining (Map, Values, Keys, ToPairs).
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
Examples ¶
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.
Example ¶
package main
import (
"fmt"
"github.com/binaryphile/fluentfp/kv"
)
func main() {
codes := map[string]string{"US": "United States", "GB": "United Kingdom"}
inverted := kv.Invert(codes)
// Print specific keys for deterministic output.
fmt.Println(inverted["United States"], inverted["United Kingdom"])
}
Output: US GB
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. Order is not guaranteed (map iteration order). Shortcut for From(m).Keys().
Example ¶
package main
import (
"fmt"
"sort"
"github.com/binaryphile/fluentfp/kv"
)
func main() {
m := map[string]int{"go": 2009, "rust": 2010, "python": 1991}
keys := kv.Keys(m)
sort.Strings(keys)
fmt.Println(keys)
}
Output: [go python rust]
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.
Example ¶
package main
import (
"fmt"
"sort"
"github.com/binaryphile/fluentfp/kv"
)
func main() {
m := map[string]int{"alice": 90, "bob": 85}
// formatEntry formats a key-value pair as "name: score".
formatEntry := func(name string, score int) string {
return fmt.Sprintf("%s: %d", name, score)
}
entries := kv.Map(m, formatEntry)
// Sort for deterministic output (map iteration order is random).
sort.Strings(entries)
fmt.Println(entries)
}
Output: [alice: 90 bob: 85]
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.
Example ¶
package main
import (
"fmt"
"strings"
"github.com/binaryphile/fluentfp/kv"
)
func main() {
m := map[string]string{"greeting": "hello", "name": "world"}
upper := kv.MapValues(m, strings.ToUpper)
// Print specific keys for deterministic output.
fmt.Println(upper["greeting"], upper["name"])
}
Output: HELLO WORLD
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.
Example ¶
package main
import (
"fmt"
"github.com/binaryphile/fluentfp/kv"
)
func main() {
defaults := map[string]string{"host": "localhost", "port": "8080"}
overrides := map[string]string{"port": "9090", "debug": "true"}
merged := kv.Merge(defaults, overrides)
// Print specific keys for deterministic output.
fmt.Println(merged["host"], merged["port"], merged["debug"])
}
Output: localhost 9090 true
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. Returns empty map for nil input.
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. Returns empty map for nil input.
func ToPairs ¶ added in v0.41.0
ToPairs converts a map to a slice of key-value pairs. Order is not guaranteed (map iteration order).
func Values ¶
func Values[K comparable, V any](m map[K]V) base.Mapper[V]
Values extracts the values of m as a Mapper for further transformation. Order is not guaranteed (map iteration order). Shortcut for From(m).Values().
Example ¶
package main
import (
"fmt"
"sort"
"github.com/binaryphile/fluentfp/kv"
)
func main() {
m := map[string]int{"alice": 90, "bob": 85, "carol": 95}
vals := kv.Values(m)
sort.Ints(vals)
fmt.Println(vals)
}
Output: [85 90 95]
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