fp-go Functional Programming for Go

fp-go v2 — Functional Programming for Go

Critical Rules for Code Generation

1. Import path is v2: always github.com/IBM/fp-go/v2/..., never github.com/IBM/fp-go/... (that is v1).
2. Data-last: all operations return a function waiting for data. Write option.Map(f)(value), never option.Map(value, f).
3. Non-inferrable type parameters come first. Whatever the compiler cannot recover from the arguments is declared first, so you can annotate just that prefix. Concretely:
   • Map[A, B](f func(A) B) and Chain[A, B](f Kleisli[A, B]) — both params are inferable from f; write option.Map(f) with no annotation.
   • Ap[B, A](fa M[A]) — B is not recoverable from fa, so it leads: option.Ap[int](fa).
   • In either/reader/readerio*, the error or environment type leads: either.Map[E, A, B], reader.Map[R, A, B]. Annotate only that head: either.Map[error](f), reader.Map[context.Context](f).
   • Result, Option, IOResult and the other error-specialized monads have no leading param, which is one more reason to prefer them.
4. Prefer Result over Either when the error type is Go's error. Result[A] is Either[error, A]. Same for ioresult over ioeither, readerioresult over readerioeither.
5. IO values are lazy: IO[A] is func() A. They describe a computation — you must call () to execute. Don't forget the trailing (). Running an IOResult[A] or ReaderIOResult[A] produces one value, a Result[A] — not a (A, error) pair. Use result.Unwrap to reach idiomatic Go:

   res := pipeline(ctx)()             // Result[A] — a single value
   value, err := result.Unwrap(res)   // (A, error)

   value, err := pipeline(ctx)() is a compile error. Alternatively, stay functional and eliminate the Result with result.Fold, or use one of the idiomatic/ packages, whose types are (A, error) tuples end to end.
6. Point-free style: compose with F.Flow and F.Pipe instead of writing inline anonymous functions. If a transformation can be expressed as a composition of named functions, it should be. Point-free pipelines are idiomatic fp-go.
   • Lambdas belong only at the leaves: a struct field accessor (or better, lens.Get), a lens setter passed to MakeLens, a multi-field formatter, or the one function that touches raw IO / ctx.Done(). Everything composed on top of the leaves — every Map, Chain, Bind, Filter, Fold argument — is a named function, a combinator (N.MoreThan, S.Format, F.Constant1, F.Bind2nd, …) or an F.FlowN of those.
   • Prefer lifting over wrapping: R.Eitherize1(strconv.Atoi), RIO.Eitherize1(repo.FindUser), EF.Eitherize1(queryUser) instead of hand-written closures.
   • An argument that is only used to feed a pipeline is a sign the function should return the pipeline instead: func fetchAll() RIO.Kleisli[[]int, []User] { return RIO.TraverseArray(fetchUser) }, not func fetchAll(ids []int) … { return RIO.TraverseArray(fetchUser)(ids) }.
7. Canonical import aliases: use the aliases in the table below in every file, so the same letter never means two packages.

Canonical Import Aliases

All fp-go skills use these aliases. Packages not listed are imported unaliased (prism, logging, readerresult, …), and so is the standard library (net/http stays http).

Generation Workflow

Two habits that matter more for fp-go than for idiomatic Go, because the library is low-frequency in training data and easy to misremember:

1. Retrieve before generating. For any pattern not fully covered below — optics beyond simple lenses, traversals, concurrent combinators, the less-common monads — query the fp-go MCP server's search_examples / get_example tools (see the fp-go-mcp skill) for a real signature instead of recalling names like Chain / FlatMap / Bind from memory. Retrieve-then-generate beats generate-then-fix here.
2. Compile before presenting. After writing fp-go code, run go build ./... and go vet ./..., then fix any import, type-parameter, or argument-order error and re-run until clean. The compiler is precise, low-ambiguity feedback, and most fp-go mistakes (wrong leading type param, data-first vs data-last) surface immediately.

Overview

fp-go (import path github.com/IBM/fp-go/v2) brings type-safe functional programming to Go using generics. Every monad follows a consistent interface: once you know the pattern in one monad, it transfers to all others.

All functions use the data-last principle: the data being transformed is always the last argument, enabling partial application and pipeline composition.

