GitHub - samber/lo: ? A Lodash-style Go library based on Go 1.18+ Generics (map... - JOYK Joy of Geek, Geek News, Link all geek

README.md

lo is a Lodash-style Go library based on Go 1.18+ Generics.

This project have started as an experiment to discover generics implementation. It may look like Lodash in some aspects. I used to code with the awesome go-funk package, but it uses reflection and therefore is not typesafe.

As expected, benchmarks demonstrate that generics will be much faster than implementations based on reflect stdlib package. Benchmarks also shows similar performances to pure for loops. See below.

In the future, 5 to 10 helpers will overlap with those coming into the Go standard library (under package names slices and maps). Anyway I feel this library legitimate to offer many more such useful abstractions.

Why this name?

I wanted a short name, similar to "Lodash", and no Go package currently use this name.

Install

go get github.com/samber/lo

Usage

You can import lo using a basic statement:

import (
    "github.com/samber/lo"
    lop "github.com/samber/lo/parallel"
)

Then use one of the helpers below:

names := lo.Uniq[string]([]string{"Samuel", "Marc", "Samuel"})
// []string{"Samuel", "Marc"}

Spec

GoDoc: https://godoc.org/github.com/samber/lo

Supported helpers for slices:

Filter
Reduce
ForEach
UniqBy
GroupBy
Chunk
PartitionBy
Flatten
Shuffle
Reverse
ToMap

Supported helpers for maps:

Values
Entries
FromEntries
Assign (maps merge)

Supported helpers for tuples:

Zip2 -> Zip9
Unzip2 -> Unzip9

Supported intersection helpers:

Contains
Every
Intersect
Difference

Supported search helpers:

IndexOf
LastIndexOf

Other functional programming helpers:

Ternary (1 line if/else statement)
If / ElseIf / Else
Switch / Case / Default
ToPtr
ToSlicePtr

Constraints:

Clonable

Manipulates a slice and transforms it to a slice of another type:

import "github.com/samber/lo"

lo.Map[int64, string]([]int64{1, 2, 3, 4}, func(x int64, _ int) string {
    return strconv.FormatInt(x, 10)
})
// []string{"1", "2", "3", "4"}

Parallel processing: like lo.Map(), but mapper is called in goroutine. Results are returned in the same order.

import lop "github.com/samber/lo/parallel"

lop.Map[int64, string]([]int64{1, 2, 3, 4}, func(x int64, _ int) string {
    return strconv.FormatInt(x, 10)
}, 2)
// []string{"1", "2", "3", "4"}

Filter

Iterates over elements of collection, returning an array of all elements predicate returns truthy for.

even := lo.Filter[int]([]int{1, 2, 3, 4}, func(x int, _ int) bool {
    return x%2 == 0
})
// []int{2, 4}

Contains

Returns true if an element is present in a collection.

present := lo.Contains[int]([]int{0, 1, 2, 3, 4, 5}, 5)
// true

Reduce

Reduces collection to a value which is the accumulated result of running each element in collection through accumulator, where each successive invocation is supplied the return value of the previous.

sum := lo.Reduce[int, int]([]int{1, 2, 3, 4}, func(agg int, item int, _ int) int {
    return agg + item
}, 0)
// 10

ForEach

Iterates over elements of collection and invokes iteratee for each element.

import "github.com/samber/lo"

lo.ForEach[string]([]string{"hello", "world"}, func(x string, _ int) {
    println(x)
})
// prints "hello\nworld\n"

Parallel processing: like lo.ForEach(), but callback is called in goroutine.

import lop "github.com/samber/lo/parallel"

lop.ForEach[string]([]string{"hello", "world"}, func(x string, _ int) {
    println(x)
})
// prints "hello\nworld\n" or "world\nhello\n"

Returns a duplicate-free version of an array, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array.

uniqValues := lo.Uniq[int]([]int{1, 2, 2, 1})
// []int{1, 2}

UniqBy

Returns a duplicate-free version of an array, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array. It accepts iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed.

uniqValues := lo.UniqBy[int, int]([]int{0, 1, 2, 3, 4, 5}, func(i int) int {
    return i%3
})
// []int{0, 1, 2}

GroupBy

Returns an object composed of keys generated from the results of running each element of collection through iteratee.

groups := GroupBy[int, int]([]int{0, 1, 2, 3, 4, 5}, func(i int) int {
    return i%3
})
// map[int][]int{0: []int{0, 3}, 1: []int{1, 4}, 2: []int{2, 5}}

Parallel processing: like lo.GroupBy(), but callback is called in goroutine.

import lop "github.com/samber/lo/parallel"

lop.GroupBy[int, int]([]int{0, 1, 2, 3, 4, 5}, func(i int) int {
    return i%3
})
// map[int][]int{0: []int{0, 3}, 1: []int{1, 4}, 2: []int{2, 5}}

Chunk

Returns an array of elements split into groups the length of size. If array can't be split evenly, the final chunk will be the remaining elements.

lo.Chunk[int]([]int{0, 1, 2, 3, 4, 5}, 2)
// [][]int{{0, 1}, {2, 3}, {4, 5}}

lo.Chunk[int]([]int{0, 1, 2, 3, 4, 5, 6}, 2)
// [][]int{{0, 1}, {2, 3}, {4, 5}, {6}}

lo.Chunk[int]([]int{}, 2)
// [][]int{}

lo.Chunk[int]([]int{0}, 2)
// [][]int{{0}}

PartitionBy

Returns an array of elements split into groups. The order of grouped values is determined by the order they occur in collection. The grouping is generated from the results of running each element of collection through iteratee.

partitions := lo.PartitionBy[int, string]([]int{-2, -1, 0, 1, 2, 3, 4, 5}, func(x int) string {
    if x < 0 {
        return "negative"
    } else if x%2 == 0 {
        return "even"
    }
    return "odd"
})
// [][]int{{-2, -1}, {0, 2, 4}, {1, 3, 5}}

Parallel processing: like lo.PartitionBy(), but callback is called in goroutine. Results are returned in the same order.

import lop "github.com/samber/lo/parallel"

partitions := lo.PartitionBy[int, string]([]int{-2, -1, 0, 1, 2, 3, 4, 5}, func(x int) string {
    if x < 0 {
        return "negative"
    } else if x%2 == 0 {
        return "even"
    }
    return "odd"
})
// [][]int{{-2, -1}, {0, 2, 4}, {1, 3, 5}}

Flatten

Returns an array a single level deep.

flat := lo.Flatten[int]([][]int{{0, 1}, {2, 3, 4, 5}})
// []int{0, 1, 2, 3, 4, 5}

Shuffle

Returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.

randomOrder := lo.Shuffle[int]([]int{0, 1, 2, 3, 4, 5})
// []int{0, 1, 2, 3, 4, 5}

Reverse

Reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.

reverseOder := lo.Reverse[int]([]int{0, 1, 2, 3, 4, 5})
// []int{5, 4, 3, 2, 1, 0}

Fills elements of array with initial value.

type foo struct {
	bar string
}

func (f foo) Clone() foo {
	return foo{f.bar}
}

initializedSlice := lo.Fill[foo]([]foo{foo{"a"}, foo{"a"}}, foo{"b"})
// []foo{foo{"b"}, foo{"b"}}

ToMap

Transforms a slice or an array of structs to a map based on a pivot callback.

m := lo.ToMap[int, string]([]string{"a", "aa", "aaa"}, func(str string) int {
    return len(str)
})
// map[int]string{1: "a", 2: "aa", 3: "aaa"}

Creates an array of the map keys.

keys := lo.Keys[string, int](map[string]int{"foo": 1, "bar": 2})
// []string{"bar", "foo"}

Values

Creates an array of the map values.

values := lo.Values[string, int](map[string]int{"foo": 1, "bar": 2})
// []int{1, 2}

Entries

Transforms a map into array of key/value pairs.

entries := lo.Entries[string, int](map[string]int{"foo": 1, "bar": 2})
// []lo.Entry[string, int]{
//     {
//         Key: "foo",
//         Value: 1,
//     },
//     {
//         Key: "bar",
//         Value: 2,
//     },
// }

FromEntries

Transforms an array of key/value pairs into a map.

m := lo.FromEntries[string, int]([]lo.Entry[string, int]{
    {
        Key: "foo",
        Value: 1,
    },
    {
        Key: "bar",
        Value: 2,
    },
})
// map[string]int{"foo": 1, "bar": 2}

Assign

Merges multiple maps from left to right.

mergedMaps := lo.Assign[string, int](
    map[string]int{"a": 1, "b": 2},
    map[string]int{"b": 3, "c": 4},
)
// map[string]int{"a": 1, "b": 3, "c": 4}

Zip2 -> Zip9

Zip creates a slice of grouped elements, the first of which contains the first elements of the given arrays, the second of which contains the second elements of the given arrays, and so on.

When collections have different size, the Tuple attributes are filled with zero value.

tuples := lo.Zip2[string, int]([]string{"a", "b"}, []int{1, 2})
// []Tuple2[string, int]{{A: "a", B: 1}, {A: "b", B: 2}}

Unzip2 -> Unzip9

Unzip accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

a, b := lo.Unzip2[string, int]([]Tuple2[string, int]{{A: "a", B: 1}, {A: "b", B: 2}})
// []string{"a", "b"}
// []int{1, 2}

Every

Returns true if all elements of a subset are contained into a collection.

ok := lo.Every[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true

ko := lo.Every[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 6})
// false

Returns true if at least 1 element of a subset is contained into a collection.

ok := lo.Some[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true

ko := lo.Some[int]([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// false

Intersect

Returns the intersection between two collections.

result1 := lo.Intersect[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// []int{0, 2}

result2 := lo.Intersect[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 6}
// []int{0}

result3 := lo.Intersect[int]([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// []int{}

Difference

Returns the difference between two collections.

The first value is the collection of element absent of list2.
The second value is the collection of element absent of list1.

left, right := lo.Difference[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2, 6})
// []int{1, 3, 4, 5}, []int{6}

left, right := Difference[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 1, 2, 3, 4, 5})
// []int{}, []int{}

IndexOf

Returns the index at which the first occurrence of a value is found in an array or return -1 if the value cannot be found.

found := lo.IndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 2)
// 2

notFound := lo.IndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 6)
// -1

LastIndex

Returns the index at which the last occurrence of a value is found in an array or return -1 if the value cannot be found.

found := lo.LastIndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 2)
// 4

notFound := lo.LastIndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 6)
// -1

Search an element in a slice based on a predicate. It returns element and true if element was found.

str, ok := lo.Find[string]([]string{"a", "b", "c", "d"}, func(i string) bool {
    return i == "b"
})
// "b", true

str, ok := lo.Find[string]([]string{"foobar"}, func(i string) bool {
    return i == "b"
})
// "", false

Search the minimum value of a collection.

min := lo.Min[int]([]int{1, 2, 3})
// 1

min := lo.Min[int]([]int{})
// 0

Search the maximum value of a collection.

min := lo.Max[int]([]int{1, 2, 3})
// 3

min := lo.Max[int]([]int{})
// 0

Returns the last element of a collection or error if empty.

last, err := lo.Last[int]([]int{1, 2, 3})
// 3

Returns the element at index nth of collection. If nth is negative, the nth element from the end is returned. An error is returned when nth is out of slice bounds.

nth, err := lo.Nth[int]([]int{0, 1, 2, 3}, 2)
// 2

nth, err := lo.Nth[int]([]int{0, 1, 2, 3}, -2)
// 2

Ternary

A 1 line if/else statement.

result := lo.Ternary[string](true, "a", "b")
// "a"

result := lo.Ternary[string](false, "a", "b")
// "b"

If / ElseIf / Else

result := lo.If[int](true, 1).
    ElseIf(false, 2).
    Else(3)
// 1

result := lo.If[int](false, 1).
    ElseIf(true, 2).
    Else(3)
// 2

result := lo.If[int](false, 1).
    ElseIf(false, 2).
    Else(3)
// 3

Switch / Case / Default

result := lo.Switch[int, string](1).
    Case(1, "1").
    Case(2, "2").
    Default("3")
// "1"

result := lo.Switch[int, string](2).
    Case(1, "1").
    Case(2, "2").
    Default("3")
// "2"

result := lo.Switch[int, string](42).
    Case(1, "1").
    Case(2, "2").
    Default("3")
// "3"

Using callbacks:

result := lo.Switch[int, string](1).
    CaseF(1, func() string {
        return "1"
    }).
    CaseF(2, func() string {
        return "2"
    }).
    DefaultF(func() string {
        return "3"
    })
// "1"

ToPtr

Returns a pointer copy of value.

ptr := lo.ToPtr[string]("hello world")
// *string{"hello world"}

ToSlicePtr

Returns a slice of pointer copy of value.

ptr := lo.ToSlicePtr[string]([]string{"hello", "world"})
// []*string{"hello", "world"}

Benchmark

We executed a simple benchmark with the a dead-simple lo.Map loop:

See the full implementation here.

_ = lo.Map[int64](arr, func(x int64, i int) string {
    return strconv.FormatInt(x, 10)
})

Result:

Here is a comparison between lo.Map, lop.Map, go-funk library and a simple Go for loop.

$ go test -benchmem -bench ./...
goos: linux
goarch: amd64
pkg: github.com/samber/lo
cpu: Intel(R) Core(TM) i5-7267U CPU @ 3.10GHz
BenchmarkMap/lo.Map-8         	       8	 131041218 ns/op	39998055 B/op	 1000001 allocs/op
BenchmarkMap/lop.Map-8        	       2	 509805437 ns/op	120018304 B/op	 3000214 allocs/op
BenchmarkMap/reflect-8        	       2	 840512374 ns/op	170325888 B/op	 4000042 allocs/op
BenchmarkMap/for-8            	       9	 127074794 ns/op	39998040 B/op	 1000001 allocs/op
PASS
ok  	github.com/samber/lo	7.531s

lo.Map is way faster (x7) than go-funk, a relection-based Map implementation.
lo.Map have the same allocation profile than for.
lo.Map is 4% slower than for.
lop.Map is slower than lo.Map because it implies more memory allocation and locks. lop.Map will be usefull for long-running callbacks, such as i/o bound processing.
for beats other implementations for memory and CPU.

Contributing

Ping me on twitter @samuelberthe (DMs, mentions, whatever :))
Fork the project
Fix open issues or request new features

Don't hesitate ;)

Install go 1.18

make go1.18beta1

If your OS currently not default to Go 1.18, replace BIN=go by BIN=go1.18beta1 in the Makefile.

With Docker

docker-compose run --rm dev

Without Docker

# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test

Authors

Samuel Berthe

Show your support

Give a if this project helped you!

License

This project is MIT licensed.

GitHub - samber/lo: ? A Lodash-style Go library based on Go 1.18+ Generics (map...