mirror of
https://github.com/rjNemo/underscore
synced 2026-06-06 02:26:42 +00:00
Ruidy
7580836815
Update README to use the latest version in install instructions, expand the list of available API functions, and add documentation for new utilities and subpackages. Improves clarity and completeness for users.
212 lines
5.3 KiB
Markdown
212 lines
5.3 KiB
Markdown
# \_Underscore
|
|
|
|
|
|
[](https://pkg.go.dev/github.com/rjNemo/underscore)
|
|
|
|
|
|
[](https://www.bestpractices.dev/projects/9726)
|
|
|
|
|
|
|
|
`underscore` is a `Go` library providing useful functional programming helpers without
|
|
extending any built-in objects.
|
|
|
|
It is mostly a port from the `underscore.js` library based on generics brought by
|
|
`Go 1.18`.
|
|
|
|
## Usage
|
|
|
|
📚 Follow this link for the [documentation](https://underscore.onrender.com/).
|
|
|
|
Install the library using
|
|
|
|
```sh
|
|
go get github.com/rjNemo/underscore@latest
|
|
```
|
|
|
|
Please check out the [examples](examples) to see how to use the library.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
u "github.com/rjNemo/underscore"
|
|
)
|
|
|
|
func main() {
|
|
numbers := []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
|
|
// filter even numbers from the slice
|
|
evens := u.Filter(numbers, func(n int) bool { return n%2 == 0 })
|
|
// square every number in the slice
|
|
squares := u.Map(evens, func(n int) int { return n * n })
|
|
// reduce to the sum
|
|
res := u.Reduce(squares, func(n, acc int) int { return n + acc }, 0)
|
|
|
|
fmt.Println(res) // 120
|
|
}
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
These instructions will get you a copy of the project up and running on your local
|
|
machine for development and testing purposes.
|
|
|
|
### Prerequisites
|
|
|
|
You need at least `go1.24` for development. The project is shipped with a [Dockerfile](Dockerfile)
|
|
based on `go1.24`.
|
|
|
|
If you prefer local development, navigate to the [official
|
|
download page](https://go.dev/dl/) and install version `1.24` or beyond.
|
|
|
|
### Installing
|
|
|
|
First clone the repository
|
|
|
|
```sh
|
|
git clone https://github.com/rjNemo/underscore.git
|
|
```
|
|
|
|
Install dependencies
|
|
|
|
```sh
|
|
go mod download
|
|
```
|
|
|
|
And that's it.
|
|
|
|
## Tests
|
|
|
|
To run the unit tests, you can simply run:
|
|
|
|
```sh
|
|
make test
|
|
```
|
|
|
|
## Functions
|
|
|
|
`underscore` provides many of functions that support your favorite functional helpers
|
|
|
|
### Collections
|
|
|
|
- `All`
|
|
- `Any`
|
|
- `Chunk`
|
|
- `Contains`
|
|
- `ContainsBy`
|
|
- `Count`
|
|
- `Difference`
|
|
- `Drop`
|
|
- `Each`
|
|
- `Filter`
|
|
- `Find`
|
|
- `Flatmap`
|
|
- `GroupBy`
|
|
- `Intersection`
|
|
- `Join` / `JoinProject`
|
|
- `Last`
|
|
- `Map`
|
|
- `Max`
|
|
- `Min`
|
|
- `OrderBy`
|
|
- `Partition`
|
|
- `Range`
|
|
- `Reduce`
|
|
- `Sum` / `SumMap`
|
|
- `Unique`
|
|
- `UniqueBy`
|
|
- `UniqueInPlace`
|
|
- `Zip`
|
|
|
|
### Pipe
|
|
|
|
Calling `NewPipe` will cause all future method calls to return wrapped values. When
|
|
you've finished the computation, call `Value` to retrieve the final value.
|
|
|
|
Methods not returning a slice such as `Reduce`, `All`, `Any`, will break the `Chain`
|
|
and return `Value` instantly.
|
|
|
|
### Concurrency
|
|
|
|
- `ParallelMap(ctx, values, workers, fn)`: apply a function concurrently while preserving order and supporting context cancellation.
|
|
- `ParallelFilter(ctx, values, workers, fn)`: filter concurrently with order preserved and context support.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
u "github.com/rjNemo/underscore"
|
|
)
|
|
|
|
func main() {
|
|
out, err := u.ParallelMap(context.Background(), []int{1, 2, 3, 4}, 4,
|
|
func(ctx context.Context, n int) (int, error) { return n * n, nil },
|
|
)
|
|
fmt.Println(out, err) // [1 4 9 16] <nil>
|
|
}
|
|
```
|
|
|
|
```go
|
|
// ParallelFilter example
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
u "github.com/rjNemo/underscore"
|
|
)
|
|
|
|
func main() {
|
|
out, err := u.ParallelFilter(context.Background(), []int{1,2,3,4,5}, 3,
|
|
func(ctx context.Context, n int) (bool, error) { return n%2==0, nil },
|
|
)
|
|
fmt.Println(out, err) // [2 4] <nil>
|
|
}
|
|
```
|
|
|
|
### Utilities
|
|
|
|
- `Ternary`: conditional expression helper
|
|
- `ToPointer`: convert values to pointers
|
|
- `SortSliceASC` / `SortSliceDESC`: sort slices in ascending or descending order
|
|
- `Result`, `Ok`, `Err`, `ToResult`: Result type for error handling
|
|
- `Tuple`: generic tuple type for paired values
|
|
|
|
### Subpackages
|
|
|
|
- `maps.Keys(m)` / `maps.Values(m)`: extract keys or values from maps
|
|
- `maps.Map(m, fn)`: transform map entries
|
|
|
|
## Built With
|
|
|
|
- [Go](https://go.dev/) - Build fast, reliable, and efficient software at scale
|
|
|
|
## Contributing
|
|
|
|
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct,
|
|
and the process for submitting pull requests to us.
|
|
|
|
## Versioning
|
|
|
|
We use [SemVer](http://semver.org/) for versioning. For the versions available, see
|
|
the [tags on this repository](https://github.com/rjNemo/underscore/tags).
|
|
|
|
## Authors
|
|
|
|
- **Ruidy** - _Initial work_ - [Ruidy](https://github.com/rjNemo)
|
|
|
|
See also the list of [contributors](https://github.com/rjNemo/underscore/contributors)
|
|
who participated in this project.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md)
|
|
file for details
|
|
|
|
## Acknowledgments
|
|
|
|
This project is largely inspired by [Underscore.js](https://underscorejs.org/#)
|
|
library. Check out the original project if you don't already know it.
|