Core Types

Idiomatic Packages (High-Performance, Tuple-Based)

The idiomatic/ packages use Go-native tuples instead of struct wrappers, offering 2–10× better performance and zero allocations. Use them in hot paths; use standard packages when you need the richer API surface.

• idiomatic/option — (A, bool) tuples
• idiomatic/result — (A, error) tuples
• idiomatic/ioresult — func() (A, error)
• idiomatic/readerresult — func(R) (A, error)
• idiomatic/readerioresult — func(R) func() (A, error)
• idiomatic/context/readerresult — func(context.Context) (A, error)

Because idiomatic operators have the shape func(A, bool) (B, bool) / func(A, error) (B, error) — two arguments — F.Pipe cannot start them. Compose with F.FlowN and spread the multi-return into the call: v, ok := F.Flow2(Map(f), Filter(p))(Do(seed)). Never mix an idiomatic and a standard package for the same monad in one file; they are different types.

Standard Operations

Every monad exports these operations (PascalCase for exported Go names):

Curried (composable) vs. monadic (direct) form:

// Curried — data last, returns a transformer function
option.Map(strings.ToUpper)              // func(Option[string]) Option[string]

// Monadic — data first, immediate execution
option.MonadMap(option.Some("hello"), strings.ToUpper)

Use curried form for pipelines; use Monad* form when you already have all arguments.

Key Type Aliases (Defined Per Monad)

// A Kleisli arrow: a function from A to a monadic B
type Kleisli[A, B any] = func(A) M[B]

// An operator: transforms one monadic value into another
type Operator[A, B any] = func(M[A]) M[B]

Chain takes a Kleisli, Map returns an Operator. The naming is consistent across all monads.

Function Composition with Flow and Pipe (Point-Free Style)

fp-go is designed for point-free programming: compose named functions with Flow and Pipe rather than writing inline anonymous functions. This makes pipelines more readable and eliminates intermediate variable naming.

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

// ✅ GOOD: point-free — compose named functions, no lambda noise
pipeline := F.Flow3(
    R.Eitherize1(strconv.Atoi),
    R.Map(N.Mul(2)),
    R.GetOrElse(F.Constant1[error](0)), // Result's GetOrElse takes func(error) A
)

// ❌ AVOID: wrapping in unnecessary anonymous functions
pipeline := F.Flow3(
    func(s string) R.Result[int] { return R.Eitherize1(strconv.Atoi)(s) },
    func(r R.Result[int]) R.Result[int] { return R.Map(func(n int) int { return n * 2 })(r) },
    func(r R.Result[int]) int { return R.GetOrElse(func(error) int { return 0 })(r) },
)

Watch the GetOrElse shape: option.GetOrElse takes func() A (use LZ.Of(v)), while result.GetOrElse / either.GetOrElse take func(error) A / func(E) A (use F.Constant1[error](v)).

The data-last design means every fp-go operation already returns a function — so you almost never need to wrap them in a lambda. When you do need to adapt arguments, use F.Flow2 to compose:

// Point-free: compose a lens getter with a Kleisli arrow
RIO.Bind(configLens.Set, F.Flow2(userLens.Get, fetchConfigForUser))

// Instead of:
RIO.Bind(configLens.Set, func(s Pipeline) RIO.ReaderIOResult[Config] {
    return fetchConfigForUser(userLens.Get(s))
})

Two forms:

// Flow: compose functions left-to-right, returns a new function
transform := F.Flow3(
    O.Map(strings.TrimSpace),
    O.Filter(S.IsNonEmpty),
    O.GetOrElse(LZ.Of("default")),
)
value := transform(O.Some("  hello  ")) // "hello"

// Pipe: apply a value through a pipeline immediately
value := F.Pipe3(
    O.Some("  hello  "),
    O.Map(strings.TrimSpace),
    O.Filter(S.IsNonEmpty),
    O.GetOrElse(LZ.Of("default")),
)

Pipe1–Pipe20 and Flow1–Flow20 are available (the number = number of transformation steps).

Lifting Go Functions Into Monadic Context

Examples

Option — Nullable Values Without Nil

