Fp-Go

https://github.com/ibm/fp-go
Admin
Functional programming library for Go 1.24+, inspired by fp-ts. Uses generic type aliases for a...
Tokens:2,573,332
Snippets:10,583
Trust Score:10
License:Apache-2.0
Update:16 hours ago
Show doc for...
Tokens:
Raw
### Install fp-go v2 with go get

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Install the fp-go v2 library. Requires Go 1.24 or later for generic type alias support.

```bash
go get github.com/IBM/fp-go/v2
```

--------------------------------

### Iso Example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Demonstrates creating an Iso for Celsius to Fahrenheit conversion and using Get and ReverseGet.

```go
import "github.com/IBM/fp-go/v2/optics/iso"

celsiusToFahrenheit := iso.MakeIso(
    func(c float64) float64 { return c*9/5 + 32 },
    func(f float64) float64 { return (f - 32) * 5 / 9 },
)
f := celsiusToFahrenheit.Get(100.0)        // 212.0
c := celsiusToFahrenheit.ReverseGet(212.0) // 100.0
```

--------------------------------

### Full Working Example: DI setup with DB, Cache, and App services

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Complete example showing token definition, provider registration, and application startup. Uses MakeProvider0 for zero-dependency services and MakeProvider2 for the app with two required dependencies. Includes a testProviders function that swaps in constant providers for testing.

```go
package main

import (
    "fmt"
    "github.com/IBM/fp-go/v2/di"
    DIE "github.com/IBM/fp-go/v2/di/erasure"
    "github.com/IBM/fp-go/v2/ioresult"
)

// Define tokens
var (
    TokenDB     = di.MakeToken[*DBService]("DBService")
    TokenCache  = di.MakeToken[*CacheService]("CacheService")
    TokenApp    = di.MakeToken[*App]("App")
)

// Providers
func dbProvider() DIE.Provider {
    return di.MakeProvider0(TokenDB, ioresult.Of(&DBService{url: "postgres://..."}))
}

func cacheProvider() DIE.Provider {
    return di.MakeProvider0(TokenCache, ioresult.Of(&CacheService{ttl: 300}))
}

func appProvider() DIE.Provider {
    return di.MakeProvider2(
        di.InjMain,              // register as main
        TokenDB.Identity(),      // required dependency
        TokenCache.Identity(),   // required dependency
        func(db *DBService) func(cache *CacheService) di.IOResult[any] {
            return func(cache *CacheService) di.IOResult[any] {
                return ioresult.Of[any](&App{db: db, cache: cache})
            }
        },
    )
}

func main() {
    err := di.RunMain([]DIE.Provider{
        dbProvider(),
        cacheProvider(),
        appProvider(),
    })()
    if err != nil {
        fmt.Println("Error:", err)
    }
}

// For testing: swap providers
func testProviders() []DIE.Provider {
    return []DIE.Provider{
        di.ConstProvider(TokenDB, &DBService{url: "sqlite://test"}),
        di.ConstProvider(TokenCache, &CacheService{ttl: 0}),
        appProvider(),
    }
}
```

--------------------------------

### Lens Example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Demonstrates creating and using lenses for a Person struct, including get, set, modify, and compose operations.

```go
type Address struct {
    Street string
    City   string
}

type Person struct {
    Name    string
    Address Address
}

nameLens := lens.MakeLens(
    func(p Person) string { return p.Name },
    func(p Person, n string) Person { p.Name = n; return p },
)

// Get
name := lens.Get(nameLens)(person)

// Set
updated := lens.Set(nameLens)("Alice")(person)

// Modify
uppered := lens.Modify(strings.ToUpper)(nameLens)(person)

// Compose lenses
addressLens := lens.MakeLens(
    func(p Person) Address { return p.Address },
    func(p Person, a Address) Person { p.Address = a; return p },
)
cityLens := lens.MakeLens(
    func(a Address) string { return a.City },
    func(a Address, c string) Address { a.City = c; return a },
)
personCityLens := F.Pipe1(addressLens, lens.Compose[Person](cityLens))
```

--------------------------------

### Example Test File Template

Source: https://github.com/ibm/fp-go/blob/main/v2/EXAMPLE_TESTS_PROGRESS.md

Template for creating example test files in Go. Includes package import, example function, and expected output comment.

```go
// Copyright header...

package packagename_test

import (
	"fmt"
	PKG "github.com/IBM/fp-go/v2/packagename"
)

func ExampleFunctionName() {
	// Copy example from doc comment
	// Ensure it compiles and produces correct output
	fmt.Println(result)
	// Output:
	// expected output
}
```

--------------------------------

### Install fp-go with go get

Source: https://github.com/ibm/fp-go/blob/main/README.md

Install the fp-go library using the Go module tool. Run this command in your project directory to add the dependency.

```bash
go get github.com/IBM/fp-go
```

--------------------------------

### Transformation Pipeline Example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Shows a left-to-right pipeline using Reduce, but notes that it starts from the zero value, so use Read or Build for specific starting values.

