kv

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. 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] wraps a map for fluent operations. Filter and mapping methods take func(K, V) T predicates/transforms — filtering considers both key and value.

• Wrap: From
• Filter: KeepIf, RemoveIf — return Entries[K,V] for chaining
• Extract: Values, Keys — return Mapper[V]/Mapper[K] for slice chaining
• Transform (standalone): Map, MapValues, MapTo — standalone because Go methods can't introduce new type parameters
• Mapping: ToString, ToInt, ToFloat64, ToBool, ToAny, ToByte, ToError, ToFloat32, ToInt32, ToInt64, ToRune

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 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 MapValues[K comparable, V, V2 any](m map[K]V, fn func(V) V2) base.Entries[K, V2]
• func Values[K comparable, V any](m map[K]V) base.Mapper[V]
• type Entries
  • func From[K comparable, V any](m map[K]V) Entries[K, V]
• type MapperTo
  • func MapTo[T any, K comparable, V any](m map[K]V) MapperTo[T, K, V]

Functions

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. Use MapTo[T](m).Map(fn) when explicit type specification is needed. Order is not guaranteed (map iteration order).

func MapValues

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()).

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. Shortcut for From(m).Values().

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.

type MapperTo

type MapperTo[T any, K comparable, V any] = base.EntryMapper[T, K, V]

MapperTo wraps a map for cross-type transformation.

func MapTo

func MapTo[T any, K comparable, V any](m map[K]V) MapperTo[T, K, V]

MapTo wraps a map for transformation to type T. Usage: kv.MapTo[TargetType](m).Map(fn)