Golang Samber Lo

Package Guide

samber/lo ships five packages. Each serves a different performance/ergonomics trade-off.

Table of Contents

• Import Paths and Aliases

• lo — Core (Immutable)

• lo/parallel (lop) — Concurrent Transforms

• lo/mutable (lom) — In-Place Mutations

• lo/it (loi) — Lazy Iterators

• lo/exp/simd — Experimental SIMD

• Decision Flowchart

• Comparison Table

Import Paths and Aliases

import (
    "github.com/samber/lo"            // lo  — core, immutable
    "github.com/samber/lo/parallel"    // lop — concurrent transforms
    "github.com/samber/lo/mutable"     // lom — in-place mutations
    "github.com/samber/lo/it"          // loi — lazy iterators (Go 1.23+)
    "github.com/samber/lo/exp/simd"    // experimental SIMD
)

lo — Core (Immutable)

The default package. 300+ functions that return new collections without modifying inputs.

Mental model: Functional transforms like JavaScript's Array.prototype.map/filter/reduce, but type-safe via generics.

Characteristics:

• Every function allocates a new result slice/map — the input is never modified

• Safe for concurrent reads on the input while transforms run

• Composable: output of one function feeds directly into the next

Use when: Always start here. Only move to other packages when profiling reveals a measured bottleneck.

// Immutable — users slice is untouched
active := lo.Filter(users, func(u User, _ int) bool {
    return u.Active
})

lo/parallel (lop) — Concurrent Transforms

Parallel variants of core functions. Each element is processed in a separate goroutine with automatic worker pooling.

Available functions: Map, ForEach, Times, GroupBy, PartitionBy

Characteristics:

• Results preserve original order despite concurrent execution

• Internal goroutine pool manages concurrency (not configurable via API — one goroutine per element)

• Synchronization via sync.WaitGroup

Use when:

• CPU-bound transforms on large datasets (~1000+ items)

• Transform function is expensive (parsing, hashing, computing)

• Order must be preserved

Do NOT use when:

• Small datasets (<100 items) — goroutine creation overhead exceeds benefit

• I/O-bound work (HTTP calls, DB queries) — use errgroup with context cancellation instead

• Transform function is trivial (field access, type cast) — lo.Map is faster

// CPU-heavy: parse 10k JSON documents in parallel
parsed := lop.Map(rawDocs, func(doc []byte, _ int) *Document {
    return parseDocument(doc) // expensive operation
})

Diagnose: go tool pprof -cpu — if transform function dominates CPU profile and dataset is large, lop helps.

lo/mutable (lom) — In-Place Mutations

Modify the original slice directly. Zero allocation overhead.

Available functions: Filter, Map, Shuffle, Reverse, Replace

Characteristics:

• Modifies the input slice — callers must expect side effects

• lom.Filter shortens the slice (removes non-matching elements in-place)

• lom.Map transforms elements in-place (preserves length)

• Uses Fisher-Yates for Shuffle

• Not safe for concurrent access to the source slice

Use when:

• go tool pprof -alloc_objects confirms allocation pressure from lo.Filter/lo.Map

• Working with very large slices where GC pressure is measurable

• You explicitly want to modify the source and won't need the original

Do NOT use when:

• Multiple goroutines read the same slice

• You need the original data after the transform

• Code readability matters more than micro-optimization

// In-place filter — modifies 'items' directly
items = lom.Filter(items, func(item Item, _ int) bool {
    return item.Price > 0
})

Diagnose: 1- go tool pprof -alloc_objects — find which lo.* calls allocate the most 2- go build -gcflags="-m" — check if result slices escape to heap

lo/it (loi) — Lazy Iterators

Go 1.23+ iterator support with lazy evaluation. Transforms are deferred until consumed — no intermediate slices allocated.

Characteristics:

• Uses range-over-func (Go 1.23+)

• Composable pipelines: loi.Map → loi.Filter → loi.Take runs as a single pass

• No intermediate slice allocations between pipeline stages

• Modules: channel, find, intersect, map, math, seq, string, tuples, type_manipulation

Use when:

• Chaining 3+ transforms on large datasets — eliminates intermediate allocations

• Processing sequences where you only need a subset (lazy Take/TakeWhile)

• Building composable pipelines with range-over-func

Do NOT use when:

• Go version < 1.23

• Simple single-step transforms — lo.Map is clearer and has negligible overhead

• You need random access to intermediate results

// Lazy pipeline — no intermediate slices allocated
for name := range loi.Map(
    loi.Filter(users, func(u User) bool { return u.Active }),
    func(u User) string { return u.Name },
) {
    fmt.Println(name)
}

lo/exp/simd — Experimental SIMD

SIMD (Single Instruction Multiple Data) optimized operations for numeric types on amd64.

Use when: Bulk numeric operations after benchmarking confirms the bottleneck. Very specialized.

Warning: This package is experimental and not covered by semver stability guarantees, so its API may break between minor versions. Do not use in production without version pinning.

Decision Flowchart

Start with lo.Map/Filter/Reduce (immutable, safe)
  │
  ├─ Profiler shows allocation pressure?
  │    └─ Yes → Switch specific calls to lom (mutable)
  │
  ├─ Profiler shows CPU-bound transform is slow?
  │    └─ Yes + large dataset → Switch to lop (parallel)
  │
  ├─ Chaining 3+ transforms with intermediate allocations?
  │    └─ Yes + Go 1.23+ → Switch to loi (lazy iterators)
  │
  └─ Need reactive/streaming over infinite events?
       └─ Yes → Use samber/ro instead (different library)

Comparison Table