```go
// Left-to-right pipeline execution
result := endomorphism.Reduce([]endomorphism.Endomorphism[string]{
    strings.TrimSpace,
    strings.ToLower,
    func(s string) string { return strings.ReplaceAll(s, " ", "-") },
})
// "" -> "" -> "" -> "" (from zero value)
// Use Read or Build for specific starting values
```

--------------------------------

### Do-notation Example with State and Pipeline

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Example of do-notation using EFF.Do, EFF.Bind, and EFF.Let to compose effects that fetch user and posts, then set count. Requires State struct and AppConfig context.

```go
type State struct {
    User    User
    Posts   []Post
    Count   int
}

pipeline := F.Pipe3(
    EFF.Do[AppConfig](State{}),
    EFF.Bind(
        func(u User) func(State) State {
            return func(s State) State { s.User = u; return s }
        },
        func(_ State) EFF.Effect[AppConfig, User] {
            return fetchUserEff(123)
        },
    ),
    EFF.Bind(
        func(ps []Post) func(State) State {
            return func(s State) State { s.Posts = ps; return s }
        },
        func(s State) EFF.Effect[AppConfig, []Post] {
            return fetchPostsEff(s.User.ID)
        },
    ),
    EFF.Let(
        func(c int) func(State) State {
            return func(s State) State { s.Count = c; return s }
        },
        func(s State) int { return len(s.Posts) },
    ),
)
```

--------------------------------

### Example Function Template with Output Comment

Source: https://github.com/ibm/fp-go/blob/main/v2/AGENTS.md

Template for creating Go example functions in *_test.go files. Must include the // Output: comment for go test recognition. Use idiomatic patterns and realistic runnable code.

```go
// ExampleFunctionName demonstrates basic usage.
func ExampleFunctionName() {
    result := FunctionName(42)
    fmt.Println(result)
    // Output: 42
}
```

--------------------------------

### Pipe vs Flow comparison example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Shows the difference between Pipe (immediate evaluation with a value) and Flow (creating a reusable function). The example uses double and toString functions.

```go
// Pipe: immediate evaluation with a value
result := F.Pipe2(42, double, toString)

// Flow: create a reusable function
transform := F.Flow2(double, toString)
result1 := transform(42)
result2 := transform(99)
```

--------------------------------

### Alt example with option.Alt

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Provides an alternative computation if the first one fails or is empty. The example returns Some(42) when the primary is None.

```go
primary := option.None[int]()
fallback := option.Alt(func() option.Option[int] {
    return option.Some(42)
})
result := fallback(primary) // Some(42)
```

--------------------------------

### Option usage example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Demonstrates piping a Some value through Filter, Map, and GetOrElse, resulting in "value: 42".

```go
import (
    O "github.com/IBM/fp-go/v2/option"
    F "github.com/IBM/fp-go/v2/function"
)

result := F.Pipe3(
    O.Some(42),
    O.Filter(func(x int) bool { return x > 0 }),
    O.Map(func(x int) string { return fmt.Sprintf("value: %d", x) }),
    O.GetOrElse(func() string { return "no value" }),
)
// result == "value: 42"
```

--------------------------------

### effect - Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-cookbook.md

Starts do-notation for Effects.

```APIDOC
## Do[C](s)

### Description
Starts do-notation for Effects.

### Parameters
- **s** (any) - Required - The initial state.

### Returns
- **Effect[C, any]** - An Effect for do-notation.
```

--------------------------------

### package lazy - Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Starts a do-notation block.