import (
    O  "github.com/IBM/fp-go/v2/option"
    F  "github.com/IBM/fp-go/v2/function"
    N  "github.com/IBM/fp-go/v2/number"
    S  "github.com/IBM/fp-go/v2/string"
    "github.com/IBM/fp-go/v2/optics/prism"
)

parseAndDouble := F.Flow3(
    O.FromPredicate(S.IsNonEmpty),
    O.Chain(prism.ParseInt().GetOption),
    O.Map(N.Mul(2)),
)

parseAndDouble("21")  // Some(42)
parseAndDouble("")    // None
parseAndDouble("abc") // None

Result — Error Handling Without If-Err Boilerplate

import (
    R  "github.com/IBM/fp-go/v2/result"
    F  "github.com/IBM/fp-go/v2/function"
    N  "github.com/IBM/fp-go/v2/number"
    P  "github.com/IBM/fp-go/v2/predicate"
    ER "github.com/IBM/fp-go/v2/errors"
    "strconv"
)

parse := R.Eitherize1(strconv.Atoi)  // lifts (int, error) → Result[int]

validate := R.FromPredicate(
    P.Not(N.LessThan(0)),
    ER.OnSome[int]("%d must not be negative"),
)

pipeline := F.Flow2(parse, R.Chain(validate))

pipeline("42")   // Ok(42)
pipeline("-1")   // Error("-1 must not be negative")
pipeline("abc")  // Error(strconv parse error)

IOResult — Lazy IO with Error Handling

import (
    IOR "github.com/IBM/fp-go/v2/ioresult"
    F   "github.com/IBM/fp-go/v2/function"
    J   "github.com/IBM/fp-go/v2/json"
    R   "github.com/IBM/fp-go/v2/result"
    "os"
)

readConfig := F.Flow2(
    IOR.Eitherize1(os.ReadFile),           // func(string) IOResult[[]byte]
    IOR.ChainEitherK(J.Unmarshal[Config]), // parse JSON, propagate errors
)

res := readConfig("config.json")()       // Result[Config] — note the trailing ()
cfg, err := R.Unwrap(res)                // bridge back to idiomatic Go

ReaderIOResult — Context-Aware Pipelines (Recommended for Services)

import (
    RIO "github.com/IBM/fp-go/v2/context/readerioresult"
    F   "github.com/IBM/fp-go/v2/function"
    IO  "github.com/IBM/fp-go/v2/io"
    R   "github.com/IBM/fp-go/v2/result"
)

// type ReaderIOResult[A any] = func(context.Context) func() Result[A]

// Lift the context-first Go function instead of hand-writing the nested closures:
// repo.FindUser is func(context.Context, int) (User, error)
fetchUser := RIO.Eitherize1(repo.FindUser)             // func(int) ReaderIOResult[User]

// validateUser is a plain Go func(User) (User, error) — Eitherize it first
pipeline := F.Pipe3(
    fetchUser(42),
    RIO.ChainResultK(R.Eitherize1(validateUser)),      // Kleisli: User → Result[User]
    RIO.Map(enrichUser),                               // lift pure User → User function
    RIO.TapIOK(IO.Logf[User]("Fetched: %v")),   // side-effect logging
)

res := pipeline(ctx)()               // Result[User] — ONE value, not (User, error)
user, err := R.Unwrap(res)           // bridge back to idiomatic Go

Reading and scoping the context

The context is the Reader environment: never thread ctx by hand, call ctx.Value(k).(T), or write ctx, cancel := context.WithTimeout(...); defer cancel() inside a pipeline. Use the operators — same names in context/readerio, context/readerresult, context/readerioresult, context/statereaderioresult (extra leading S type parameter) and idiomatic/context/readerresult:

type ctxKey string                         // unexported key type, never plain strings
const userKey ctxKey = "user"

requireUser := F.Pipe1(                    // required: None → error
    RIO.AskValue[string](userKey),
    RIO.Chain(RIO.FromOption[string](F.Constant(errNoUser))),
)
userOrAnon := F.Pipe1(                     // optional: None → default
    RIO.AskValue[string](userKey),
    RIO.Map(O.GetOrElse(LZ.Of("anonymous"))),
)

