Skip to main content
Version: v2.2.82 (latest)
Reference

API Reference

Complete API reference for fp-go v2 covering core types, collections, function utilities, and advanced patterns.

01

Core Types

The fundamental building blocks for functional programming in Go.

Essential Types​

SymbolDescription
OptionRepresent optional values without null pointers
ResultType-safe error handling with Ok/Err variants
EitherRepresent a value of one of two possible types (Left/Right)
IOLazy side effects that execute when called
IOResultCombine IO with Result for effectful error handling
IOEitherCombine IO with Either for lazy error handling
IOOptionCombine IO with Option for optional effects

Reader Types​

Dependency injection and environment management:

SymbolDescription
ReaderComputations that depend on a shared environment
ReaderEitherReader with Either for error handling
ReaderIOReader with IO for side effects
ReaderIOEitherReader with IO and Either (most powerful combination)
ReaderIOResultReader with IO and Result
ReaderOptionReader with Option for optional dependencies

State & Advanced Types​

Stateful computations and advanced patterns:

SymbolDescription
StateStateful computations with get/put operations
StateReaderIOEitherState with Reader, IO, and Either (ultimate monad stack)
LazyLazy evaluation with memoization
IdentitySimplest monad wrapper
ConstantConstant functor
EndomorphismFunctions from type to itself
core_example.go
package main

import (
  "fmt"
  O "github.com/IBM/fp-go/option"
  E "github.com/IBM/fp-go/either"
  R "github.com/IBM/fp-go/result"
)

func main() {
  // Option for optional values
  opt := O.Some(42)
  fmt.Println(O.IsSome(opt)) // true
  
  // Either for errors
  either := E.Right[error](42)
  fmt.Println(E.IsRight(either)) // true
  
  // Result for Ok/Err
  result := R.Ok[error](42)
  fmt.Println(R.IsOk(result)) // true
}
02

Collections & Arrays

Functional operations on slices and maps.

Array Operations​

SymbolDescription
ArrayCore array operations (Map, Filter, Reduce)
Array.ApApplicative operations for arrays
Array.EqEquality checking for arrays
Array.FindSearch and lookup operations
Array.MonoidMonoid instance for arrays
Array.SortSorting with custom comparators
Array.UniqRemove duplicates
Array.ZipCombine multiple arrays
NonEmptyArrayArrays guaranteed to have at least one element

Record Operations​

SymbolDescription
RecordCore map operations (Map, Filter, Keys, Values)
Record.ApApplicative operations for records
Record.ChainMonadic chaining for records
Record.ConversionConvert between records and arrays
Record.EqEquality checking for records
Record.MonoidMonoid instance for records
Record.OrdOrdering for records
Record.TraverseTraverse records with effects
Sequence.TraverseGeneric sequence traversal
collections_example.go
package main

import (
  "fmt"
  A "github.com/IBM/fp-go/array"
  R "github.com/IBM/fp-go/record"
)

func main() {
  // Array operations
  numbers := []int{1, 2, 3, 4, 5}
  doubled := A.Map(func(n int) int { return n * 2 })(numbers)
  fmt.Println(doubled) // [2 4 6 8 10]
  
  // Record operations
  ages := map[string]int{"Alice": 30, "Bob": 25}
  names := R.Keys(ages)
  fmt.Println(names) // [Alice Bob]
}
03

Function Utilities

Core function manipulation and composition utilities.

Composition & Flow​

SymbolDescription
Pipe & FlowLeft-to-right function composition
ComposeRight-to-left function composition
FunctionCore function utilities (Identity, Constant, Flip)

Currying & Binding​

SymbolDescription
Bind & CurryCurrying and partial application

Type Classes​

SymbolDescription
EqEquality type class
OrdOrdering type class
SemigroupAssociative binary operation
MonoidSemigroup with identity element
MagmaBinary operation without laws

Primitive Utilities​

SymbolDescription
BooleanBoolean operations and combinators
NumberNumeric operations and instances
StringString operations and instances
PredicatePredicate combinators (And, Or, Not)
TupleTuple operations and utilities
utilities_example.go
package main

import (
  "fmt"
  F "github.com/IBM/fp-go/function"
)

func main() {
  // Pipe: left-to-right composition
  add10 := func(n int) int { return n + 10 }
  double := func(n int) int { return n * 2 }
  
  result := F.Pipe2(
      5,
      add10,   // 5 + 10 = 15
      double,  // 15 * 2 = 30
  )
  fmt.Println(result) // 30
}
04

Type Hierarchy

Understanding the relationships between types:

hierarchy.txt
Functor
├─ Applicative
│   └─ Monad
│       ├─ Option
│       ├─ Either
│       ├─ Result
│       ├─ IO
│       ├─ IOEither
│       ├─ IOResult
│       ├─ IOOption
│       ├─ Reader
│       ├─ ReaderEither
│       ├─ ReaderIO
│       ├─ ReaderIOEither
│       ├─ ReaderIOResult
│       ├─ ReaderOption
│       ├─ State
│       └─ StateReaderIOEither
└─ Array

Key Concepts:

  • Functor - Types that can be mapped over (Map)
  • Applicative - Functors with Of (pure) and Ap (apply)
  • Monad - Applicatives with Chain (flatMap/bind)
  • Array - Functor but not a monad (multiple values)
05

Common Patterns

Frequently used patterns and idioms.

Error Handling​

Before
traditional.go
// ❌ Traditional Go error handling
func getUser(id string) (*User, error) {
  user, err := db.FindUser(id)
  if err != nil {
      return nil, err
  }
  return user, nil
}
After
functional.go
// ✅ Functional error handling
func getUser(id string) either.Either[error, User] {
  return db.FindUser(id)
}

// Chain operations
result := pipe.Pipe2(
  getUser("123"),
  E.Chain(validateUser),
  E.Map(enrichUser),
)

Side Effects​

effects.go
// IO for lazy effects
io := IO.Of(func() int {
  fmt.Println("Computing...")
  return 42
})

// Execute when ready
result := io() // Prints "Computing..." and returns 42

// IOEither for effects with errors
ioe := IOE.TryCatch(func() (int, error) {
  return readFile("config.json")
})

Dependency Injection​

reader.go
type Config struct {
  DBUrl string
  Port  int
}

// Reader for dependencies
getDBUrl := R.Asks(func(c Config) string {
  return c.DBUrl
})

// ReaderIOEither for full power
program := RIOE.Chain(
  getDBUrl,
  func(url string) RIOE.ReaderIOEither[Config, error, *DB] {
      return RIOE.FromIO(connectDB(url))
  },
)

// Run with config
config := Config{DBUrl: "localhost:5432", Port: 8080}
result := program(config)()
06

Quick Links

Getting Started​

Learning Resources​

Advanced Topics​

Legacy Version​