samber-lo

name	samber-lo
description	Use when writing or refactoring Go collection/pointer helper code in OpenMeter, especially when choosing between standard library slices/maps helpers and github.com/samber/lo for cloning, copying, equality, sorting, pointer literals, slice-to-map transforms, map keys/values, mapping, filtering, grouping, uniqueness, set-like conversions, and map entry transformations.
user-invocable	true
argument-hint	[collection transformation or lo helper question]
allowed-tools	Read, Edit, Write, Bash, Grep, Glob

samber/lo

Use standard library collection helpers first when they express the operation directly, and use github.com/samber/lo for small, local collection transformations when it makes the intent clearer than a hand-written loop. OpenMeter pins github.com/samber/lo v1.53.0 in go.mod.

Imports

import "maps"
import "slices"
import "github.com/samber/lo"

Do not use dot imports. Do not reach for lo/parallel, lo/mutable, or lo/it unless the surrounding package already uses that subpackage or the task explicitly needs it.

Standard Library First

Prefer slices for operations the standard library already names clearly:

• slices.Clone(s) for defensive slice copies instead of append([]T(nil), s...).
• slices.Contains(s, v) for membership checks on short or already-available slices.
• slices.Sort, slices.SortFunc, and slices.SortStableFunc before comparing, logging, serializing, or asserting on order.
• slices.Equal and slices.EqualFunc for equality checks.
• slices.Concat(a, b, c) for concatenating known slices.
• slices.Compact after sorting when normalizing a slice.

Prefer maps for direct map operations:

• maps.Clone(m) for defensive copies.
• maps.Copy(dst, src) when merging maps.
• maps.Equal and maps.EqualFunc for equality checks.
• maps.Keys(m) and maps.Values(m) when the iterator result is acceptable; collect or sort when a slice is required or order matters.

Prefer lo.ToPtr(...), lo.FromPtr(...), and lo.FromPtrOr(...) for pointer literals and pointer defaults. Avoid local wrappers such as ptr, loPtr, must, or loMust.

Common Helpers

For slice transforms:

• lo.Map(items, func(item T, index int) R) converts []T to []R.
• lo.Filter(items, func(item T, index int) bool) keeps matching items.
• lo.FilterMap(items, func(item T, index int) (R, bool)) filters and maps in one pass.
• lo.Uniq(items) and lo.UniqBy(items, func(item T) K) remove duplicates.
• lo.GroupBy(items, func(item T) K) returns map[K][]T.
• lo.GroupByMap(items, func(item T) (K, V)) returns map[K][]V.

For slice-to-map work:

• lo.KeyBy(items, func(item T) K) returns map[K]T.
• lo.SliceToMap(items, func(item T) (K, V)) returns map[K]V; lo.Associate is the same operation, but prefer SliceToMap for readability.
• lo.FilterSliceToMap(items, func(item T) (K, V, bool)) returns map[K]V while skipping items.
• lo.Keyify(items) returns map[T]struct{} for set-like membership.

For map work:

• lo.Keys(m) and lo.Values(m) return slices.
• lo.UniqKeys(m1, m2) and lo.UniqValues(m1, m2) combine maps while removing duplicates.
• lo.MapKeys(m, func(value V, key K) R) changes key type while preserving values.
• lo.MapValues(m, func(value V, key K) R) changes values while preserving keys.
• lo.MapEntries(m, func(key K, value V) (K2, V2)) changes both keys and values.
• lo.MapToSlice(m, func(key K, value V) R) converts a map to a slice.
• lo.FilterMapToSlice(m, func(key K, value V) (R, bool)) filters and maps a map into a slice.
• lo.PickBy, lo.OmitBy, lo.FilterKeys, and lo.FilterValues are useful when only part of a map is needed.

Use *Err variants such as MapErr, KeyByErr, GroupByMapErr, MapValuesErr, or MapToSliceErr when the callback can fail and the first error should stop the transform.

For slice-wide invariants where the exact offending element is not important, prefer collecting distinct values with lo.Map plus lo.Uniq and validating cardinality over stateful "first seen value" loops.

Correctness Notes

• Duplicate keys in KeyBy, SliceToMap, MapKeys, and MapEntries overwrite earlier entries; the last value wins.
• Map iteration order is not stable. Sort keys or results before comparing, logging, serializing, or asserting on order.
• Callback argument order differs by helper: slice helpers usually pass (item, index), map helpers usually pass (value, key) for MapKeys/MapValues and (key, value) for MapEntries/MapToSlice.
• Prefer a plain for loop when the transform has branching business rules, context-aware calls, transaction-sensitive operations, side effects, or multi-step error handling.
• Keep code inline for tiny transformations; do not add pass-through wrappers around lo helpers unless the wrapper name captures a domain rule that is not obvious from the helper call.

Examples

ids := lo.Map(customers, func(customer customer.Customer, _ int) string {
    return customer.ID
})

byID := lo.KeyBy(customers, func(customer customer.Customer) string {
    return customer.ID
})

namesByID := lo.SliceToMap(customers, func(customer customer.Customer) (string, string) {
    return customer.ID, customer.Name
})

activeNamesByID := lo.FilterSliceToMap(customers, func(customer customer.Customer) (string, string, bool) {
    return customer.ID, customer.Name, customer.Active
})

externalIDs := lo.Keys(externalIDByCustomerID)

apiByID := lo.MapValues(customerByID, func(customer customer.Customer, _ string) api.Customer {
    return mapCustomerToAPI(customer)
})