```APIDOC
## func Do

### Description
Starts a do-notation block.

### Signature
```go
func Do[S any](
```

### Parameters
- **S** (any) - Required - The state type.
```

--------------------------------

### Filter examples for Option and Array

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Shows how to use option.Filter and array.Filter to keep values that satisfy a predicate. The Option example converts Some to None when the predicate fails, and the Array example filters elements in a slice.

```go
// Option
isPositive := option.Filter(func(x int) bool { return x > 0 })
result1 := isPositive(option.Some(42))  // Some(42)
result2 := isPositive(option.Some(-5))  // None

// Array
evens := array.Filter(func(x int) bool { return x%2 == 0 })
result := evens([]int{1, 2, 3, 4, 5}) // [2, 4]
```

--------------------------------

### Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Initializes a do-notation block. This is useful for starting a sequence of computations.

```APIDOC
## Do

### Description
Initializes a do-notation block. This is useful for starting a sequence of computations.

### Signature
```go
func Do[R, S any](
```

### Parameters
- **R** - Required - The environment type.
- **S** - Required - The state type.
```

--------------------------------

### Do-notation (building up state)

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-claude.md

Use R.Do, R.Bind, and R.Let to build up state in a functional way. The example shows binding an integer and letting a string derived from it.

```go
type State struct { X int; Y string }

result := F.Pipe3(
    R.Do(State{}),
    R.Bind(
        func(x int) func(State) State {
            return func(s State) State { s.X = x; return s }
        },
        func(s State) Result[int] { return R.Of(42) },
    ),
    R.Let(
        func(y string) func(State) State {
            return func(s State) State { s.Y = y; return s }
        },
        func(s State) string { return fmt.Sprintf("val=%d", s.X) },
    ),
)
```

--------------------------------

### option.AltAllArray(start)

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/PATTERN_MATCHING.md

Returns the first Some among an array of existing Options. Input is eager.

```APIDOC
## option.AltAllArray(start)

### Description
Returns the first Some among an array of existing Options. Input is eager.

### Signature
`func([]Option[A]) Option[A]`

### Parameters
- **start** (Option[A]) - The initial option.

### Returns
- **func([]Option[A]) Option[A]** - A function that returns the first Some.
```

--------------------------------

### Result example: Unwrap with Pipe2

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Shows how to use R.Unwrap with F.Pipe2 to chain operations on a Result. The example converts "42" to an integer and doubles it, resulting in val == 84 and err == nil.

```go
import (
    R "github.com/IBM/fp-go/v2/result"
    F "github.com/IBM/fp-go/v2/function"
)

val, err := R.Unwrap(F.Pipe2(
    R.TryCatchError(strconv.Atoi("42")),
    R.Map(func(n int) int { return n * 2 }),
))
// val == 84, err == nil
```

--------------------------------

### Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Starts a do-notation block for IOResult, enabling monadic composition.

```APIDOC
## Do

### Description
Starts a do-notation block for IOResult, enabling monadic composition.

### Signature
func Do[S any](

### Parameters
- (parameters not fully specified in source)

### Returns
(not specified in source)
```

--------------------------------

### Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Starts a do-notation block for composing effects.

```APIDOC
## Do

### Description
Starts a do-notation block for composing effects.

### Signature
```go
func Do[C, S any](
```
```

--------------------------------

### func Do[ST, A any](

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Starts a do-notation block for stateful computations.

```APIDOC
## func Do[ST, A any](

### Description
Starts a do-notation block for stateful computations.

### Signature
```go
func Do[ST, A any](
```
```

--------------------------------

### stateless.Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Starts a do-notation block for iterators.

```APIDOC
## Do[S any](

### Description
Starts a do-notation block for iterators, allowing monadic composition.

### Parameters
- **S** (type parameter) - The state type.

### Usage
```go
result := stateless.Do[int]()
```
```

--------------------------------

### Pipe usage example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Value-first pipeline using Pipe3. The initial value is passed through three transform functions in order.

```go
result := F.Pipe3(
    someValue,          // initial value
    firstTransform,     // T0 -> T1
    secondTransform,    // T1 -> T2
    thirdTransform,     // T2 -> T3
)
```

--------------------------------

### Real-World Example: User Registration Validation Chain

Source: https://github.com/ibm/fp-go/blob/main/v2/CHAINING_PERFORMANCE_ANALYSIS.md

Comment-only placeholder for the validation chain: email → trim → lowercase → check format → check uniqueness. This is the context for the following performance examples.

```go
// Validate: email → trim → lowercase → check format → check uniqueness
```

--------------------------------

### func Do[R, S any](

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Starts a do-notation block for sequencing ReaderIOResult computations. This is the entry point for the do-notation syntax.

```APIDOC
## func Do[R, S any](

### Description
Starts a do-notation block for sequencing ReaderIOResult computations. This is the entry point for the do-notation syntax.

### Signature
func Do[R, S any](

### Parameters
- **R** (type parameter) - The environment type.
- **S** (type parameter) - The state type.

### Returns
- A do-notation builder.

```

--------------------------------

### option.AltAllSeq(start)

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/PATTERN_MATCHING.md

Returns the first Some among a sequence of Options. Works with iterators.

```APIDOC
## option.AltAllSeq(start)

### Description
Returns the first Some among a sequence of Options. Works with iterators.

### Signature
`func(Seq[Option[A]]) Option[A]`

### Parameters
- **start** (Option[A]) - The initial option.

### Returns
- **func(Seq[Option[A]]) Option[A]** - A function that returns the first Some.
```

--------------------------------

### Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Starts a monadic do-notation block for ReaderResult.

```APIDOC
## Do

### Description
Starts a monadic do-notation block for ReaderResult.

### Signature
func Do[R, S any](

### Parameters
- **R** (type) - Required - The environment type.
- **S** (type) - Required - The state type for the do-notation.

### Returns
- (incomplete signature in source)
```

--------------------------------

### Middleware Chain Example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Shows how to compose HTTP middleware using endomorphisms, with right-to-left composition wrapping order.

```go
type Handler = func(http.Request) http.Response
type Middleware = endomorphism.Endomorphism[Handler]

logging := func(h Handler) Handler { /* wrap with logging */ }
auth := func(h Handler) Handler { /* wrap with auth */ }
cors := func(h Handler) Handler { /* wrap with CORS */ }

// Compose middlewares (right-to-left: cors wraps auth wraps logging)
stack := endomorphism.ConcatAll([]Middleware{cors, auth, logging})
finalHandler := stack(baseHandler)
```

--------------------------------

### Preload

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/EFFECT_TIER2_PLAN.md

Resolves the given tokens eagerly, for example at startup. This moves the cost of building and discovery of missing providers to startup.

```APIDOC
## Preload

### Description
Resolves the given tokens eagerly, for example at startup.

### Signature
```go
func Preload(tokens ...erasure.Dependency) Effect[Injector, Void]
```

### Parameters
- **tokens** (erasure.Dependency) - Required - The tokens to resolve eagerly.

### Returns
- **Effect[Injector, Void]** - An effect that resolves the tokens when run.

```

--------------------------------

### Example Test Pattern: TestFromReaderResult_Success

Source: https://github.com/ibm/fp-go/blob/main/v2/AGENTS.md

Shows a complete test function using result.Eitherize1, FromReaderResult, and assert.Equal. Tests conversion of a successful ReaderResult.

```go
func TestFromReaderResult_Success(t *testing.T) {
    t.Run("converts successful ReaderResult", func(t *testing.T) {
        // Arrange
        parseIntRR := result.Eitherize1(strconv.Atoi)
        validator := FromReaderResult[string, int](parseIntRR)
        
        // Act
        result := validator("42")(nil)
        
        // Assert
        assert.Equal(t, validation.Success(42), result)
    })
}
```

--------------------------------

### option.Do Example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Initializes an Option context with an empty struct. The result is Some(Result{x: 0, y: ""}).

```go
type Result struct {
    x int
    y string
}

result := option.Do(Result{})
// Result: Some(Result{x: 0, y: ""})
```

--------------------------------

### option.Bind Example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Builds a State context sequentially using option.Bind. The result is Some(State{x: 42, y: 84}).

```go
type State struct {
    x int
    y int
}

result := F.Pipe2(
    option.Do(State{}),
    option.Bind(
        func(x int) func(State) State {
            return func(s State) State { s.x = x; return s }
        },
        func(s State) option.Option[int] { return option.Some(42) },
    ),
    option.Bind(
        func(y int) func(State) State {
            return func(s State) State { s.y = y; return s }
        },
        func(s State) option.Option[int] { return option.Some(s.x * 2) },
    ),
) // Some(State{x: 42, y: 84})
```

--------------------------------

### IO example: greeting with delay

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Shows how to create an IO that maps a string and delays execution. Calling greeting() waits 1 second and returns "Hello, World!".

```go
import (
    IO "github.com/IBM/fp-go/v2/io"
    F "github.com/IBM/fp-go/v2/function"
)

greeting := F.Pipe2(
    IO.Of("World"),
    IO.Map(func(s string) string { return "Hello, " + s + "!" }),
    IO.Delay[string](time.Second),
)
result := greeting() // waits 1 second, returns "Hello, World!"
```

--------------------------------

### Optics (Lens)

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-claude.md

Create a lens with L.MakeLens to get, set, and modify a field. The example shows a Person struct and operations on the Name field.

```go
type Person struct { Name string; Age int }

nameLens := L.MakeLens(
    func(p Person) string { return p.Name },
    func(p Person, name string) Person { p.Name = name; return p },
)

name := nameLens.Get(person)              // get
updated := nameLens.Set("Bob")(person)    // set (returns new Person)
modified := L.Modify(strings.ToUpper)(nameLens)(person) // modify
```

--------------------------------

### Running Effects with Provide and RunSync

Source: https://github.com/ibm/fp-go/blob/main/v2/FUNCTIONAL_IO.md

Demonstrates how to run an effect by providing dependencies, converting to a Thunk, running synchronously, and executing with a runtime context.

```go
func main() {
    // Set up typed dependencies once
    services := Services{
        UserRepo: &PostgresUserRepo{db: db},
        EmailSvc: &SMTPEmailService{host: "smtp.example.com"},
    }

    // Build the effect pipeline (no execution yet)
    userEffect := processUser(42, "new@email.com")

    // Provide dependencies - returns a Thunk (ReaderIOResult)
    thunk := effect.Provide(services)(userEffect)

    // Run synchronously - returns a func(context.Context) (User, error)
    readerResult := effect.RunSync(thunk)

    // Execute with runtime context
    user, err := readerResult(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Updated user: %+v\n", user)
}
```

--------------------------------

### Composing Retry Policies

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Shows how to combine retry policies using the Monoid. The example creates a policy that retries up to 5 times with exponential backoff starting at 100ms and capped at 10 seconds.

```go
import M "github.com/IBM/fp-go/v2/monoid"

// Retry up to 5 times with exponential backoff capped at 10s
policy := M.ConcatAll(retry.Monoid)([]retry.RetryPolicy{
    retry.LimitRetries(5),
    retry.CapDelay(10*time.Second, retry.ExponentialBackoff(100*time.Millisecond)),
})
```

--------------------------------

### Chain function signature and usage

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Chain is monadic bind in curried form, sequencing two computations where the second depends on the first. The usage example pipes a Result[A] through Chain to get Result[B].

```go
// Chain for result
func Chain[A, B any](f Kleisli[A, B]) Operator[A, B]
```

```go
// Usage: pipe a Result[A] through Chain to get Result[B]
result := F.Pipe2(
    getUser(id),                    // Result[User]
    result.Chain(func(u User) Result[Order] {
        return getLatestOrder(u.ID)
    }),
    result.Chain(func(o Order) Result[string] {
        return formatOrder(o)
    }),
)
```

--------------------------------

### TraverseArrayPar for concurrent IO operations

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-cookbook.md

Uses readerioresult.TraverseArrayPar to execute an array of IO operations in parallel with context.Context. The fetchStatus function creates a ReaderIOResult that performs an HTTP GET request and returns the status code. The example shows how to define the operation and the parallel traversal, with the result being a Result[[]int].

```go
package main

import (
    "context"
    "net/http"
    RIOE "github.com/IBM/fp-go/v2/context/readerioresult"
    R "github.com/IBM/fp-go/v2/result"
)

func fetchStatus(url string) RIOE.ReaderIOResult[int] {
    return func(ctx context.Context) func() R.Result[int] {
        return func() R.Result[int] {
            req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
            if err != nil { return R.Left[int](err) }
            resp, err := http.DefaultClient.Do(req)
            if err != nil { return R.Left[int](err) }
            defer resp.Body.Close()
            return R.Right(resp.StatusCode)
        }
    }
}

// Parallel execution: all URLs fetched concurrently
var fetchAllStatuses = RIOE.TraverseArrayPar(fetchStatus)
// fetchAllStatuses(urls)(ctx)() => Result[[]int]
```

--------------------------------

### V1 Complex Example with generic subpackages

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Shows the previous fp-go v1 style using generic subpackages (either/generic, ioeither/generic) to map over an IOEither. Requires importing multiple generic packages and explicit type parameters.

```go
import (
    ET "github.com/IBM/fp-go/either"
    EG "github.com/IBM/fp-go/either/generic"
    IOET "github.com/IBM/fp-go/ioeither"
    IOEG "github.com/IBM/fp-go/ioeither/generic"
)

func process() IOET.IOEither[error, string] {
    return IOEG.Map[error, int, string](
        strconv.Itoa,
    )(fetchData())
}
```

--------------------------------

### Option and Either Chain examples

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Shows sequential composition with option.Chain for dependent operations and either.Chain for error handling pipelines. The Option example returns Some(20) for input 5, and the Either example parses a string to return Right(42).

```go
// Option - dependent operations
safeDivide := func(x int) option.Option[int] {
    if x == 0 { return option.None[int]() }
    return option.Some(100 / x)
}
result := F.Pipe1(
    option.Some(5),
    option.Chain(safeDivide),
) // Some(20)

// Either - error handling pipeline
parseAndValidate := F.Pipe1(
    either.Right[error]("42"),
    either.Chain(func(s string) either.Either[error, int] {
        return result.Eitherize1(strconv.Atoi)(s)
    }),
) // Right(42)
```

--------------------------------

### Working with Option in Go

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Demonstrates creating Option values, mapping over them, and chaining operations into a reusable pipeline. Uses F.Pipe2, O.Map, O.GetOrElse, and F.Flow3. Outputs: 84, Positive: 42, No value.

```go
package main

import (
    "fmt"

    F "github.com/IBM/fp-go/v2/function"
    "github.com/IBM/fp-go/v2/lazy"
    N "github.com/IBM/fp-go/v2/number"
    O "github.com/IBM/fp-go/v2/option"
    S "github.com/IBM/fp-go/v2/string"
)

func main() {
    // Create an Option
    some := O.Some(42)
    none := O.None[int]()

    // Map over values
    doubled := F.Pipe2(some, O.Map(N.Mul(2)), O.GetOrElse(lazy.Of(0)))
    fmt.Println(doubled) // Output: 84

    // Chain operations into a reusable pipeline
    describePositive := F.Flow3(
        O.Chain(O.FromPredicate(N.MoreThan(0))),
        O.Map(S.Format[int]("Positive: %d")),
        O.GetOrElse(lazy.Of("No value")),
    )

    fmt.Println(describePositive(some)) // Output: Positive: 42
    fmt.Println(describePositive(none)) // Output: No value
}
```

--------------------------------

### Fold examples for Option and Either

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Shows how to use option.Fold and either.Fold to collapse monadic values into plain values, handling both success and error cases. The Option example returns a string for None or Some, and the Either example handles Left (error) and Right (success).

```go
// Option
result := F.Pipe1(
    option.Some(42),
    option.Fold(
        func() string { return "no value" },
        func(x int) string { return fmt.Sprintf("value: %d", x) },
    ),
) // "value: 42"

// Either
result := F.Pipe1(
    either.Right[error](42),
    either.Fold(
        func(e error) string { return "error: " + e.Error() },
        func(x int) string { return fmt.Sprintf("success: %d", x) },
    ),
) // "success: 42"
```

--------------------------------

### V2 Simplified Example with ioresult and F.Pipe1

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Shows the new fp-go v2 style using the ioresult package and F.Pipe1 for a cleaner API. Uses a type alias IOResult and avoids generic subpackages.

```go
import (
    "strconv"

    F "github.com/IBM/fp-go/v2/function"
    "github.com/IBM/fp-go/v2/ioresult"
)

type IOResult[A any] = ioresult.IOResult[A]

func process() IOResult[string] {
    return F.Pipe1(fetchData(), ioresult.Map(strconv.Itoa))
}
```

--------------------------------

### Before: Importing generic Subpackage

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Shows the import of a generic subpackage before migration.

```go
import (
    E "github.com/IBM/fp-go/either/generic"
)
```

--------------------------------

### Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Initializes a do-notation context. The function signature is partially shown.

```APIDOC
## Do

### Description
Initializes a do-notation context. The function signature is partially shown.

### Signature
```go
func Do[R, S any](
```

### Parameters
- (incomplete signature)
```

--------------------------------

### Flatten example with option.Flatten and array.Flatten

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Removes one level of nesting from a nested monadic structure. The example shows flattening an option and a slice.

```go
nested := option.Some(option.Some(42))
result := option.Flatten(nested) // Some(42)

nested := [][]int{{1, 2}, {3, 4}}
result := array.Flatten(nested) // [1, 2, 3, 4]
```

--------------------------------

### After: Import Paths with v2

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Shows the import paths after migration, using github.com/IBM/fp-go/v2.

```go
import (
    "github.com/IBM/fp-go/v2/either"
    "github.com/IBM/fp-go/v2/option"
)
```

--------------------------------

### Tap example with ioresult.Tap

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Alias for ChainFirst, executes a side effect while preserving the original value. The example returns (42, nil) after the side effect.

```go
result := F.Pipe1(
    ioresult.Of(42),
    ioresult.Tap(func(x int) ioresult.IOResult[string] {
        return ioresult.Of(fmt.Sprintf("Processing: %d", x))
    }),
)() // Returns (42, nil) after side effect
```

--------------------------------

### ChainFirst example with option.ChainFirst

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Executes a monadic computation for side effects but returns the original value. The example logs the value and returns the original Some(42).

```go
logValue := option.ChainFirst(func(x int) option.Option[string] {
    fmt.Printf("Value: %d\n", x)
    return option.Some(fmt.Sprintf("logged: %d", x))
})

result := F.Pipe1(option.Some(42), logValue)
// Prints "Value: 42", returns Some(42)
```

--------------------------------

### Before: Import Paths without v2

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Shows the import paths before migration, using github.com/IBM/fp-go.

```go
import (
    "github.com/IBM/fp-go/either"
    "github.com/IBM/fp-go/option"
)
```

--------------------------------

### WithResource

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Creates a Kleisli that manages a resource.

```APIDOC
## WithResource

### Description
Creates a Kleisli that manages a resource.

### Signature
func WithResource[A, R, ANY any](

### Parameters
- **A** (any) - Required - The input type.
- **R** (any) - Required - The resource type.
- **ANY** (any) - Required - The output type.

### Returns
Kleisli[A, R] - The resulting Kleisli.
```

--------------------------------

### Option and Either Ap examples

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Shows how to use option.Ap to combine independent Option values and either.Ap for fail-fast error handling. The Option example pipes a wrapped add function with two wrapped arguments to produce Some(42). The Either example applies a wrapped multiplication function to a wrapped value, yielding Right(42).

```go
// Option - combining independent values
add := func(x int) func(int) int {
    return func(y int) int { return x + y }
}
result := F.Pipe2(
    option.Some(add),
    option.Ap(option.Some(10)),
    option.Ap(option.Some(32)),
) // Some(42)

// Either - fail-fast on first error
result := F.Pipe1(
    either.Right[error](N.Mul(2)),
    either.Ap[int](either.Right[error](21)),
) // Right(42)
```

--------------------------------

### Intercalate usage example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Example of joining strings with a comma separator using Intercalate and the string monoid. Outputs "a, b, c".

```go
import (
    A "github.com/IBM/fp-go/v2/array"
    S "github.com/IBM/fp-go/v2/string"
)

joined := A.Intercalate(S.Monoid)(", ")([]string{"a", "b", "c"})
// "a, b, c"
```

--------------------------------

### Traverse with Option example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Example of using Traverse with Option to parse a slice of strings into integers. Returns Some([1,2,3]) for valid input and None if any parse fails.

```go
parseAll := array.Traverse(
    option.Of[[]int],
    option.Map[[]int, func(int) []int],
    option.Ap[[]int, int],
    func(s string) option.Option[int] {
        n, err := strconv.Atoi(s)
        if err != nil { return option.None[int]() }
        return option.Some(n)
    },
)

parseAll([]string{"1", "2", "3"}) // Some([1, 2, 3])
parseAll([]string{"1", "x", "3"}) // None
```

--------------------------------

### Apache 2.0 License Header for Go Files

Source: https://github.com/ibm/fp-go/blob/main/v2/AGENTS.md

Required header for every file in the project. Includes copyright notice and full license text.

```go
// Copyright (c) 2023 - 2025 IBM Corp.
// All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
```

--------------------------------

### Sorting example with SortBy

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Example of sorting a slice of Person structs by age then name using SortBy with multiple Ord instances. Requires importing array and ord packages.

```go
import (
    A "github.com/IBM/fp-go/v2/array"
    "github.com/IBM/fp-go/v2/ord"
)

type Person struct { Name string; Age int }

byAge := ord.ContraMap(func(p Person) int { return p.Age })(ord.FromStrictCompare[int]())
byName := ord.ContraMap(func(p Person) string { return p.Name })(ord.FromStrictCompare[string]())

sorted := A.SortBy([]ord.Ord[Person]{byAge, byName})(people)
```

--------------------------------

### Option Monoids Example: ApplicativeMonoid and FirstMonoid

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/COMMON_MONAD_FUNCTIONS.md

Shows how to use option.ApplicativeMonoid to combine Some values (returning None if any is None) and option.FirstMonoid to take the first Some value. The example uses number.MonoidSum[int]() as the inner semigroup for ApplicativeMonoid.

```go
// ApplicativeMonoid - combines values inside Some
m := option.ApplicativeMonoid(number.MonoidSum[int]())
result := m.Concat(option.Some(5), option.Some(3))  // Some(8)
result2 := m.Concat(option.Some(5), option.None[int]())  // None

// FirstMonoid - takes first Some
firstM := option.FirstMonoid[int]()
result3 := firstM.Concat(option.Some(5), option.Some(3))  // Some(5)
```

--------------------------------

### Ask

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Returns the environment R as a ReaderResult.

```APIDOC
## Ask

### Description
Returns the environment R as a ReaderResult.

### Signature
func Ask[R any]() ReaderResult[R, R]

### Returns
- **ReaderResult[R, R]** - A ReaderResult that yields the environment R.
```

--------------------------------

### FromIO

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Lifts an IO into an IOEither.

```APIDOC
## FromIO

### Description
Lifts an IO into an IOEither.

### Signature
func FromIO[E, A any](mr IO[A]) IOEither[E, A]

### Parameters
- **mr** (IO[A]) - Required - The IO to lift

### Returns
- **IOEither[E, A]** - The lifted IOEither.
```

--------------------------------

### iso.Iso.String

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Implements fmt.Stringer for Iso.

```APIDOC
## [METHOD] String

### Description
Implements fmt.Stringer for Iso.

### Signature
```go
func (i Iso[S, T]) String() string
```

### Returns
- A string representation of the Iso.
```

--------------------------------

### Do

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Monadic do-notation for sequencing IO actions.

```APIDOC
## Do

### Description
Monadic do-notation for sequencing IO actions.

### Signature
```go
func Do[S any](
```
```

--------------------------------

### After: Importing v2 either Package

Source: https://github.com/ibm/fp-go/blob/main/v2/README.md

Shows the import after removing the generic subpackage and using the v2 either package.

```go
import (
    "github.com/IBM/fp-go/v2/either"
)
```

--------------------------------

### Lens Operations

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Provides functions to get, set, modify, and compose lenses.

```go
func Get[S, A any](sa Lens[S, A]) func(S) A
func Set[S, A any](sa Lens[S, A]) func(A) func(S) S
func Modify[S any, FCT ~func(A) A, A any](f FCT) func(Lens[S, A]) func(S) S
func Compose[S, A, B any](ab Lens[A, B]) func(Lens[S, A]) Lens[S, B]
```

--------------------------------

### FromOption

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Creates a Kleisli from an Option, handling the None case.

```APIDOC
## FromOption

### Description
Creates a Kleisli from an Option, handling the None case.

### Signature
func FromOption[R, A any](onNone Lazy[error]) Kleisli[R, Option[A], A]

### Parameters
- **onNone** (Lazy[error]) - Required - The error to use when the option is None.

### Returns
- **Kleisli[R, Option[A], A]** - The Kleisli.
```

--------------------------------

### stateless.Count

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Creates an iterator that counts from a start value.

```APIDOC
## Count(start int) Iterator[int]

### Description
Creates an iterator that counts from a start value, incrementing by 1 each time.

### Parameters
- **start** (int) - Required - The starting value.

### Returns
- **Iterator[int]** - An iterator of integers.

### Usage
```go
iter := stateless.Count(0)
```
```

--------------------------------

### Building a Complex Struct Step-by-Step with Do Notation

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-mastery.md

Complete example showing how to use do-notation with struct embedding and curried setters to build a configuration struct step by step. Includes imports, state definitions, setters, effectful lookups, and the final composition using F.Pipe4.

```go
import (
    F "github.com/IBM/fp-go/v2/function"
    R "github.com/IBM/fp-go/v2/result"
)

// Define states by embedding. Each step adds a field.
type Initial struct{}

type WithHost struct {
    Initial
    Host string
}

type WithPort struct {
    WithHost
    Port int
}

type WithDB struct {
    WithPort
    DBConn string
}

// Curried setters: func(T) func(S1) S2
var SetHost = F.Curry2(func(host string, s Initial) WithHost {
    return WithHost{Initial: s, Host: host}
})

var SetPort = F.Curry2(func(port int, s WithHost) WithPort {
    return WithPort{WithHost: s, Port: port}
})

var SetDB = F.Curry2(func(db string, s WithPort) WithDB {
    return WithPort{WithPort: s, DBConn: db}
})

// Effectful lookups
func lookupHost() R.Result[string]          { return R.Of("localhost") }
func lookupPort(host string) R.Result[int]  { return R.Of(8080) }
func connectDB(host string, port int) R.Result[string] {
    return R.Of(fmt.Sprintf("%s:%d", host, port))
}

// Compose with do-notation
config := F.Pipe4(
    R.Do(Initial{}),
    R.Bind(SetHost, func(_ Initial) R.Result[string] {
        return lookupHost()
    }),
    R.Bind(SetPort, func(s WithHost) R.Result[int] {
        return lookupPort(s.Host)
    }),
    R.Bind(SetDB, func(s WithPort) R.Result[string] {
        return connectDB(s.Host, s.Port)
    }),
)
// config: Result[WithDB] with all fields populated
```

--------------------------------

### Ord example: personByAge

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Creates an Ord for Person by contramapping age to an int Ord. Uses ord.ContraMap and ord.FromStrictCompare.

```go
type Person struct { Name string; Age int }
personByAge := ord.ContraMap(func(p Person) int { return p.Age })(ord.FromStrictCompare[int]())
```

--------------------------------

### Flow usage example

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

Point-free composition using Flow3. Creates a composed function that can be reused with different inputs.

```go
transform := F.Flow3(
    firstTransform,     // T0 -> T1
    secondTransform,    // T1 -> T2
    thirdTransform,     // T2 -> T3
)
result := transform(someValue)
```

--------------------------------

### Ask

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Returns the current environment as an effect.

```APIDOC
## Ask

### Description
Returns the current environment as an effect.

### Signature
```go
func Ask[C any]() Effect[C, C]
```
```

--------------------------------

### func Get[S any]() State[S, S]

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-full-reference.md

Returns a State computation that retrieves the current state.

```APIDOC
## func Get[S any]() State[S, S]

### Description
Returns a State computation that retrieves the current state.

### Signature
```go
func Get[S any]() State[S, S]
```
```

--------------------------------

### Quick example using either and function packages

Source: https://github.com/ibm/fp-go/blob/main/README.md

Shows a pure function that can fail, returning an either.Either, and composing operations safely with function.Pipe2. The result is 10.

```go
import (
    "errors"
    "github.com/IBM/fp-go/either"
    "github.com/IBM/fp-go/function"
)

// Pure function that can fail
func divide(a, b int) either.Either[error, int] {
    if b == 0 {
        return either.Left[int](errors.New("division by zero"))
    }
    return either.Right[error](a / b)
}

// Compose operations safely
result := function.Pipe2(
    divide(10, 2),
    either.Map(func(x int) int { return x * 2 }),
    either.GetOrElse(func() int { return 0 }),
)
// result = 10
```

--------------------------------

### Iso

Source: https://github.com/ibm/fp-go/blob/main/v2/docs/fp-go-guide/fp-go-core-patterns.md

An Iso is a lossless bidirectional transformation between types. It provides get and reverseGet functions and supports composition and modification.

```APIDOC
## Iso

### Description
An Iso is a lossless bidirectional transformation between types. It provides get and reverseGet functions and supports composition and modification.

### Type Definition
```go
type Iso[S, A any] struct {
    Get        func(S) A
    ReverseGet func(A) S
}
```

### Construction and Operations
```go
func MakeIso[S, A any](get func(S) A, reverse func(A) S) Iso[S, A]
func Id[S any]() Iso[S, S]
func Compose[S, A, B any](ab Iso[A, B]) func(Iso[S, A]) Iso[S, B]
func Reverse[S, A any](sa Iso[S, A]) Iso[A, S]
func Modify[S any, FCT ~func(A) A, A any](f FCT) func(Iso[S, A]) Endomorphism[S]
func Unwrap[A, S any](s S) func(Iso[S, A]) A               // alias: To
func Wrap[S, A any](a A) func(Iso[S, A]) S                 // alias: From
func IMap[S, A, B any](ab func(A) B, ba func(B) A) func(Iso[S, A]) Iso[S, B]
```

### Example
```go
import "github.com/IBM/fp-go/v2/optics/iso"

celsiusToFahrenheit := iso.MakeIso(
    func(c float64) float64 { return c*9/5 + 32 },
    func(f float64) float64 { return (f - 32) * 5 / 9 },
)
f := celsiusToFahrenheit.Get(100.0)        // 212.0
c := celsiusToFahrenheit.ReverseGet(212.0) // 100.0
```
```
Tokens:
Raw