README
¶
For why fluentfp exists and when to use it, see the main README.
either: sum types for Go
An Either represents a value that is one of two possible types: Left or Right. By convention, Left represents failure or an alternative path, while Right represents success or the primary path. The mnemonic is "Right is right" (correct).
Creating Either Values
The Either type is either.Either[L, R any], where L is the Left type and R is the
Right type.
Create a Left value:
left := either.Left[string, int]("error message")
Create a Right value:
right := either.Right[string, int](42)
Using the Either
Checking Which Side
Test which variant you have:
if e.IsRight() {
// handle success
}
if e.IsLeft() {
// handle failure/alternative
}
Extracting Values
Use the comma-ok idiom to safely extract values:
// Get the Right value
if value, ok := e.Get(); ok {
// use value
}
// Get the Left value
if err, ok := e.GetLeft(); ok {
// handle error
}
Get with a default fallback:
value := e.GetOrElse(defaultValue) // returns Right or default
leftVal := e.LeftOrElse(defaultLeft) // returns Left or default
Transforming
Map applies a function to the Right value (right-biased):
doubled := right.Map(func(x int) int { return x * 2 })
// Left values pass through unchanged
Fold handles both cases exhaustively (pattern matching):
result := either.Fold(e,
func(err string) string { return "Error: " + err },
func(val int) string { return fmt.Sprintf("Value: %d", val) },
)
Note: Fold is a function, not a method, due to Go's generics limitations (methods
cannot introduce new type parameters).
Either vs Option
| Type | Use Case | Example |
|---|---|---|
option.Basic[T] |
Value may be absent | Database nullable field |
either.Either[L, R] |
One of two distinct states | Success with value OR failure with reason |
Option is for "maybe nothing." Either is for "definitely something, but which one?"
Patterns
Parse, Don't Validate
Return structured failure information instead of just bool or error:
type ParseError struct {
Line int
Reason string
}
func ParseConfig(input string) either.Either[ParseError, Config]
// Caller gets actionable failure context
result := ParseConfig(raw)
if cfg, ok := result.Get(); ok {
return cfg
}
if err, ok := result.GetLeft(); ok {
log.Printf("Parse failed at line %d: %s", err.Line, err.Reason)
}
Exhaustive Handling
Fold forces handling both cases at compile time—no forgotten error paths:
response := either.Fold(result,
func(err ParseError) Response { return ErrorResponse(err) },
func(cfg Config) Response { return SuccessResponse(cfg) },
)
Two-State Structs
Replace pairs of nullable fields with explicit Either:
// Before: which field is set? nil checks scattered everywhere
type Handler struct {
syncFn *func()
asyncFn *func() <-chan Result
}
// After: exactly one mode, exhaustively handled
type Handler struct {
mode either.Either[func(), func() <-chan Result]
}
Documentation
¶
Overview ¶
Package either provides a sum type representing a value of one of two types.
Convention: Left represents failure/error, Right represents success. Mnemonic: "Right is right" (correct).
Either is right-biased: Map, MustGet, Call, GetOrElse operate on the Right value. Use MapLeft, MustGetLeft, CallLeft, LeftOrElse for Left-side operations.
Index ¶
- func Fold[L, R, T any](e Either[L, R], onLeft func(L) T, onRight func(R) T) T
- type Either
- func (e Either[L, R]) Call(fn func(R))
- func (e Either[L, R]) CallLeft(fn func(L))
- func (e Either[L, R]) Get() (_ R, _ bool)
- func (e Either[L, R]) GetLeft() (_ L, _ bool)
- func (e Either[L, R]) GetOrCall(fn func() R) R
- func (e Either[L, R]) GetOrElse(defaultVal R) R
- func (e Either[L, R]) IsLeft() bool
- func (e Either[L, R]) IsRight() bool
- func (e Either[L, R]) LeftOrCall(fn func() L) L
- func (e Either[L, R]) LeftOrElse(defaultVal L) L
- func (e Either[L, R]) Map(fn func(R) R) Either[L, R]
- func (e Either[L, R]) MustGet() R
- func (e Either[L, R]) MustGetLeft() L
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Either ¶
type Either[L, R any] struct { // contains filtered or unexported fields }
Either represents a value of one of two types. Convention: Left for failure, Right for success.
func Map ¶ added in v0.8.1
Map applies fn to the Right value and returns a new Either with a different Right type. If e is Left, returns the Left value unchanged.
func MapLeft ¶ added in v0.8.1
MapLeft applies fn to the Left value and returns a new Either with a different Left type. If e is Right, returns the Right value unchanged.
func (Either[L, R]) Call ¶ added in v0.8.1
func (e Either[L, R]) Call(fn func(R))
Call applies fn to the Right value if e is Right. If e is Left, does nothing.
func (Either[L, R]) CallLeft ¶ added in v0.8.1
func (e Either[L, R]) CallLeft(fn func(L))
CallLeft applies fn to the Left value if e is Left. If e is Right, does nothing.
func (Either[L, R]) GetOrCall ¶ added in v0.8.1
func (e Either[L, R]) GetOrCall(fn func() R) R
GetOrCall returns the Right value, or the result of calling fn if e is Left.
func (Either[L, R]) GetOrElse ¶
func (e Either[L, R]) GetOrElse(defaultVal R) R
GetOrElse returns the Right value, or defaultVal if Left.
func (Either[L, R]) LeftOrCall ¶ added in v0.8.1
func (e Either[L, R]) LeftOrCall(fn func() L) L
LeftOrCall returns the Left value, or the result of calling fn if e is Right.
func (Either[L, R]) LeftOrElse ¶
func (e Either[L, R]) LeftOrElse(defaultVal L) L
LeftOrElse returns the Left value, or defaultVal if Right.
func (Either[L, R]) Map ¶
Map applies fn to the Right value and returns a new Either. If e is Left, returns e unchanged.
func (Either[L, R]) MustGet ¶ added in v0.8.1
func (e Either[L, R]) MustGet() R
MustGet returns the Right value or panics if e is Left.
func (Either[L, R]) MustGetLeft ¶ added in v0.8.1
func (e Either[L, R]) MustGetLeft() L
MustGetLeft returns the Left value or panics if e is Right.
Source Files