handler := F.Pipe3(                        // scoping composes like any operator
    processRequest(),
    RIO.WithTimeout[Response](5*time.Second),
    RIO.WithValue[Response](userKey, user),
    RIO.Local[Response](logging.WithLogger(reqLogger)), // WithLogger already has Local's shape
)

Outside a pipeline (building a context in main or a test) use context/reader (CR): CR.AskValue[V](k)(ctx), CR.WithValue[V](k)(v)(ctx), CR.NopCancel(ctx). Keep only request-scoped data (IDs, principal, logger) in the context; real dependencies belong in Effect. For the full guide (key accessors, cancellation semantics, Effect scoping, testing) use the fp-go-context skill.

Effect — Typed Dependency Injection (Recommended for Testable Services)

Effect[C, A] adds a typed dependency parameter C on top of ReaderIOResult. While context/readerioresult hardcodes context.Context as the environment, Effect lets you define a custom dependencies struct — making dependencies explicit, compile-time checked, and trivially mockable in tests.

Effect[C, A] is literally func(C) ReaderIOResult[A] (an alias for context/readerreaderioresult.ReaderReaderIOResult[C, A]). A function of that exact shape is already an Effect — do not wrap it in Asks. EF.Asks(f) is for a pure projection func(C) A and returns Effect[C, A]; passing it a func(C) ReaderIOResult[A] silently yields the nested Effect[C, ReaderIOResult[A]].

Use Effect when your service has dependencies beyond context.Context (database connections, HTTP clients, config, loggers). It is the recommended top-level monad for production service code. The type parameter C is meant for these dependencies; request-scoped data (IDs, principal, deadlines) stays in context.Context. For designing dependency types (capability interfaces, Local, dependencies built by an effect, testing with fakes) use the fp-go-effect skill.

import (
    EF "github.com/IBM/fp-go/v2/effect"
    F  "github.com/IBM/fp-go/v2/function"
    L  "github.com/IBM/fp-go/v2/optics/lens"
)

// 1. Define your dependencies as a struct
type Deps struct {
    DB     DBClient
    Logger Logger
    Config AppConfig
}

// Leaf accessors (or generated lenses' .Get)
func getConfig(d Deps) AppConfig          { return d.Config }
func getDisplayName(u EnrichedUser) string { return u.DisplayName }

// 2. Write effects that declare exactly what they need.
// Lift an idiomatic function that takes deps and ctx — no hand-written closure:
// queryUser is func(Deps, context.Context, int) (User, error)
fetchUser := EF.Eitherize1(queryUser)      // func(int) Effect[Deps, User]

// Asks is for PURE projections of the deps: func(Deps) A → Effect[Deps, A].
// applyConfig is curried: func(User) func(AppConfig) EnrichedUser
enrichWithConfig := func(user User) EF.Effect[Deps, EnrichedUser] {
    return EF.Asks(F.Flow2(getConfig, applyConfig(user)))
}

// 3. Compose effects — same Map/Chain/Bind/ApS API as every other monad.
// C leads the type-parameter list and is not always inferable: annotate EF.Map[Deps].
pipeline := F.Pipe2(
    fetchUser(42),
    EF.Chain(enrichWithConfig),
    EF.Map[Deps](getDisplayName),
)

// 4. Provide dependencies once at the edge, then run.
// Provide[A, C]: A cannot be inferred through the returned function — annotate it.
thunk := EF.Provide[string](Deps{
    DB:     realDB,
    Logger: zapLogger,
    Config: loadedConfig,
})(pipeline) // ReaderIOResult[string]

value, err := EF.RunSync(thunk)(ctx) // RunSync gives back idiomatic (A, error)
// or: result := thunk(ctx)()        // Result[string]

Why Effect over ReaderIOResult: dependencies are typed (compiler catches missing deps), each function's signature declares what it needs (Effect[Deps, A]), testability is trivial (swap Deps{DB: mockDB}), and EF.Local/EF.Provide narrow or eliminate deps for subsystems.

Lifting into Effect (all take C as a leading, usually explicit, type parameter):

Running: EF.Provide[A](deps) → ReaderIOResult[A], then EF.RunSync(thunk)(ctx) → (A, error). EF.Local(f) narrows an outer dep struct to an inner one for a subsystem.