You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/about.md
+55-24Lines changed: 55 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,44 +8,58 @@ sidebar_position: 0
8
8
9
9
**samber/lo** is a Lodash-style utility library for Go that brings the power and convenience of functional programming helpers to the Go ecosystem. Born from the need for more expressive and concise data manipulation, `lo` fills the gaps between Go's standard library and the complex data transformations that modern applications require.
10
10
11
-
## Why `lo` Exists
11
+
12
+
13
+
**Why `lo` Exists**
12
14
13
15
Go's standard library is excellent for many use cases, but it lacks the higher-level abstractions that developers coming from JavaScript, Python, or other languages often miss. While Go 1.18 introduced generics, the standard library's `slices` and `maps` packages only cover about 5-10 basic helpers. `lo` provides hundreds of additional utilities that make everyday programming tasks more enjoyable and less error-prone.
14
16
15
-
## Design Philosophy
17
+
**The name "lo"**
16
18
17
-
### 1. **Type Safety Through Generics**
18
-
Every function in `lo` is built on Go 1.18+ generics, ensuring compile-time type safety without sacrificing flexibility. This eliminates runtime type assertions and reduces bugs.
19
+
I wanted a short and memorable name, similar to "Lodash". It's easy to type and no existing Go package was using this name, making it unique in the ecosystem.
19
20
20
-
### 2. **Immutable by Default**
21
-
The main `lo` package follows functional programming principles by returning new collections rather than modifying existing ones. This predictability makes code easier to reason about and test.
21
+
## 🚀 Install
22
22
23
-
### 3. **Performance When Needed**
24
-
For performance-critical scenarios, `lo` offers specialized packages:
25
-
-`lo/mutable`: In-place operations that modify collections directly
26
-
-`lo/parallel`: Concurrent processing with built-in worker pools
27
-
-`lo/it`: Lazy evaluation using Go 1.23+ iterators
23
+
```go
24
+
go get -u github.com/samber/lo@v1
25
+
```
28
26
29
-
### 4. **Minimal Dependencies**
30
-
`lo` has zero dependencies outside the Go standard library. This choice ensures reliability, security, and avoids dependency hell.
27
+
This library is v1 and follows SemVer strictly.
28
+
29
+
No breaking changes will be made to exported APIs before v2.0.0.
30
+
31
+
This library has no dependencies outside the Go standard library.
32
+
33
+
## 💡 Usage
34
+
35
+
You can import lo using:
31
36
32
-
## Key Design Decisions
37
+
```go
38
+
import (
39
+
"github.com/samber/lo"
40
+
lop "github.com/samber/lo/parallel"
41
+
lom "github.com/samber/lo/mutable"
42
+
)
43
+
```
33
44
34
-
### Function Naming
35
-
Functions follow familiar patterns from Lodash and other functional libraries, making the learning curve gentle for developers with experience in other ecosystems.
45
+
Then use one of the helpers below:
36
46
37
-
### Play Links
38
-
Every function includes a "Play" link to the Go Playground, allowing developers to quickly experiment and understand behavior without setting up a local environment.
Many functions accept variadic parameters (like `Keys()` accepting multiple maps), providing flexibility while maintaining type safety.
52
+
### Tips for lazy developers
42
53
43
-
### Slice Type Parameters
44
-
Functions use `~[]T` constraints to accept any slice type, including named slice types, not just `[]T`. This design choice makes the library more flexible in real-world usage.
54
+
I cannot recommend it, but in case you are too lazy for repeating lo. everywhere, you can import the entire library into the namespace.
45
55
46
-
## The Name "lo"
56
+
```go
57
+
import (
58
+
. "github.com/samber/lo"
59
+
)
60
+
```
47
61
48
-
The name was chosen to be short and memorable, similar to "Lodash". It's easy to type and no existing Go package was using this name, making it unique in the ecosystem.
62
+
I take no responsibility for this junk. 😁 💩
49
63
50
64
## Community and Evolution
51
65
@@ -66,3 +80,20 @@ Use `lo` when you need to:
66
80
- Process data in parallel or with lazy evaluation
67
81
68
82
For simple operations, Go's standard library may suffice. But when you find yourself writing nested loops or complex data manipulation logic, `lo` provides the abstractions you need.
83
+
84
+
## Design Philosophy
85
+
86
+
### 1. **Type Safety Through Generics**
87
+
Every function in `lo` is built on Go 1.18+ generics, ensuring compile-time type safety without sacrificing flexibility. This eliminates runtime type assertions and reduces bugs.
88
+
89
+
### 2. **Immutable by Default**
90
+
The main `lo` package follows functional programming principles by returning new collections rather than modifying existing ones. This predictability makes code easier to reason about and test.
91
+
92
+
### 3. **Performance When Needed**
93
+
For performance-critical scenarios, `lo` offers specialized packages:
94
+
-`lo/mutable`: In-place operations that modify collections directly
95
+
-`lo/parallel`: Concurrent processing with built-in worker pools
96
+
-`lo/it`: Lazy evaluation using Go 1.23+ iterators
97
+
98
+
### 4. **Minimal Dependencies**
99
+
`lo` has zero dependencies outside the Go standard library. This choice ensures reliability, security, and avoids dependency hell.
Hey! We are happy to have you as a new contributor. ✌️
10
+
11
+
For your first contribution please follow some guidelines:
12
+
13
+
## Function Naming
14
+
Function naming: helpers must be self-explanatory and respect standards (other languages, libraries...). Feel free to suggest many names in your contributions.
15
+
16
+
## Variadic functions
17
+
Many functions accept variadic parameters (like `lo.Keys(...map[K]V)` accepting multiple maps), providing flexibility while maintaining type safety.
18
+
19
+
## Slice type Parameters
20
+
Functions use `~[]T` constraints to accept any slice type, including named slice types, not just `[]T`. This design choice makes the library more flexible in real-world usage.
21
+
22
+
## Variants
23
+
When applicable, some functions can be added to sub-package as well: `mutable`, `it` and `parallel`. Add a documentation for each helper.
24
+
25
+
## Testing
26
+
We try to maintain code coverage above 90%.
27
+
28
+
## Benchmark and performance
29
+
Write performant helpers and limit extra memory consumption. Build an helper for general purpose and don't optimize for a particular use-case.
30
+
31
+
Feel free to write benchmarks.
32
+
33
+
Iterators can be unbounded and run for a very long time. If you expect a big memory footprint, please warn developers in the function comment.
34
+
35
+
## Documentation
36
+
Functions must be properly commented, with a Go Playground link. New helpers must be created with a markdown documentation in `docs/data/`. In markdown header, please link to similar helpers (and update other markdowns accordingly).
37
+
38
+
## Examples
39
+
Every function includes a "Play" link to the Go Playground, allowing developers to quickly experiment and understand behavior without setting up a local environment.
40
+
41
+
Please add an example of your helper in the file named `xxxx_example_test.go`. It will be available from Godoc website: https://pkg.go.dev/github.com/samber/lo
0 commit comments