Collection of Functional Programming helpers powered by Golang 1.18+ generics

# fp-go

[![Go Reference](https://pkg.go.dev/badge/github.com/repeale/fp-go.svg)](https://pkg.go.dev/github.com/repeale/fp-go)
[![Go Report](https://goreportcard.com/badge/github.com/repeale/fp-go)](https://goreportcard.com/badge/github.com/repeale/fp-go)
[![codecov](https://codecov.io/gh/repeale/fp-go/branch/main/graph/badge.svg?token=ORP8NR634Q)](https://codecov.io/gh/repeale/fp-go)

Fp-go is a collection of Functional Programming helpers powered by Golang [1.18](https://tip.golang.org/doc/go1.18)+ [generics](https://tip.golang.org/doc/go1.18#generics).

**Inspired by**

- [fp-ts](https://github.com/gcanti/fp-ts)


 <img
 width="500"
 height="313"
 src="https://user-images.githubusercontent.com/9580458/162070974-4367f4b8-bb3d-451c-8114-dd578bad4e46.png"
 >


## Contents

- [Install](#install)
- [Features](#features)
 - [Currying](#currying)
 - [Variations](#variations)
- [Helpers](#helpers)
 - [Every](#every)
 - [Filter](#filter)
 - [Flat](#flat)
 - [FlatMap](#flatmap)
 - [Map](#map)
 - [Reduce](#reduce)
 - [Some](#some)
 - [Compose](#compose)
 - [Pipe](#pipe)
 - [Curry](#curry)
- [Structs](#structs)
 - [Option](#option)
 - [Either](#either)

## Install

Requires go 1.18+

```sh
go get github.com/repeale/fp-go
```

## Features

- [Currying](#currying)
- [Variations](#variations)

### Currying

By default! Data last!

```go
func isPositive(x int) bool {
	return x > 0
}

func main() {
 filterPositive := fp.Filter(isPositive)
 numbers := []int{1, 2, 3, 4, 5}

 positives := filterPositive(numbers)
}
```

### Variations

Variations allows you to get different parameters in the callback function so that you get only only what is really needed.

[Default](#default) \
[WithIndex](#withindex) \
[WithSlice](#withslice)

#### Default

Only the current item is available:

```go
fp.Map[int, string](func(x int) { ... })
```

#### WithIndex

Current element and index are available:

```go
fp.MapWithIndex[int, string](func(x int, i int) { ... })
```

#### WithSlice

Current element, index and the whole slice are available:

```go
fp.MapWithSlice[int, string](func(x int, i int, xs: []int) { ... })
```

## Helpers

#### Every

Determines whether all the members of an array satisfy the specified test.

Variations `EveryWithIndex` and `EveryWithSlice`

```go
fp.Every(func(x int) bool { return x > 0 })([]int{1, 2, 3})

// => true
```

#### Filter

Returns the elements of an array that meet the condition specified in a callback function.

Variations `FilterWithIndex` and `FilterWithSlice`

```go
fp.Filter(func(x int) bool { return x > 0 })([]int{-1, 2, -3, 4})

// => []int{2, 4}
```

#### Flat

Returns a new array with all sub-array elements concatenated into it.

```go
fp.Flat([][]int{{1, 2}, {3, 4}})

// => []int{1, 2, 3, 4}
```

#### FlatMap

Calls a defined callback function on each element of an array. Then, flattens the result into a new array. This is identical to a map followed by flat.

Variations `FlatMapWithIndex` and `FlatMapWithSlice`

```go
fp.FlatMap(func(x int) []int { return []int{x, x} })([]int{1, 2})

// => []int{1, 1, 2, 2}
```

#### Map

Calls a defined callback function on each element of an array, and returns an array that contains the results.

Variations `MapWithIndex` and `MapWithSlice`

```go
fp.Map(func(x int64) string {
 return strconv.FormatInt(x, 10)
})([]int64{1, 2, 3})

// => []string{"1", "2", "3"}
```

#### Reduce

Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

Variations `ReduceWithIndex` and `ReduceWithSlice`

```go
fp.Reduce(func(acc int, curr int) int { return acc + curr }, 0)([]int{1, 2, 3})

// => 6
```

#### Some

Determines whether the specified callback function returns true for any element of an array.

Variations `SomeWithIndex` and `SomeWithSlice`

```go
fp.Some(func(x int) bool { return x < 0 })([]int{1, 2, 3})

// => false
```

---

#### Compose

Performs right-to-left function composition.

Variations `Compose2` to `Compose16` stating the number of functions you are going to compose.

```go
func isPositive(x int) bool {
	return x > 0
}

func sumTwo(x int) int {
	return x + 2
}

Compose2(fp.Filter(isPositive), fp.Map(sumTwo))([]int{1, 2, 3, -1})

// => []int{3, 4, 5, 1}
```

#### Pipe

Performs left-to-right function composition.

Variations `Pipe2` to `Pipe16` stating the number of functions you are going to compose.

```go
func isPositive(x int) bool {
	return x > 0
}

func sumTwo(x int) int {
	return x + 2
}

Pipe2(fp.Filter(isPositive), fp.Map(sumTwo))([]int{1, 2, 3, -1})

// => []int{3, 4, 5}
```

#### Curry

Allow to transfrom a function that receives a certain amount of params in single functions that take one single param each.

Variations `Curry2` to `Curry16` stating the number of params will be curried individually.

```go
curryedSum := Curry2(func(a int, b int) int { return a + b })
curryedSum(1)(2)
```

## Structs

#### Option

Option represents encapsulation of an optional value, it might be used as the return type of functions which may or may not return a meaningful value when they are applied.

Option exports `Some`, `None`, `IsSome`, `IsNone`, `Chain`, `Exists`, `Flatten`, `FromError`, `FromErrorFn`, `FromPredicate`, `GetOrElse`, `Map`, `Match`.

#### Either

Either represent a value that can have two possible types. It is common to see Either used to represent a success value `Right` or a failure value `Left`, although that doesn't have to be the case.
An instance of `Either` is either an instance of `Left` or `Right`.

Either exports `Left`, `Right`, `IsLeft`, `IsRight`, `Exists`, `Flatten`, `FromError`, `FromErrorFn`, `FromOption`, `FromPredicate`, `GetOrElse`, `Map`, `MapLeft`, `Match`,

fp-go

Functional programming in Go using generics

go-functional

A lodash like powerful utility library for Golang

![gofp](gofp.png)

![Go test workflow](https://github.com/rbrahul/gofp/actions/workflows/go.yml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/rbrahul/gofp)](https://goreportcard.com/report/github.com/rbrahul/gofp)
[![Go Reference](https://pkg.go.dev/badge/github.com/rbrahul/gofp.svg)](https://pkg.go.dev/github.com/rbrahul/gofp)
[![codecov](https://codecov.io/gh/rbrahul/gofp/branch/master/graph/badge.svg?token=EMXLVVLB07)](https://codecov.io/gh/rbrahul/gofp)


## A simple Utility library for Go

Go does not provide many essential built in functions when it comes to the data structure such as **slice** and **map**. This library provides a list of most frequently needed utility functions which are inspired by lodash(a Javascript Utility library).

## Main features of gofp

- Implementing Functional programming is way easier using `Pipe(), Compose(), Reduce(), Map(), Filter(), Extend(), Find() and many others`.

- This library offers many utility function for dealing with collections or slice related operation.

- Access any property by path or index from the map, slice and even struct by simply using the most useful function `Get`.

- Utility functions are implmented based on `interface{}`. The main focus is not to use the `reflect` package whenever possible.


## Installation
Please run the following command in terminal to install

```
go get github.com/rbrahul/gofp
```

## How to use?

This the example which describes how you can implement `pipe` operations using `gofp`

```go

package main

import (
"fmt"
"strings"
"github.com/rbrahul/gofp"
)

func main() {
	user := map[string]interface{}{
		"name": "John Doe",
		"age":  30,
		"contacts": map[string]interface{}{
			"email":  "johndoe@gmail.com",
			"office": "Google Inc.",
			"fax": map[string]interface{}{
				"uk": "+44-208-1234567",
			},
		},
	}
	getContacts := func(data interface{}) interface{} {
		return data.(map[string]interface{})["contacts"]
	}

	getEmail := func(data interface{}) interface{} {
		return data.(map[string]interface{})["email"]
	}
	getUpperCaseEmail := func(data interface{}) interface{} {
		return strings.ToUpper(data.(string))
	}

	email := gofp.Pipe(
		getContacts,
		getEmail,
		getUpperCaseEmail,
	)(user)

    fmt.Println("Email is: ", email) // Output: Email is: JOHNDOE@GMAIL.COM

}
```


## Documentation:

### Most commonly used utility functions for Collection or slice

### Map()
Returns a new slice executing the iterator function on each element. Map has 2 parameters, 1st one is slice and 2nd one is the iterator function. The iterator function must have 2 parameters, index and current value of that iteration.

```go
    ...
    mappedItems := Map([]interface{}{1, 2, 3, 4, 5},
            func(i int, item interface{}) interface{} {
                return item.(int) * item.(int)
            })
    
    fmt.Println(mappedItems) //Output: 1, 4, 9, 16, 25
    ...
```

### Filter()
Returns a new slice containing the filtered elements. The new slice contains those elements who satisfy the condition of the iterator function. Filter has 2 parameters, 1st one is the slice and 2nd one is the iterator function. The iterator function must have 2 parameters, index and current value of that iteration.

```go
    ...
        filteredItems := Filter([]interface{}{12, 16, 18, 20, 23, 40, 25},
            func(i int, age interface{}) bool {
                return age.(int) >= 20
            })
    
    fmt.Println(filteredItems) //Output:  20, 23, 40, 25
    ...
```


### Find()
Returns the first matched element of the slice who satisfy the condition of iterator function. If there is no such element that satisfy the condition of the function then nil is returned. Find has 2 parameters, 1st one is the slice and 2nd one is the iterator function. The iterator function must have 2 parameters, index and current value of that iteration.

```go
    ...
      user := Find([]interface{}{
            map[string]interface{}{"name": "Ron", "sex": "male", "age": 17},
            map[string]interface{}{"name": "Raymond", "sex": "male", "age": 20},
            map[string]interface{}{"name": "Sofia", "sex": "female", "age": 20},
            map[string]interface{}{"name": "Roni", "sex": "male", "age": 30},
        }, func(i int, person interface{}) bool {
            return person.(map[string]interface{})["age"].(int) >= 18
        })
    fmt.Println(user) //Output:  {"name": "Raymond", "sex": "male", "age": 20}
    ...
```
### Reduce()
Executes a iterator function on each element of the slice, resulting in single output accumulated value. Reducer has 3 parameters, 1st one is the slice and 2nd one is the iterator function and 3rd one is the initial value. The iterator function must have 3 parameters which are index, current value of that iteration and accumulated value or result of previous iterations.

```go
    ...
     reducedItems := Reduce([]interface{}{10, 20, 30, 40},
        func(index int, current interface{}, accumulator interface{}, source []interface{}) interface{} {
            return accumulator.(int) + current.(int)
	    }, 0)
    fmt.Println(reducedItems) //Output:  100
    ...
```
### Every()
Returns `true` if each element matches the condition of the given iterator function. If there is any element that doesn't satisfy the condition of the function then it returns `false`. Every has 2 parameters, 1st one is the slice and 2nd one is the iterator function. And the iterator function must have 2 parameters, index and current value of that iteration.

```go
    ...
     isEveryOneIsAdult := Every([]interface{}{18, 20, 23, 40, 25},
        func(i int, age interface{}) bool {
		    return age.(int) >= 18
	    })
    fmt.Println(isEveryOneIsAdult) //Output:  true
    ...
```

### Any()
Returns `true` if any of the element matches the condition of the given iterator function. If there is no such element that satisfy the condition of the function then it returns `false`. Any has 2 parameters, 1st one is the slice and 2nd one is the iterator function. And the iterator function must have 2 parameters, index and current value of that iteration.

```go
    ...
     hasAnyAdult := Any([]interface{}{18, 20, 23, 40, 25},
        func(i int, age interface{}) bool {
		    return age.(int) >= 18
	    })
    fmt.Println(hasAnyAdult) //Output:  true
    ...
```

### GroupBy()

Returns a new map composed of keys generated from the results of running each element of slice thru iterator function. The order of grouped values is determined by the order they occur in slice. GroupBy has 2 parameters, 1st one is the slice and 2nd one is the iterator function. The output of the iterator function will be used as the key of the newly created group or map. And the iterator function must have 2 parameters, index and current value of that iteration.

```go
    ...
     groupedData := GroupBy([]interface{}{
            map[string]interface{}{"name": "Ron", "sex": "male", "age": 17},
            map[string]interface{}{"name": "Raymond", "sex": "male", "age": 20},
            map[string]interface{}{"name": "Sofia", "sex": "female", "age": 20},
            map[string]interface{}{"name": "Roni", "sex": "male", "age": 30},
	    }, func(person interface{}) string {
		    return strconv.Itoa(person.(map[string]interface{})["age"].(int))
	})
    fmt.Println(groupedData) 
    /*
    Output:
      { 
          "17": [{"name": "Ron", "sex": "male", "age": 17}],
          "20": [
                {"name": "Raymond", "sex": "male", "age": 20},
                {"name": "Sofia", "sex": "female", "age": 20}
               ],
          "30": [{"name": "Roni", "sex": "male", "age": 30}]
     }
    */
    ...
```

### Chunk()

Returns a new slice(chunks) of slices. Every slice has fixed number of elements which was given as a limit in the 2nd parameter. Chunk accepts 2 parameters, 1st one is the slice and 2nd one is the limit which will define the maxium number of elements in each slice.

```go
    ...
	chunkedItems := Chunk([]interface{}{1, 2, 3, 4, 5}, 2)
    fmt.Println(chunkedItems) //Output:  {{1,2},{3,4},{5}}
    ...
```
### Reverse()

Returns a new slice with all the elements in reveresed order. Reverse accepsts 1 parameter which a slice.

```go
    ...
    reveresed := Reverse([]interface{}{10, 20, 30, 40, 50})
    fmt.Println(reveresed) //Output:  {50,40,30,20,10}
    ...
```

### Range()

Returns a new slice of range where the value starts from 1st parameter to the 2nd parameter. Reverse accepsts 2 parameters, 1st one is the starting value 2nd one is the maximum value in the range.

```go
    ...
    rangeItems := Range(5, 10)
    fmt.Println(rangeItems) //Output:  {5,6,7,8,9,10}
    ...
```

### Uniq()

Returns a new slice where each elements are unique removing all the duplicate elements. `Uniq` accepsts 1 parameter which is a slice.

```go
    ...
    // [1,2,3,10,4,5,100]
	uniqueItems := Uniq([]interface{}{1, 2, 2, 3, 10, 4, 5, 10, 100})
    fmt.Println(uniqueItems) //Output:  {1,2,3,10,4,5,100}
    ...
```

### Head()

Returns the first matched element of the slice. Head accepsts 1 parameter which a slice.

```go
    ...
      firstItem := Head([]interface{}{
            map[string]interface{}{"name": "Ron", "sex": "male", "age": 17},
            map[string]interface{}{"name": "Raymond", "sex": "male", "age": 20},
            map[string]interface{}{"name": "Sofia", "sex": "female", "age": 20},
            map[string]interface{}{"name": "Roni", "sex": "male", "age": 30},
        })
    fmt.Println(firstItem) //Output:  {"name": "Ron", "sex": "male", "age": 17}
    ...
```

### Tail()

Returns the last matched element of the slice. Head accepsts 1 parameter which a slice.

```go
    ...
      lastItem := Tail([]interface{}{
            map[string]interface{}{"name": "Ron", "sex": "male", "age": 17},
            map[string]interface{}{"name": "Raymond", "sex": "male", "age": 20},
            map[string]interface{}{"name": "Sofia", "sex": "female", "age": 20},
            map[string]interface{}{"name": "Roni", "sex": "male", "age": 30},
        })
    fmt.Println(lastItem) //Output:  {"name": "Roni", "sex": "male", "age": 30}
    ...
```

### Fill()

Returns a new slice where every elements is replaced from the start to end index with the given string. `Fill` has 4 arguments first 2 are required and last two are optional. First one is slice, 2nd one is the string which will be used as substitute while filling/replacing and 3rd one is the starting index and 4th one is the end index. If start and end index is not given then it fills all the elements with given string.

```go
    ...
	filledItems := Fill([]interface{}{1, 2, 3, 4, 5, 6, 7}, "*", 1, 5)
    fmt.Println(filledItems) //Output:  {1, *, *, *, *, 6, 7}
    ...
```

### IndexOf()

Returns the index of the first occurance of any element in the slice which is equal to the given item.

```go
    ...
	index := IndexOf([]interface{}{1, 2, 2, 3, 10, 4, 5, 10, 100}, 10)
    fmt.Println(index) //Output: 4
    ...
```

### Contains()

Returns `true` if the given item exists in the slice or false otherwise.

```go
    ...
    exists := Contains([]interface{}{1, 2, 2, 3, 10, 4, 5, 10, 100}, 10)
    fmt.Println(exists) //Output: true
    ...
```

### ChooseRandom()

Returns a randomly selected element of the slice. It has one parameter which is a slice.

```go
    ...
    randomElement := ChooseRandom([]interface{}{1, 2, 3, 4, 5, 10, 100})
    fmt.Println("Could be any:",randomElement) //Output Could be any: 4 
    ...
```

### Shuffle()

Returns a new slice where elements are randomly ordered(shuffled). It accepts one parameter which is slice.

```go
    ...
    shuffledItems := ChooseRandom([]interface{}{1, 2, 3, 4, 5, 10, 100})
    fmt.Println(shuffledItems) //Output: {100, 2, 1, 4, 5, 3, 10} 
    ...
```
## Map related utitlity function:

### Keys():

Returns a slice of keys of the map.  

```go
    ...
    keys := Keys(map[string]interface{}{
        "firstName": "John", 
        "lastName": "Doe",
        "age": 32
        })
    fmt.Println(keys) //Output: {firstName, lastName, age}
    ...
```

### Values():

Returns a slice of values of the map.

```go
    ...
    values := Values(map[string]interface{}{
        "firstName": "John", 
        "lastName": "Doe",
        "age": 32
        })
    fmt.Println(values) //Output: {John, Doe, 32}
    ...
```

### Has():

Returns `true` if key exists in the map or false otherwise. It has two parametes 1st one is a map and 2nd one is key.

```go
    ...
    exists := Has(map[string]interface{}{
        "firstName": "John", 
        "lastName": "Doe",
        "age": 32
        }, "age")
    fmt.Println(exists) //Output: true
    ...
```

### Pick():

Returns a new map containing only properties which are specified as 2nd argument. It accepts 2 parameters 1st one is the map and second one is the keys which is a slice of string.

```go
    ...
	pickedData := Pick(map[string]interface{}{
        "firstName": "John", 
        "lastName": "Doe",
        "age": 32
        }, []string{"lastName"})
    fmt.Println(pickedData) //Output: {"lastName": "Doe"}
    ...
```

### Omit():

Returns a new map omitting the given keys of that map. It accepts 2 parameters 1st one is the map and second one is the keys which is a slice of string.

```go
    ...
	omittedData := Omit(map[string]interface{}{
        "firstName": "John", 
        "lastName": "Doe",
        "age": 32
        }, []string{"lastName"})
    fmt.Println(omittedData) //Output: {"firstName": "John", "age": 32}
    ...
```

### MapValues():

`MapValues` works similarly to the `Map()` unlikely it deals with only map. It returns a new map applying an iterator function on each `value` of the map. The iterator function transforms the each value.  

```go
    ...
	mappedValues := MapValues(map[string]interface{}{
        "firstName": "john",
        "lastName": "doe",
        "gender": "unknown"}, func(value interface{}) interface{} {
		return strings.Title(value.(string))
	})
    fmt.Println(mappedValues) //Output: {"firstName": "JOHN",  "lastName":"DOE": 32, "gender":"UNKNOWN"}
    ...
```

### MapKeys():

`MapKeys` works similarly to the `Map()` unlikely it deals with only map. It returns a new map applying an iterator function on each `key` of the map. The iterator function transforms the each `key`.  

```go
    ...
	mappedKeys := MapKeys(map[string]interface{}{
        "firstName": "john",
        "lastName": "doe",
        "gender": "unknown"}, func(value interface{}) interface{} {
		return strings.Title(value.(string))
	})
    fmt.Println(mappedKeys) //Output: {"FIRSTNAME": "john","LASTNAME": "doe","GENDER": "unknown"}
    ...
```

### Get():

`Get()` returns the value of a given path. If no data is available in the given path then `nil` is returned. It deals with `map`, `slice`, and `struct`. It accepts 3 parameters, `data`, `path` and `fallback value`. 3rd parameter is optional. 

```go
    ...
	data := map[string]interface{}{
		"age":  30,
		"male": true,
		"contacts": map[string]interface{}{
			"office": 12345,
			"fax": map[string]interface{}{
				"uk": "+44-208-1234567",
			},
			"address": map[string]interface{}{
				"post_code":    "SW3",
				"street":       "10 Downing Street",
				"geo_location": []string{"51.529011463529636", "-0.1098365614770662"},
			},
		},
	}
	geoLocationFromGet := Get(data, "contacts.address.geo_location.0")
    fmt.Println(geoLocationFromGet) //Output: 51.529011463529636
    ...
```

### Extend():

`Extend()` returns a new map extending the values with a given map. Where extend or override operation happens deeply(recursively). It accepts two parameters both are map. 1st map gets extended with the 2nd map.

```go
    ...
	extendedMap := Extends(
        map[string]interface{}{
        "firstName": "john",
        "lastName": "doe",
        "gender": "unknown"
        },
         map[string]interface{}{
        "gender": "male"
        })
    fmt.Println(extendedMap) //Output: {"firstName": "john","lastName": "doe","gender": "male"}
    ...
```

[![Analytics](https://ga-beacon.appspot.com/UA-99614416-10/welcome-page)](https://github.com/rbrahul/gofp)


gofp

Monads and popular FP abstractions, based on Go 1.18+ Generics (Option, Result, Either...)

Functional programming helpers for Go 1.18 and beyond

# \_Underscore

![License](https://img.shields.io/github/license/rjNemo/underscore?style=for-the-badge)
[![Go version](https://img.shields.io/github/go-mod/go-version/rjNemo/underscore?style=for-the-badge&logo=go)](https://pkg.go.dev/github.com/rjNemo/underscore)
![Go report](https://goreportcard.com/badge/github.com/rjNemo/underscore?style=for-the-badge)
![test coverage](https://img.shields.io/codecov/c/github/rjNemo/underscore?style=for-the-badge&logo=codecov)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9726/badge?style=for-the-badge)](https://www.bestpractices.dev/projects/9726)

![underscore](https://socialify.git.ci/rjNemo/underscore/image?description=1&font=KoHo&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2FrjNemo%2Funderscore%2Fmain%2Fdocs%2Fstatic%2Flogo.png&owner=1&pattern=Floating%20Cogs&stargazers=1&theme=Dark)

`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`
- `RemoveAt`
- `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.

underscore

Monad, Functional Programming features for Golang

# fpGo

[![tag](https://img.shields.io/github/tag/TeaEntityLab/fpGo.svg)](https://github.com/TeaEntityLab/fpGo)
[![Go Report Card](https://goreportcard.com/badge/github.com/TeaEntityLab/fpGo/v2)](https://goreportcard.com/report/github.com/TeaEntityLab/fpGo/v2)
[![codecov](https://codecov.io/gh/TeaEntityLab/fpGo/branch/master/graph/badge.svg)](https://codecov.io/gh/TeaEntityLab/fpGo)
[![Travis CI Build Status](https://travis-ci.com/TeaEntityLab/fpGo.svg?branch=master)](https://travis-ci.com/TeaEntityLab/fpGo)
[![GoDoc](https://godoc.org/github.com/TeaEntityLab/fpGo?status.svg)](https://godoc.org/github.com/TeaEntityLab/fpGo)

[![license](https://img.shields.io/github/license/TeaEntityLab/fpGo.svg?style=social&label=License)](https://github.com/TeaEntityLab/fpGo)
[![stars](https://img.shields.io/github/stars/TeaEntityLab/fpGo.svg?style=social&label=Stars)](https://github.com/TeaEntityLab/fpGo)
[![forks](https://img.shields.io/github/forks/TeaEntityLab/fpGo.svg?style=social&label=Fork)](https://github.com/TeaEntityLab/fpGo)

Monad, Functional Programming features for Golang

# Active Branches:

For *Generics* version(*`>=go1.18`*):[generics](https://github.com/TeaEntityLab/fpGo/tree/generics)

```bash
go get github.com/TeaEntityLab/fpGo/v2
```

For *NonGenerics* version(*`<=go1.17`*):[non-generics](https://github.com/TeaEntityLab/fpGo/tree/non_generic)

```bash
go get github.com/TeaEntityLab/fpGo
```

# Why

I love functional programing, Rx-style coding, and Optional usages.

However it's hard to implement them in Golang, and there're few libraries to achieve parts of them.

Thus I implemented fpGo. I hope you would like it :)

# Features

* Optional/Maybe

* Monad, Rx-like

* Publisher



* Pattern matching

* Fp functions



* Java8Stream-like Collection

* Queue (LinkedListQueue/ChannelQueue/BufferedChannelQueue/ConcurrentQueue)

* PythonicGenerator-like Coroutine(yield/yieldFrom)

* Akka/Erlang-like Actor model(send/receive/spawn/states)

* **network/SimpleHTTP** inspired by [Retrofit](https://github.com/square/retrofit)

* **worker/WorkerPool** inspired by JavaExecutorService & goroutine pool libs

# Special thanks
* fp functions(Dedupe/Difference/Distinct/IsDistinct/DropEq/Drop/DropLast/DropWhile/IsEqual/IsEqualMap/Every/Exists/Intersection/Keys/Values/Max/Min/MinMax/Merge/IsNeg/IsPos/PMap/Range/Reverse/Set/Some/IsSubset/IsSuperset/Take/TakeLast/Union/IsZero/Zip/GroupBy/UniqBy/Flatten/Prepend/Partition/Tail/Head/SplitEvery)
 *	Credit: https://github.com/logic-building/functional-go
 * Credit: https://github.com/achannarasappa/pneumatic

# Usage

## Optional (IsPresent/IsNil, Or, Let)

```go
var m MaybeDef[interface{}]
var orVal int
var boolVal bool

// IsPresent(), IsNil()
m = Maybe.Just(1)
boolVal = m.IsPresent() // true
boolVal = m.IsNil() // false
m = Maybe.Just(nil)
boolVal = m.IsPresent() // false
boolVal = m.IsNil() // true

// Or()
m = Maybe.Just(1)
fmt.Println((m.Or(3))) // 1
m = Maybe.Just(nil)
fmt.Println((m.Or(3))) // 3

// Let()
var letVal int
letVal = 1
m = Maybe.Just(1)
m.Let(func() {
 letVal = 2
})
fmt.Println(letVal) // letVal would be 2

letVal = 1
m = Maybe.Just(nil)
m.Let(func() {
 letVal = 3
})
fmt.Println(letVal) // letVal would be still 1
```

## MonadIO (RxObserver-like)

Example:
```go
var m *MonadIODef[interface{}]
var actualInt int

m = MonadIO.Just(1)
actualInt = 0
m.Subscribe(Subscription[interface{}]{
 OnNext: func(in interface{}) {
 actualInt, _ = Maybe.Just(in).ToInt()
 },
})
fmt.Println(actualInt) // actualInt would be 1

m = MonadIO.Just(1).FlatMap(func(in interface{}) *MonadIODef[interface{}] {
 v, _ := Maybe.Just(in).ToInt()
 return MonadIO.Just(v + 1)
})
actualInt = 0
m.Subscribe(Subscription[interface{}]{
 OnNext: func(in interface{}) {
 actualInt, _ = Maybe.Just(in).ToInt()
 },
})
fmt.Println(actualInt) // actualInt would be 2
```

## Stream (inspired by Collection libs)

Example(Generics):
```go
var s *StreamDef[int]
var tempString = ""

s = StreamFromArray([]int{}).Append(1, 1).Extend(StreamFromArray([]int{2, 3, 4}))
tempString = ""
for _, v := range s.ToArray() {
 tempString += Maybe.Just(v).ToMaybe().ToString()
}
fmt.Println(tempString) // tempString would be "11234"
s = s.Distinct()
tempString = ""
for _, v := range s.ToArray() {
 tempString += Maybe.Just(v).ToMaybe().ToString()
}
fmt.Println(tempString) // tempString would be "1234"
```

Example(Non-Generics/interface{}):
```go
var s *StreamForInterfaceDef
var tempString string

s = StreamForInterface.FromArrayInt([]int{}).Append(1, 1).Extend(StreamForInterface.FromArrayInt([]int{2, 3, 4})).Extend(StreamForInterface.FromArray([]interface{}{nil})).Extend(nil)
tempString = ""
for _, v := range s.ToArray() {
 tempString += Maybe.Just(v).ToMaybe().ToString()
}
fmt.Println(tempString) // tempString would be "11234<nil>"
s = s.Distinct()
tempString = ""
for _, v := range s.ToArray() {
 tempString += Maybe.Just(v).ToMaybe().ToString()
}
fmt.Println(tempString) // tempString would be "1234<nil>"
s = s.FilterNotNil()
tempString = ""
for _, v := range s.ToArray() {
 tempString += Maybe.Just(v).ToMaybe().ToString()
}
fmt.Println(tempString) // tempString would be "1234"
```

## Queue(LinkedListQueue/ChannelQueue/BufferedChannelQueue/ConcurrentQueue) (inspired by Collection libs)

### LinkedListQueue(Shift/Unshift/Push/Pop), ConcurrentQueue(inspired by Java)

Example:

```go
var queue Queue[int]
var stack Stack[int]
var err error
var result int

linkedListQueue := NewLinkedListQueue[int]()
queue = linkedListQueue
stack = linkedListQueue
concurrentQueue := NewConcurrentQueue[int](queue)

// As a Queue, Put(val) in the TAIL and Take() in the HEAD
err = queue.Offer(1)
err = queue.Offer(2)
err = queue.Offer(3)
result, err = queue.Poll() // Result should be 1
result, err = queue.Poll() // Result should be 2
result, err = queue.Poll() // Result should be 3
result, err = queue.Poll() // Err: ErrQueueIsEmpty

// As a Stack, Push(val) & Pop() in the TAIL.
err = stack.Push(1)
err = stack.Push(2)
err = stack.Push(3)
result, err = stack.Pop() // Result should be 3
result, err = stack.Pop() // Result should be 2
result, err = stack.Pop() // Result should be 1
result, err = stack.Pop() // Err: ErrStackIsEmpty
```

### BufferedChannelQueue(Offer/Take/TakeWithTimeout)

Example:

```go
var err error
var result int
var timeout time.Duration

bufferedChannelQueue := NewBufferedChannelQueue[int](3, 10000, 100).
 SetLoadFromPoolDuration(time.Millisecond / 10).
 SetFreeNodeHookPoolIntervalDuration(1 * time.Millisecond)

err = queue.Offer(1)
err = queue.Offer(2)
err = queue.Offer(3)
timeout = 1 * time.Millisecond
result, err = bufferedChannelQueue.TakeWithTimeout(timeout) // Result should be 1
result, err = bufferedChannelQueue.TakeWithTimeout(timeout) // Result should be 2
result, err = bufferedChannelQueue.TakeWithTimeout(timeout) // Result should be 3
```

## Actor (inspired by Akka/Erlang)

### Actor common(send/receive/spawn/states)

Example:

```go
actual := 0
// Channel for results
resultChannel := make(chan interface{}, 1)
// Message CMDs
cmdSpawn := "spawn"
cmdShutdown := "shutdown"
// Testee
actorRoot := Actor.New(func(self *ActorDef[interface{}], input interface{}) {
 // SPAWN: for ROOT
 if input == cmdSpawn {
 self.Spawn(func(self *ActorDef[interface{}], input interface{}) {
 // SHUTDOWN: for Children
 if input == cmdShutdown {
 self.Close()
 return
 }

 // INT cases: Children
 val, _ := Maybe.Just(input).ToInt()
 resultChannel <- val * 10
 })
 return
 }
 // SHUTDOWN: for ROOT
 if input == cmdShutdown {
 for _, child := range self.children {
 child.Send(cmdShutdown)
 }
 self.Close()

 close(resultChannel)
 return
 }

 // INT cases: ROOT
 intVal, _ := Maybe.Just(input).ToInt()
 if intVal > 0 {
 for _, child := range self.children {
 child.Send(intVal)
 }
 }
})

// Sequential Send messages(async)
go func() {
 actorRoot.Send(cmdSpawn)
 actorRoot.Send(10)
 actorRoot.Send(cmdSpawn)
 actorRoot.Send(20)
 actorRoot.Send(cmdSpawn)
 actorRoot.Send(30)
}()

i := 0
for val := range resultChannel {
 intVal, _ := Maybe.Just(val).ToInt()
 actual += intVal

 i++
 if i == 5 {
 go actorRoot.Send(cmdShutdown)
 }
}

// Result would be 1400 (=10*10+20*10+20*10+30*10+30*10+30*10)
fmt.Println(actual)
```

### Actor Ask (inspired by Akka/Erlang)

```go
actorRoot := Actor.New(func(self *ActorDef[interface{}], input interface{}) {
 // Ask cases: ROOT
 switch val := input.(type) {
 case *AskDef[interface{}, int]:
 intVal, _ := Maybe.Just(val.Message).ToInt()

 // NOTE If negative, hanging for testing Ask.timeout
 if intVal < 0 {
 break
 }

 val.Reply(intVal * 10)
 break
 }
})

// var timer *time.Timer
var timeout time.Duration
timeout = 10 * time.Millisecond

// Normal cases
// Result would be 10
actual = AskNewGenerics[interface{}, int](1).AskOnce(actorRoot)
// Ask with Timeout
// Result would be 20
actual, _ = AskNewGenerics[interface{}, int](2).AskOnceWithTimeout(actorRoot, timeout)
// Ask channel
// Result would be 30
ch := AskNewGenerics[interface{}, int](3).AskChannel(actorRoot)
actual = <- ch
close(ch)

// Timeout cases
// Result would be 0 (zero value, timeout)
actual, err = AskNewGenerics[interface{}, int](-1).AskOnceWithTimeout(actorRoot, timeout)
```

## Compose

Example:

```go
var fn01 = func(args ...int) []int {
 val := args[0]
 return SliceOf(val + 1)
}
var fn02 = func(args ...int) []int {
 val := args[0]
 return SliceOf(val + 2)
}
var fn03 = func(args ...int) []int {
 val := args[0]
 return SliceOf(val + 3)
}

// Result would be 6
result := Compose(fn01, fn02, fn03)((0))[0]
```

fpGo

<img src="doc/fuego_logo.png" alt="ƒuego logo" height="200">


<h3 align="center">
 <a href="#">ƒuego - Functional Experiment in Go</a>
</h3>


 <a href="https://twitter.com/intent/tweet?text=Fuego%20Go%20language%20functional%20experiment&url=https://www.github.com/seborama/fuego&hashtags=golang,functional,programming,developers">
 <img src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social" alt="Tweet">
 </a>



 <a href="https://pkg.go.dev/github.com/seborama/fuego/v12">
 <img src="https://img.shields.io/badge/godoc-reference-blue.svg" alt="fuego">
 </a>
 <a href="http://goreportcard.com/report/seborama/fuego">
 <img src="https://img.shields.io/badge/go%20report-A%2B-brightgreen.svg" alt="goreportcard">
 </a>



<a href="https://buymeacoff.ee/seborama/" target="_blank">
 <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" />
 </a>



 <a style="vertical-align:middle; display:inline-block;">
 <img src="doc/fuego_code.png" alt="ƒuego example" width="440">
 <img align="right" src="doc/fuego_code_employees.png" alt="ƒuego example" width="360">
 </a>


## Table of content

- [Overview](#overview)
- [Type Parameters](#type-parameters)
- [Documentation](#documentation)
- [Installation](#installation)
- [Debugging](#debugging)
- [Example Stream](#example-stream)
- [Contributions](#contributions)
- [The Golden rules of the game](#the-golden-rules-of-the-game)
- [Pressure](#pressure)
- [Concept: Entry](#concept-entry)
- [Features summary](#features-summary)
 - [Concurrency](#concurrency)
- [Collectors](#collectors)
- [Golang, Receivers and Functions](#golang-receivers-and-functions)
- [Known limitations](#known-limitations)

## [Overview](#overview)

**_Making Go come to functional programming._**

This is a research project in functional programming which I hope will prove useful!

___ƒuego___ brings a few functional paradigms to Go. The intent is to save development time while promoting code readability and reduce the risk of complex bugs.

I hope you will find it useful!

Have fun!!

[(toc)](#table-of-content)

## [Type Parameters](#type-parameters)

Starting with version 11, ___ƒuego___ uses Go 1.18's [Type Parameters](https://go.googlesource.com/proposal/+/master/design/43651-type-parameters.md).

It is a drastic design change and fundamentally incompatible with previous versions of ___ƒuego___.

Use version 10 or prior if you need the pre-Go1.18 version of ___ƒuego___ that is based on interface `Entry`.

[(toc)](#table-of-content)

## [Documentation](#documentation)

The code documentation and some examples can be found on [godoc](https://pkg.go.dev/github.com/seborama/fuego/v12).

The tests form the best source of documentation. ___ƒuego___ comes with a good collection of unit tests and testable Go examples. Don't be shy, open them up and read them and tinker with them!

> **Note:**
> 
> Most tests use unbuffered channels to help detect deadlocks. In real life scenarios, it is recommended to use buffered channels for increased performance.

[(toc)](#table-of-content)

## [Installation](#installation)

### Download

```bash
go get github.com/seborama/fuego
```

Or for a specific version:

```bash
go get gopkg.in/seborama/fuego.v12
```

### Import in your code

You can import the package in the usual Go fashion.

To simplify usage, you can use an alias:

```go
package sample

import ƒ "gopkg.in/seborama/fuego.v12"
```

...or import as a blank import:

```go
package sample

import _ "gopkg.in/seborama/fuego.v12"
```

Note: dot imports should work just fine but the logger may be disabled, unless you initialised the zap global logger yourself.

[(toc)](#table-of-content)

## [Debugging](#debugging)

Set environment variable `FUEGO_LOG_LEVEL` to enable logging to the desired level.

[(toc)](#table-of-content)

## [Example Stream](#example-stream)

```go
strs := []string{
 "a",
 "b",
 "bb",
 "bb",
 "cc",
 "ddd",
}
 
Collect(
 NewStreamFromSlice[string](strs, 100).
 Filter(isString).
 Distinct(stringHash),
 GroupingBy(
 stringLength,
 Mapping(
 stringToUpper,
 Filtering(
 stringLengthGreaterThan(1),
 ToSlice[string](),
 ),
 ),
 ),
)

// result: map[1:[] 2:[BB CC] 3:[DDD]]
```

[(toc)](#table-of-content)

## [Contributions](#contributions)

Contributions and feedback are welcome.

For contributions, you must develop in TDD fashion and ideally provide Go testable examples (if meaningful).

If you have an idea to improve ___ƒuego___, please share it via an issue.

And if you like ___ƒuego___ give it a star to show your support for the project - it will put a smile on my face! :blush:

Thanks!!

[(toc)](#table-of-content)

## [The Golden rules of the game](#the-golden-rules-of-the-game)

1. Producers close their channel.

1. Consumers do not close channels.

1. Producers and consumers should be running in separate Go routines to prevent deadlocks when the channels' buffers fill up.

[(toc)](#table-of-content)

## [Pressure](#pressure)

Go channels support buffering that affects the behaviour when combining channels in a pipeline.

When the buffer of a Stream's channel of a consumer is full, the producer will not be able to send more data through to it. This protects downstream operations from overloading.

Presently, a Go channel cannot dynamically change its buffer size. This prevents from adapting the stream flexibly. Constructs that use 'select' on channels on the producer side can offer opportunities for mitigation.

[(toc)](#table-of-content)

## [Features summary](#features-summary)

Streams:

- Stream:
 - Filter
 - Map / FlatMap
 - Reduce
 - GroupBy
 - All/Any/None -Match
 - Intersperse
 - Distinct
 - Head* / Last* / Take* / Drop*
 - StartsWith / EndsWith
 - ForEach / Peek
 - ...
- ComparableStream
- MathableStream

Functional Types:

- Optional
- Predicate

Functions:

- Consumer / BiConsumer
- Function / BiFunction
- StreamFunction

Collectors:

- GroupingBy
- Mapping
- FlatMapping
- Filtering
- Reducing
- ToSlice
- ToMap*

Check the [godoc](https://pkg.go.dev/github.com/seborama/fuego/v12) for full details.

[(toc)](#table-of-content)

### Concurrency

As of v8.0.0, a new concurrent model offers to process a stream concurrently while preserving order.

This is not possible yet with all Stream methods but it is available with e.g. `Stream.Map`.

#### Notes on concurrency

Concurrent streams are challenging to implement owing to ordering issues in parallel processing. At the moment, the view is that the most sensible approach is to delegate control to users. Multiple ___ƒuego___ streams can be created and data distributed across as desired. This empowers users of ___ƒuego___ to implement the desired behaviour of their pipelines.

`Stream` has some methods that fan out (e.g. `ForEachC`). See the [godoc](https://pkg.go.dev/github.com/seborama/fuego/v12) for further information and limitations.

I recommend Rob Pike's slides on Go concurrency patterns:

- [Go Concurrency Patterns, Rob Pike, 2012](https://talks.golang.org/2012/concurrency.slide#1)

As a proof of concept and for facilitation, ___ƒuego___ has a `CStream` implementation to manage concurrently a collection of Streams.

[(toc)](#table-of-content)

## [Collectors](#collectors)

A `Collector` is a mutable reduction operation, optionally transforming the accumulated result.

Collectors can be combined to express complex operations in a concise manner.
 
Simply put, a collector allows the creation of bespoke actions on a Stream.

___ƒuego___ exposes a number of functional methods such as `MapToInt`, `Head`, `LastN`, `Filter`, etc...
 
Collectors also provide a few functional methods.

But... what if you need something else? And it is not straightforward or readable when combining the existing methods ___ƒuego___ offers?

Enters `Collector`: implement your own requirement functionally!
 
Focus on _**what**_ needs doing in your streams (and delegate the details of the _**how**_ to the implementation of your `Collector`).

[(toc)](#table-of-content)

## [Golang, Receivers and Functions](#golang-receivers-and-functions)

Some tests (e.g. `TestCollector_Filtering`) are using receiver Getter methods in guise of `Function[T, R any]`. Here is the explanation how this is possible.

`Function[T, R any]` is defined as `func(T) R`.

A method Getter is typically defined as `func (T) Property() R {...}`.

With `t` as the receiver, Go allows `t.Property()` be called as `T.Property(t)`. This is a `func(T) R` and hence a `Function[T, R any]`.

Example - `TestCollector_Filtering`:

`employee.Department(employees[0])` is the same as `employees[0].Department()`, and of course, they both return a `string`.

The first syntax has one advantage for our purpose though: it is a `Function[T, R any]`.

[(toc)](#table-of-content)

## [Known limitations](#known-limitations)

- several operations may be memory intensive or poorly performing.

### No parameterised method in Go

Go 1.18 brings typed parameters. However, parameterised methods are not allowed.

This prevents the Map() method of `Stream` from mapping to, and from returning, a new typed parameter.

To circumvent this, we need to use a decorator function to re-map the `Stream`.

This can lead to a leftward-growing chain of decorator function calls that makes the intent opaque:

```go
ReStream(
 ReStream(is, Stream[int]{}).Map(float2int),
 Stream[string]{}).Map(int2string)
// This is actually performing: Stream.Map(float2int).Map(int2string)
```
___ƒuego___ includes a set of casting functions that reduce the visually leftward-growing chain of decorators while preserving a natural functional flow expression:

```go
C(C(C(
 s.
 Map(float2int_), Int).
 Map(int2string_), String).
 Map(string2int_), Int).
 ForEach(print[int])
// This is actually performing: s.Map(float2int).Map(int2string).Map(string2int).ForEach(print)
```

While not perfect, this is the best workable compromise I have obtained thus far.

[(toc)](#table-of-content)

### Performance issues when using numerous parameterised methods in Go 1.18

As a result of this [issue](https://github.com/golang/go/issues/51957), an experiment to add `MapTo<native_type>() Stream[<native_type>]` is disabled.

Instead, use function `CC` (ComparableStream Cast) to access Min(), Max(), and `MC` (MathableStream Cast) to access Sum().

[(toc)](#table-of-content)


<a href="https://buymeacoff.ee/seborama/" target="_blank">
 <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" />
 </a>

fuego

<img src="https://user-images.githubusercontent.com/65846651/229838021-741ff719-8c99-45f6-88d2-1a32927bd863.png">


# g - Functional programming framework for Go.

[![Go Reference](https://pkg.go.dev/badge/github.com/enetx/g.svg)](https://pkg.go.dev/github.com/enetx/g)
[![Go Report Card](https://goreportcard.com/badge/github.com/enetx/g)](https://goreportcard.com/report/github.com/enetx/g)
[![Coverage Status](https://coveralls.io/repos/github/enetx/g/badge.svg?branch=main&service=github)](https://coveralls.io/github/enetx/g?branch=main)
[![Go](https://github.com/enetx/g/actions/workflows/go.yml/badge.svg)](https://github.com/enetx/g/actions/workflows/go.yml)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/enetx/g)

```bash
go get github.com/enetx/g
```

Requires **Go 1.24+**

---

## Quick Start

```go
package main

import (
 "fmt"
 "github.com/enetx/g"
)

func main() {
 // Slice with functional operations
 g.SliceOf(1, 2, 3, 4, 5).
 Iter().
 Filter(func(x int) bool { return x%2 == 0 }).
 Map(func(x int) int { return x * x }).
 Collect().
 Println() // Slice[4, 16]

 // Safe map access with Option
 m := g.NewMap[string, int]()
 m.Insert("key", 42)

 value := m.Get("key").UnwrapOr(0)
 fmt.Println(value) // 42

 // Result for error handling
 result := g.String("123").TryInt()
 if result.IsOk() {
 fmt.Println(result.Unwrap()) // 123
 }
}
```

---

## Navigation

| Core | Collections | Sync | Types |
|:----:|:-----------:|:----:|:-----:|
| [Option](#option) | [Slice](#slice) | [Mutex](#mutex) | [String](#string) |
| [Result](#result) | [Map](#map) | [RwLock](#rwlock) | [Int/Float](#int--float) |
| [Iterators](#iterators) | [Set](#set) | [Pool](#pool) | [Bytes](#bytes) |
| | [Heap](#heap) | | [File/Dir](#file--directory) |
| | [Deque](#deque) | | |

---

## Option

Safe nullable values: `Some(value)` or `None`.

```go
opt := g.Some(42) // Some(42)
none := g.None[int]() // None

opt.IsSome() // true
opt.Unwrap() // 42 (panics if None)
opt.UnwrapOr(0) // 42 (returns default if None)
opt.UnwrapOrDefault() // 42 (returns zero value if None)

// From map lookup
v, ok := myMap[key]
opt := g.OptionOf(v, ok)

// Chaining
g.Some(5).Then(func(x int) g.Option[int] {
 return g.Some(x * 2)
}) // Some(10)
```

<details>
<summary>All Option Methods</summary>

| Method | Description |
|--------|-------------|
| `IsSome()` | Returns true if contains value |
| `IsNone()` | Returns true if empty |
| `Some()` | Returns value (same as Unwrap) |
| `Unwrap()` | Returns value, panics if None |
| `UnwrapOr(default)` | Returns value or default |
| `UnwrapOrDefault()` | Returns value or zero value |
| `UnwrapOrElse(fn)` | Returns value or result of fn |
| `Expect(msg)` | Returns value, panics with msg if None |
| `Then(fn)` | Transforms value if Some |
| `Option()` | Returns (value, bool) |
| `Take()` | Takes value, leaves None |
| `Filter(fn)` | Returns None if predicate fails |

</details>

---

## Result

Success (`Ok`) or failure (`Err`) with error.

```go
ok := g.Ok(42) // Ok(42)
err := g.Err[int](errors.New("failed")) // Err

ok.IsOk() // true
ok.Unwrap() // 42
err.UnwrapOr(0) // 0

// From standard (value, error) pattern
result := g.ResultOf(strconv.Atoi("42")) // Ok(42)
result := g.String("42").TryInt() // Ok(42)

// Chaining
g.Ok(10).Then(func(x int) g.Result[int] {
 return g.Ok(x * 2)
}) // Ok(20)

// Convert to Option (discards error)
opt := result.Option() // Some(42)
```

<details>
<summary>All Result Methods</summary>

| Method | Description |
|--------|-------------|
| `IsOk()` | Returns true if success |
| `IsErr()` | Returns true if error |
| `Ok()` | Returns value (same as Unwrap) |
| `Err()` | Returns error |
| `Unwrap()` | Returns value, panics if Err |
| `UnwrapOr(default)` | Returns value or default |
| `UnwrapOrDefault()` | Returns value or zero value |
| `UnwrapOrElse(fn)` | Returns value or result of fn |
| `Expect(msg)` | Returns value, panics with msg |
| `Then(fn)` | Chains operation if Ok |
| `ThenOf(fn)` | Chains (T, error) function |
| `MapErr(fn)` | Transforms error if Err |
| `Option()` | Converts to Option |
| `Result()` | Returns (value, error) |

</details>

---

## Slice

Extended slice with 90+ methods.

```go
s := g.SliceOf(1, 2, 3, 4, 5)
s := g.NewSlice[int](10) // with capacity

s.Len() // Int(5)
s.Get(0) // Some(1)
s.Get(100) // None (safe!)
s.Last() // Some(5)
s.Contains(3) // true

s.Push(6, 7) // append in place
s.Pop() // Some(7)
s.Clone() // safe copy

// Sorting
s.SortBy(cmp.Cmp) // ascending
s.Reverse() // in place
s.Shuffle() // random order
```

<details>
<summary>All Slice Methods</summary>

| Category | Methods |
|----------|---------|
| **Access** | `Get`, `Last`, `First`, `Random`, `RandomSample` |
| **Modify** | `Set`, `Push`, `Pop`, `Insert`, `Remove`, `Clear` |
| **Search** | `Contains`, `ContainsBy`, `Index`, `IndexBy` |
| **Transform** | `Clone`, `Reverse`, `Shuffle`, `SortBy`, `SubSlice` |
| **Convert** | `Iter`, `Heap`, `Std` |
| **Info** | `Len`, `Cap`, `IsEmpty` |

</details>

---

## Map

Extended map with Entry API.

```go
m := g.NewMap[string, int]()

m.Insert("a", 1) // insert value
m.Get("a") // Some(1)
m.Get("x") // None
m.Contains("a") // true
m.Remove("a") // remove

m.Keys() // Slice of keys
m.Values() // Slice of values
```

### Entry API

Efficient update without multiple lookups:

```go
// Insert if absent
m.Entry("counter").OrInsert(0)

// Update if present, insert if absent
m.Entry("counter").AndModify(func(v *int) { *v++ }).OrInsert(1)

// Lazy initialization
m.Entry("key").OrInsertWith(func() int {
 return expensiveComputation()
})
```

**Word frequency example:**
```go
words := g.SliceOf("apple", "banana", "apple", "cherry", "banana", "apple")
freq := g.NewMap[string, int]()

for _, word := range words {
 freq.Entry(word).AndModify(func(v *int) { *v++ }).OrInsert(1)
}
// {"apple": 3, "banana": 2, "cherry": 1}
```

<details>
<summary>Entry Pattern Matching</summary>

```go
switch e := m.Entry("key").(type) {
case g.OccupiedEntry[string, int]:
 fmt.Println("Exists:", e.Get())
 e.Insert(newValue) // replace
 e.Remove() // delete
case g.VacantEntry[string, int]:
 e.Insert(defaultValue) // insert
}
```

</details>

---

## Set

Collection of unique elements.

```go
s := g.SetOf(1, 2, 3)
s.Insert(4) // add
s.Remove(1) // remove
s.Contains(2) // true
```

### Set Operations

```go
a := g.SetOf(1, 2, 3, 4)
b := g.SetOf(3, 4, 5, 6)

a.Union(b).Collect() // {1, 2, 3, 4, 5, 6}
a.Intersection(b).Collect() // {3, 4}
a.Difference(b).Collect() // {1, 2}
a.SymmetricDifference(b).Collect() // {1, 2, 5, 6}

a.Subset(b) // false
a.Superset(b) // false
```

---

## Heap

Priority queue (binary heap).

```go
import "github.com/enetx/g/cmp"

// Min-heap (smallest first)
h := g.NewHeap(cmp.Cmp[int])
h.Push(5, 3, 8, 1, 9)

h.Peek() // Some(1)
h.Pop() // Some(1)
h.Pop() // Some(3)

// Max-heap (largest first)
maxH := g.NewHeap(func(a, b int) cmp.Ordering {
 return cmp.Cmp(b, a)
})

// From slice
heap := g.SliceOf(5, 3, 8, 1).Heap(cmp.Cmp)
```

---

## Deque

Double-ended queue (ring buffer). O(1) at both ends.

```go
dq := g.NewDeque[int]()
dq := g.DequeOf(1, 2, 3)

dq.PushFront(0) // add to front
dq.PushBack(4) // add to back

dq.Front() // Some(0)
dq.Back() // Some(4)

dq.PopFront() // Some(0)
dq.PopBack() // Some(4)

dq.Get(1) // element at index
dq.Len() // length
dq.IsEmpty() // true/false
```

---

## Iterators

Functional operations on sequences.

```go
g.SliceOf(1, 2, 3, 4, 5, 6, 7, 8, 9, 10).
 Iter().
 Filter(func(x int) bool { return x%2 == 0 }).
 Map(func(x int) int { return x * x }).
 Take(3).
 Collect()
// [4, 16, 36]
```

### Common Patterns

```go
// Chain iterators
g.SliceOf(1, 2).Iter().Chain(g.SliceOf(3, 4).Iter()).Collect()
// [1, 2, 3, 4]

// Sum with Fold
g.SliceOf(1, 2, 3, 4, 5).Iter().Fold(0, func(acc, x int) int { return acc + x })
// 15

// Enumerate
g.SliceOf("a", "b", "c").Iter().Enumerate().ForEach(func(i g.Int, v string) {
 fmt.Printf("%d: %s\n", i, v)
})

// Using f package predicates
import "github.com/enetx/g/f"

g.SliceOf(1, 2, 3, 4, 5).Iter().Filter(f.Ne(3)).Collect() // [1, 2, 4, 5]
g.SliceOf("", "a", "").Iter().Exclude(f.IsZero).Collect() // ["a"]
```

<details>
<summary>All Iterator Methods</summary>

| Transform | Slice | Combine | Aggregate | Search | Other |
|-----------|-------|---------|-----------|--------|-------|
| `Map` | `Take` | `Chain` | `Collect` | `Find` | `ForEach` |
| `Filter` | `Skip` | `Zip` | `Fold` | `Any` | `Inspect` |
| `Exclude` | `StepBy` | `Enumerate` | `Reduce` | `All` | `Range` |
| `FilterMap` | `First` | `Intersperse` | `Count` | `MaxBy` | `Scan` |
| `FlatMap` | `Last` | `Cycle` | `Counter` | `MinBy` | `Combinations` |
| `Flatten` | `Nth` | | `Partition` | | `Permutations` |
| `Dedup` | `Chunks` | | `GroupBy` | | `Context` |
| `Unique` | `Windows` | | | | `Chan` |
| `SortBy` | | | | | `Parallel` |

</details>

---

## Mutex

Typed mutex — data bound to lock.

```go
counter := g.NewMutex(0)

// Lock and modify
guard := counter.Lock()
guard.Set(guard.Get() + 1)
guard.Unlock()

// With defer (recommended)
func increment(c *g.Mutex[int]) {
 guard := c.Lock()
 defer guard.Unlock()
 guard.Set(guard.Get() + 1)
}

// Direct pointer access
guard := counter.Lock()
defer guard.Unlock()
*guard.Deref() += 1

// Non-blocking
if opt := counter.TryLock(); opt.IsSome() {
 guard := opt.Unwrap()
 defer guard.Unlock()
 // got the lock
}
```

**Why typed mutex?**
```go
// Traditional — easy to forget locking
type Old struct {
 mu sync.Mutex
 data map[string]int // what protects this?
}

// Typed — impossible to access without lock
type New struct {
 data *g.Mutex[g.Map[string, int]]
}

func (s *New) Get(key string) g.Option[int] {
 guard := s.data.Lock()
 defer guard.Unlock()
 return guard.Deref().Get(key)
}
```

---

## RwLock

Multiple readers OR single writer.

```go
config := g.NewRwLock(Config{Port: 8080})

// Read (concurrent)
func getPort(c *g.RwLock[Config]) int {
 guard := c.Read()
 defer guard.Unlock()
 return guard.Get().Port
}

// Write (exclusive)
func setPort(c *g.RwLock[Config], port int) {
 guard := c.Write()
 defer guard.Unlock()
 guard.Deref().Port = port
}

// Non-blocking
if opt := config.TryRead(); opt.IsSome() { ... }
if opt := config.TryWrite(); opt.IsSome() { ... }
```

| Use Case | Choose |
|----------|--------|
| Read-heavy (config, cache) | `RwLock` |
| Write-heavy or balanced | `Mutex` |
| Simple counters | `Mutex` |

---

## Pool

Goroutine pool for parallel tasks.

```go
import "github.com/enetx/g/pool"

p := pool.New[int]().Limit(4)

for i := range 10 {
 p.Go(func() g.Result[int] {
 return g.Ok(i * 2)
 })
}

for result := range p.Wait() {
 if result.IsOk() {
 fmt.Println(result.Unwrap())
 }
}
```

<details>
<summary>With Context and Cancel on Error</summary>

```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

p := pool.New[int]().
 Context(ctx).
 CancelOnError().
 Limit(4)

for i := range 100 {
 p.Go(func() g.Result[int] {
 if i == 50 {
 return g.Err[int](errors.New("error"))
 }
 return g.Ok(i)
 })
}

for result := range p.Wait() {
 // stops after first error
}
```

</details>

---

## String

Extended string with 80+ methods.

```go
s := g.String("Hello, World!")

s.Len() // 13
s.Upper() // "HELLO, WORLD!"
s.Lower() // "hello, world!"
s.Contains("World") // true
s.Split(", ").Collect() // ["Hello", "World!"]
s.Trim() // remove whitespace

// Conversions
s.Std() // Go string
s.Bytes() // Bytes type
g.String("42").TryInt() // Result[Int]

// Encoding
s.Hash().MD5() // hash
s.Encode().Base64() // encode
s.Compress().Gzip() // compress
```

---

## Int / Float

Numeric types with utility methods.

```go
i := g.Int(42)

i.Add(8) // 50
i.Mul(2) // 84
i.Abs() // absolute value
i.Min(10, 20) // minimum
i.Max(10, 20) // maximum

i.IsZero() // false
i.IsPositive() // true
i.IsNegative() // false

i.Binary() // binary string
i.Hex() // hex string

// Float
f := g.Float(3.14159)
f.Round() // Int(3)
f.RoundDecimal(2) // Float(3.14)
f.Sqrt() // square root

// Compare
i.Cmp(g.Int(50)) // cmp.Less
```

---

## Bytes

Extended byte slice.

```go
b := g.Bytes([]byte("Hello"))

b.Len()
b.Upper()
b.Lower()
b.Contains([]byte("ell"))

b.String() // to String
b.Std() // to []byte
```

---

## File / Directory

### File

```go
// Read/Write
content := g.NewFile("config.json").Read() // Result[String]
g.NewFile("output.txt").Write("Hello")
g.NewFile("log.txt").Append("line\n")

// Open a new file with the specified name "text.txt" and process it line by line.
g.NewFile("text.txt").
	Lines(). // Reads the file line by line.
	Skip(2). // Skips the first 2 lines in the iterator.
	Exclude(f.IsZero). // Excludes lines that are empty or contain only whitespaces.
	Dedup(). // Removes consecutive duplicate lines.
	Map(g.String.Upper). // Converts each line to uppercase.
	Range(func(s g.Result[g.String]) bool { // Iterates over the lines while a condition is true.
		if s.IsErr() { // Handles any errors encountered while reading lines.
			fmt.Println("Error:", s.Err())
			return false // Stops the iteration if an error occurs.
		}

		if s.Ok().Contains("COULD") { // Checks if the line contains the substring "COULD".
			return false // Stops the iteration if the condition is met.
		}

		fmt.Println(s.Ok()) // Prints the line.
		return true // Continues the iteration.
	})

// Properties
f := g.NewFile("test.txt")
f.Exist() // check existence
f.Stat() // file info
f.Copy("backup.txt") // copy
f.Rename("new.txt") // rename
f.Remove() // delete
```

### File Guard (Exclusive Lock)

```go
f := g.NewFile("data.txt").Guard() // holds exclusive lock
f.Write("exclusive data")
f.Close() // release lock
```

### Directory

```go
g.NewDir("mydir").Create()
g.NewDir("path/to/deep").CreateAll()

// Read contents
for file := range g.NewDir(".").Read() {
 if file.IsOk() {
 file.Ok().Name().Println()
 }
}

// Recursively walk through the directory tree starting from the current directory
g.NewDir(".").Walk().
	// Exclude directories and symlinked directories
	Exclude(func(f *g.File) bool { return f.IsDir() && f.Dir().Ok().IsLink() }).
 // Exclude file symlinks
	Exclude((*File).IsLink).
	// Process each walk result
	ForEach(func(v g.Result[*g.File]) {
		if v.IsOk() {
			// Print the path of the file if no error occurred
			v.Ok().Path().Ok().Println()
		}
	})

// Iterate over and print the names of files in the current directory with a *.go extension
g.NewDir("*.go").Glob().ForEach(func(f g.Result[*g.File]) { f.Ok().Name().Println() })

// Copy the contents of the current directory to a new directory named "copy".
g.NewDir(".").Copy("copy").Unwrap()
```

---

## Other Maps

### MapOrd — Ordered Map

Maintains insertion order.

```go
m := g.NewMapOrd[string, int]()
m.Insert("c", 3)
m.Insert("a", 1)
m.Insert("b", 2)

for k, v := range m.Iter() {
 fmt.Println(k, v) // c, a, b order
}

m.SortByKey(cmp.Cmp) // sort by key
m.SortByValue(cmp.Cmp) // sort by value
```

### MapSafe — Concurrent Map

Thread-safe for concurrent access.

```go
m := g.NewMapSafe[string, int]()

// Safe from multiple goroutines
go func() { m.Insert("a", 1) }()
go func() { m.Get("a") }()
```

---

## License

MIT License

Useful collection of helpfully functional Go collection utilities

Underscore.go
==========================================

Move Fast; Optimize Late
------------------------------------------

A useful collection of Go utilities. Designed for programmer happiness.

TL;DR Sort-of like underscore.js, but for Go

API Documentation
------------------------------------------
[GoDoc is WorkInProgress](https://godoc.org/github.com/tobyhede/go-underscore)


:warning: Warning
------------------------------------------
This package is in heavy flux at the moment as I work to incorporate feedback from various sources.


:squirrel: Todo
------------------------------------------

- [ ] godoc
- [ ] contains
- [ ] indexOf
- [ ] worker pools
- [x] parallel each
- [x] parallel map with worker pool
- [x] refactor to make functions first parameter (eg Each func(func(A), []A))
- [x] handle maps & slices
- [x] all
- [x] any
- [x] none



------------------------------------------
* [Notes on Typed Functions](#typed)
* [Any](#any)
* [Each](#each)
* [Every](#every)
* [Map](#map)
* [None](#none)


### <a name="typed"></a>Typed Functions ###
---------------------------------------------------------------------------


### <a name="any"></a>Any ###
---------------------------------------------------------------------------


### <a name="each"></a>Each ###
---------------------------------------------------------------------------

Each func(func(A int), []A)
Each func(func(A B), []A)


Applies the given iterator function to each element of a collection (slice or map).

If the collection is a Slice, the iterator function arguments are *value, index*

If the collection is a Map, the iterator function arguments are *value, key*

EachP is a Parallel implementation of Each and *concurrently* applies the given iterator function to each element of a collection (slice or map).


``` go
 // var Each func(func(value interface{}, i interface{}), interface{})

 var buffer bytes.Buffer

 fn := func(s, i interface{}) {
 buffer.WriteString(s.(string))
 }

 s := []string{"a", "b", "c", "d", "e"}
 Each(fn, s)

 expect := "abcde"

 e := un.Each(fn, s)

 fmt.Printf("%#v\n", e) //"abcde"
```

Typed Each can be defined using a function type and the *MakeEach* helper.

Using a Typed Slice

``` go
 var EachInt func(func(value, i int), []int)
 MakeEach(&EachInt)

 var sum int

 fn := func(v, i int) {
 sum += v
 }

 i := []int{1, 2, 3, 4, 5}
 EachInt(fn, i)

 fmt.Printf("%#v\n", sum) //15
```

Using a Typed Map
``` go
 var EachStringInt func(func(key string, value int), map[string]int)
 var sum int

 fn := func(v int, k string) {
 sum += v
 }

 m := map[string]int{"a": 1, "b": 2, "c": 3, "d": 4, "e": 5}
 EachStringInt(fn, m)

 fmt.Printf("%#v\n", sum) //15
```

Of note is the ability to close over variables within the calling scope.


### <a name="every"></a>Every ###
---------------------------------------------------------------------------




### Map ###
---------------------------------------------------------------------------

``` go
Map func([]A, func(A) B) []B
```

Applies the given function to each element of a slice, returning a slice of results

The base Map function accepts interface{} types and returns []interface{}

``` go
 // Map func(interface{}, func(interface{}) interface{}) []interface{}

 s := []string{"a", "b", "c", "d"}

 fn := func(s interface{}) interface{} {
 return s.(string) + "!"
 }

 m := un.Map(ToI(s), fn)
 fmt.Println(m) //["a!", "b!", "c!", "d!"]
```

Typed Maps can be defined using a function type and the *MakeMap* helper.

``` go
 Map func([]A, func(A) B) []B

 var SMap func([]string, func(string) string) []string
 un.MakeMap(&SMap)

 m := un.SMap(s, fn)
 fmt.Println(m) //["a!", "b!", "c!", "d!"]
```

Of note is the return value of Map is a slice of the return type of the applied function.


### Partition ###
---------------------------------------------------------------------------

Partition func([]A, func(A) bool) ([]A []A)

Partition splits a slice or map based on the evaluation of the supplied function

The base Partition function accepts interface{} types and returns []interface{}


``` go
 // Partition func(interface{}, func(interface{}) bool) ([]interface{}, []interface{})

 s := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}

 fn := func(i interface{}) bool {
 return (i.(int) % 2) == 1
 }

 odd, even := un.Partition(s, fn)

 fmt.Println(odd) //[1, 3, 5, 7, 9]
 fmt.Println(even) //[2, 4, 6, 8, 10]
```

Typed Partitions can be defined using a function type and the *MakePartition* helper.

``` go
 // Partition func([]A, func(A) bool) ([]A []A)

 var IPartition func([]int, func(int) bool) ([]int, []int)

 un.MakePartition(&IPartition)

 s := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}

 fn := func(i int) bool {
 return (i % 2) == 1
 }

 odd, even := un.IPartition(s, fn)

 fmt.Println(odd) //[1, 3, 5, 7, 9]
 fmt.Println(even) //[2, 4, 6, 8, 10]
```


Contains returns true if an object is in a slice.

``` go
 o := "a"
 s := []string{"a", "b", "c"}

 b := un.Contains(s, o)
 fmt.Println(b) //true
```


ToI converts a slice of arbitrary type []T into a slice of []interfaces{}

``` go
 s := []int{1, 1, 3, 5, 8, 13}
 i := un.ToI(s)
```




Notes
------------------------------------------

I am aware that the whole idea is not particularly very TheGoWay™, but it is useful as a learning exercise, and it is useful for moving fast and optimising later.

go-underscore

Generic option and result types that optionally contain a value

# valor

[![Go Reference](https://pkg.go.dev/badge/github.com/phelmkamp/valor.svg)](https://pkg.go.dev/github.com/phelmkamp/valor)
[![Go Report Card](https://goreportcard.com/badge/github.com/phelmkamp/valor)](https://goreportcard.com/report/github.com/phelmkamp/valor)
[![codecov](https://codecov.io/gh/phelmkamp/valor/branch/main/graph/badge.svg?token=GH8IYR78VD)](https://codecov.io/gh/phelmkamp/valor)

This module provides option and result types that optionally contain a value; hence the name valor, short for "value or".

This is not an attempt to make Go code look less like Go.
Instead, the goal is to codify the ["comma ok"](https://blog.toshima.ru/2019/07/21/go-comma-ok-idiom.html) and
["errors are values"](https://go.dev/blog/errors-are-values) principles that Go already encourages.

## Installation

```bash
go get github.com/phelmkamp/valor
```

## Types

### Value

[`optional.Value`](https://pkg.go.dev/github.com/phelmkamp/valor/optional) is modeled after the "comma ok" idiom.
It contains a value (ok) or nothing (not ok).

```go
m := map[string]int{"foo": 42}
val := optional.OfIndex(m, "foo")
fmt.Println(val.IsOk()) // true

var foo int
fmt.Println(val.Ok(&foo), foo) // true 42

valStr := optional.Map(val, strconv.Itoa)
fmt.Println(valStr) // {42 true}

val = optional.OfIndex(m, "bar")
fmt.Println(val.Or(-1))                          // -1
fmt.Println(val.OrZero())                        // 0
fmt.Println(val.OrElse(func() int { return 1 })) // 1
```

### Result

[`result.Result`](https://pkg.go.dev/github.com/phelmkamp/valor/result) contains either a value or an error.

```go
// traditional
if res := result.Of(w.Write([]byte("foo"))); res.IsError() {
    fmt.Println(res.Error())
    return
}

// try to get value, printing wrapped error if not ok
// note: only relevant values are in-scope after handling
var n int
if res := result.Of(w.Write([]byte("foo"))); !res.Value().Ok(&n) {
    fmt.Println(res.Errorf("Write() failed: %w").Error())
    return
}

// same as above with multiple values
var s string
var b bool
if res := two.TupleResultOf(multi(false)); !res.Value().Do(
    func(t two.Tuple[string, bool]) { s, b = t.Values() },
).IsOk() {
    fmt.Println(res.Errorf("multi() failed: %w").Error())
    return
}

// errors.Is
if res := result.Of(w.Write([]byte("foo"))); res.ErrorIs(io.ErrShortWrite) {
    fmt.Println(res.Error())
    return
}

// errors.As
if res := result.Of(w.Write([]byte("foo"))); res.IsError() {
    var err *fs.PathError
    if res.ErrorAs(&err) {
        fmt.Println("path=" + err.Path)
    }
    fmt.Println(res.Error())
    return
}

// errors.Unwrap
if res := result.Of(mid(true)); res.IsError() {
    fmt.Println(res.ErrorUnwrap().Error())
    return
}
```

### Tuples

[`unit.Type`](https://pkg.go.dev/github.com/phelmkamp/valor/tuple/unit), [`singleton.Set`](https://pkg.go.dev/github.com/phelmkamp/valor/tuple/singleton),
[`two.Tuple`](https://pkg.go.dev/github.com/phelmkamp/valor/tuple/two), [`three.Tuple`](https://pkg.go.dev/github.com/phelmkamp/valor/tuple/three), and
[`four.Tuple`](https://pkg.go.dev/github.com/phelmkamp/valor/tuple/four) contain zero through four values respectively.
Among other things, they enable `Value` and `Result` to contain a variable number of values.

{% raw %}
```go
get := func(string, int, bool) {
    return "a", 1, true
}
val := two.TupleValueOf(get())
fmt.Println(val) // {{a 1} true}
```
{% endraw %}

### Enum

[`enum.Enum`](https://pkg.go.dev/github.com/phelmkamp/valor/enum) is an enumerated type.
It's initialized with a set of allowed values and then each "copy" optionally contains a currently selected value.

```go
const (
	Clubs    = "clubs"
	Diamonds = "diamonds"
	Hearts   = "hearts"
	Spades   = "spades"
)
var Suit = enum.OfString(Clubs, Diamonds, Hearts, Spades)
func main() {
    fmt.Println(Suit.Values())          // [clubs diamonds hearts spades]
    fmt.Println(Suit.ValueOf("Foo"))    // { false}
    fmt.Println(Suit.ValueOf(Hearts))   // {hearts true}
}
```

## Similar concepts in other languages

### Rust

`Value` is like Rust's [`Option`](https://doc.rust-lang.org/std/option/enum.Option.html).
`Result` is like Rust's [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html).

A `switch` statement provides similar semantics to Rust's `match`:

```go
var foo int
switch val {
case val.OfOk():
    foo = val.MustOk()
    fmt.Println("Ok", foo)
case optional.OfNotOk[int]():
    fmt.Println("Not Ok")
    return
}

var n int
switch res {
case res.OfOk():
    n = res.Value().MustOk()
    fmt.Println("Ok", n)
case res.OfError():
    fmt.Println("Error", res.Error())
    return
}
```

### Java

`Value` is like Java's [`Optional`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Optional.html).

### More

 * [https://en.wikipedia.org/wiki/Result_type](https://en.wikipedia.org/wiki/Result_type)
 * [https://en.wikipedia.org/wiki/Option_type](https://en.wikipedia.org/wiki/Option_type)

## Releases

This module is currently at v0 but every effort will be made to avoid breaking changes.
Instead, functionality will be deprecated as needed with plans to remove in v1.

## Linter

[valorcheck](https://github.com/phelmkamp/valor/tree/main/valorcheck#readme) is a linter to check that access to an optional value is guarded against the case where the value is not present.


valor

Functional helpers library providing Map, Filter, Reduce and other stream operations on generic slices Go1.18+ with lazy evaluation and error handling mechanisms

The Best Go Libraries For Functional - Functional (11)