Golang Samber Mo

Persona: You are a Go engineer bringing functional programming safety to Go. You use monads to make impossible states unrepresentable — nil checks become type constraints, error handling becomes composable pipelines.

Thinking mode: Use ultrathink when designing multi-step Option/Result/Either pipelines. Wrong type choice creates unnecessary wrapping/unwrapping that defeats the purpose of monads.

samber/mo — Monads and Functional Abstractions for Go

Go 1.18+ library providing type-safe monadic types with zero dependencies. Inspired by Scala, Rust, and fp-ts.

Official Resources:

• pkg.go.dev/github.com/samber/mo
• github.com/samber/mo

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.

go get github.com/samber/mo

For an introduction to functional programming concepts and why monads are valuable in Go, see Monads Guide.

Core Types at a Glance

Option[T] — Nullable Values Without nil

Represents a value that is either present (Some) or absent (None). Eliminates nil pointer risks at the type level.

import "github.com/samber/mo"

name := mo.Some("Alice")          // Option[string] with value
empty := mo.None[string]()        // Option[string] without value
fromPtr := mo.PointerToOption(ptr) // nil pointer -> None

// Safe extraction
name.OrElse("Anonymous")  // "Alice"
empty.OrElse("Anonymous")  // "Anonymous"

// Transform if present, skip if absent
upper := name.Map(func(s string) (string, bool) {
    return strings.ToUpper(s), true
})

Key methods: Some, None, Get, MustGet, OrElse, OrEmpty, Map, FlatMap, Match, ForEach, ToPointer, IsPresent, IsAbsent.

Option implements json.Marshaler/Unmarshaler, sql.Scanner, driver.Valuer — use it directly in JSON structs and database models.

For full API reference, see Option Reference.

Result[T] — Error Handling as Values

Represents success (Ok) or failure (Err). Equivalent to Either[error, T] but specialized for Go's error pattern.

// Wrap Go's (value, error) pattern
result := mo.TupleToResult(os.ReadFile("config.yaml"))

// Same-type transform — errors short-circuit automatically
upper := mo.Ok("hello").Map(func(s string) (string, error) {
    return strings.ToUpper(s), nil
})
// Ok("HELLO")

// Extract with fallback
val := upper.OrElse("default")

Go limitation: Direct methods (.Map, .FlatMap) cannot change the type parameter — Result[T].Map returns Result[T], not Result[U]. Go methods cannot introduce new type parameters. For type-changing transforms (e.g. Result[[]byte] to Result[Config]), use sub-package functions or mo.Do:

import "github.com/samber/mo/result"

// Type-changing pipeline: []byte -> Config -> ValidConfig
parsed := result.Pipe2(
    mo.TupleToResult(os.ReadFile("config.yaml")),
    result.Map(func(data []byte) Config { return parseConfig(data) }),
    result.FlatMap(func(cfg Config) mo.Result[ValidConfig] { return validate(cfg) }),
)

Key methods: Ok, Err, Errf, TupleToResult, Try, Get, MustGet, OrElse, Map, FlatMap, MapErr, Match, ForEach, ToEither, IsOk, IsError.

For full API reference, see Result Reference.

Either[L, R] — Discriminated Union of Two Types

Represents a value that is one of two possible types. Unlike Result, neither side implies success or failure — both are valid alternatives.

// API that returns either cached data or fresh data
func fetchUser(id string) mo.Either[CachedUser, FreshUser] {
    if cached, ok := cache.Get(id); ok {
        return mo.Left[CachedUser, FreshUser](cached)
    }
    return mo.Right[CachedUser, FreshUser](db.Fetch(id))
}

// Pattern match
result := fetchUser("user-123")
result.Match(
    func(cached CachedUser) mo.Either[CachedUser, FreshUser] { /* use cached */ },
    func(fresh FreshUser) mo.Either[CachedUser, FreshUser] { /* use fresh */ },
)

When to use Either vs Result: Use Result[T] when one path is an error. Use Either[L, R] when both paths are valid alternatives (cached vs fresh, left vs right, strategy A vs B).

Either3[T1, T2, T3], Either4, and Either5 extend this to 3-5 type variants.

For full API reference, see Either Reference.

Do Notation — Imperative Style with Monadic Safety

mo.Do wraps imperative code in a Result, catching panics from MustGet() calls:

result := mo.Do(func() int {
    // MustGet panics on None/Err — Do catches it as Result error
    a := mo.Some(21).MustGet()
    b := mo.Ok(2).MustGet()
    return a * b  // 42
})
// result is Ok(42)

result := mo.Do(func() int {
    val := mo.None[int]().MustGet()  // panics
    return val
})
// result is Err("no such element")

Do notation bridges imperative Go style with monadic safety — write straight-line code, get automatic error propagation.

Pipeline Sub-Packages vs Direct Chaining

samber/mo provides two ways to compose operations:

Direct methods (.Map, .FlatMap) — work when the output type equals the input type:

opt := mo.Some(42)
doubled := opt.Map(func(v int) (int, bool) {
    return v * 2, true
})  // Option[int]

Sub-package functions (option.Map, result.Map) — required when the output type differs from input:

import "github.com/samber/mo/option"

// int -> string type change: use sub-package Map
strOpt := option.Map(func(v int) string {
    return fmt.Sprintf("value: %d", v)
})(mo.Some(42))  // Option[string]

Pipe functions (option.Pipe3, result.Pipe3) — chain multiple type-changing transformations readably:

import "github.com/samber/mo/option"

result := option.Pipe3(
    mo.Some(42),
    option.Map(func(v int) string { return strconv.Itoa(v) }),
    option.Map(func(s string) []byte { return []byte(s) }),
    option.FlatMap(func(b []byte) mo.Option[string] {
        if len(b) > 0 { return mo.Some(string(b)) }
        return mo.None[string]()
    }),
)

Rule of thumb: Use direct methods for same-type transforms. Use sub-package functions + pipes when types change across steps.

For detailed pipeline API reference, see Pipelines Reference.

Common Patterns

JSON API responses with Option

type UserResponse struct {
    Name     string            `json:"name"`
    Nickname mo.Option[string] `json:"nickname"`  // omits null gracefully
    Bio      mo.Option[string] `json:"bio"`
}

Database nullable columns

type User struct {
    ID       int
    Email    string
    Phone    mo.Option[string]  // implements sql.Scanner + driver.Valuer
}

err := row.Scan(&u.ID, &u.Email, &u.Phone)

Wrapping existing Go APIs

// Convert map lookup to Option
func MapGet[K comparable, V any](m map[K]V, key K) mo.Option[V] {
    return mo.TupleToOption(m[key])  // m[key] returns (V, bool)
}

Uniform extraction with Fold

mo.Fold works uniformly across Option, Result, and Either via the Foldable interface:

str := mo.Fold[error, int, string](
    mo.Ok(42),  // works with Option, Result, or Either
    func(v int) string { return fmt.Sprintf("got %d", v) },
    func(err error) string { return "failed" },
)
// "got 42"

Best Practices

1. Prefer `OrElse` over `MustGet` — MustGet panics on absent/error values; use it only inside mo.Do blocks where panics are caught, or when you are certain the value exists 2. Use `TupleToResult` at API boundaries — convert Go's (T, error) to Result[T] at the boundary, then chain with Map/FlatMap inside your domain logic 3. Use `Result[T]` for errors, `Either[L, R]` for alternatives — Result is specialized for success/failure; Either is for two valid types 4. Option for nullable fields, not zero values — Option[string] distinguishes "absent" from "empty string"; use plain string when empty string is a valid value 5. Chain, don't nest — result.Map(...).FlatMap(...).OrElse(default) reads left-to-right; avoid nested if/else patterns when monadic chaining is cleaner 6. Use sub-package pipes for multi-step type transformations — when 3+ steps each change the type, option.Pipe3(...) is more readable than nested function calls

For advanced types (Future, IO, Task, State), see Advanced Types Reference.

If you encounter a bug or unexpected behavior in samber/mo, open an issue at <https://github.com/samber/mo/issues>.

Cross-References

• -> See samber/cc-skills-golang@golang-samber-lo skill for functional collection transforms (Map, Filter, Reduce on slices) that compose with mo types
• -> See samber/cc-skills-golang@golang-error-handling skill for idiomatic Go error handling patterns
• -> See samber/cc-skills-golang@golang-safety skill for nil-safety and defensive Go coding
• -> See samber/cc-skills-golang@golang-database skill for database access patterns
• -> See samber/cc-skills-golang@golang-design-patterns skill for functional options and other Go patterns

Advanced Types Reference

These types are less commonly used than Option/Result/Either but provide powerful abstractions for specific scenarios.

Type Hierarchy

Synchronous                    Asynchronous
-----------                    ------------
IO[T]     (no error)    →     Task[T]     (no error)    → Future[T]
IOEither[T] (with error) →     TaskEither[T] (with error) → Future[T]

• IO wraps a synchronous side-effecting computation
• Task wraps an asynchronous side-effecting computation (returns a Future)
• Future represents a value that will be available later
• Either variants add error handling capability

Future[T] — Asynchronous Values

Represents a value that may not yet be available. Similar to JavaScript's Promise.

Constructor

future := mo.NewFuture(func(resolve func(int), reject func(error)) {
    // runs asynchronously
    result, err := expensiveComputation()
    if err != nil {
        reject(err)
    } else {
        resolve(result)
    }
})

Chaining

future.
    Then(func(v int) (int, error) {
        return v * 2, nil  // transform on success
    }).
    Catch(func(err error) (int, error) {
        return 0, err  // handle error
    }).
    Finally(func(v int, err error) (int, error) {
        // always runs, regardless of success/failure
        log.Println("Done")
        return v, err
    })

Collecting Results

value, err := future.Collect()    // blocks until resolved
result := future.Result()          // blocks, returns Result[T]
either := future.Either()          // blocks, returns Either[error, T]

Cancellation

future.Cancel()  // terminates the future chain

IO[T] — Synchronous Side Effects

Wraps a function that performs side effects. The computation is lazy — it only runs when Run() is called. IO never fails.

Variants by Parameter Count

// No parameters
io := mo.NewIO(func() string { return "hello" })
result := io.Run()  // "hello"

// 1 parameter
io1 := mo.NewIO1(func(name string) string { return "hello " + name })
result := io1.Run("Alice")  // "hello Alice"

// 2-5 parameters (IO2, IO3, IO4, IO5)
io2 := mo.NewIO2(func(a, b int) int { return a + b })
result := io2.Run(1, 2)  // 3

IOEither[T] — Synchronous Side Effects with Errors

Like IO but the computation can fail. The callback must return Either[error, R], not (R, error).

io := mo.NewIOEither(func() mo.Either[error, string] {
    data, err := os.ReadFile("config.yaml")
    if err != nil {
        return mo.Left[error, string](err)
    }
    return mo.Right[error, string](string(data))
})

either := io.Run()  // Either[error, string]

Variants by Parameter Count

// 1 parameter
io1 := mo.NewIOEither1(func(path string) mo.Either[error, string] {
    data, err := os.ReadFile(path)
    if err != nil {
        return mo.Left[error, string](err)
    }
    return mo.Right[error, string](string(data))
})
either := io1.Run("config.yaml")  // Either[error, string]

// IOEither2 through IOEither5 follow the same pattern

Task[T] — Asynchronous Computations

Lazy async computation — Run() calls the wrapped function, which returns a *Future[T]. Never fails.

task := mo.NewTask(func() *mo.Future[int] {
    return mo.NewFuture(func(resolve func(int), reject func(error)) {
        time.Sleep(time.Second)
        resolve(42)
    })
})

future := task.Run()           // executes the function, returns *Future[int]
value, err := future.Collect() // blocks until done

Note: NewTask accepts func() *Future[R] — it wraps a Future-producing function for lazy execution.

From IO

io := mo.NewIO(func() int { return 42 })
task := mo.NewTaskFromIO(io)  // wrap IO as async Task

Variants by Parameter Count

task1 := mo.NewTask1(func(n int) *mo.Future[int] {
    return mo.NewFuture(func(resolve func(int), reject func(error)) {
        resolve(n * 2)
    })
})
future := task1.Run(21)  // *Future[int] resolving to 42

TaskEither[T] — Async Computations with Errors

Like Task but the computation can fail. Combines Task semantics with error handling.

te := mo.NewTaskEither(func() *mo.Future[string] {
    return mo.NewFuture(func(resolve func(string), reject func(error)) {
        resp, err := http.Get("https://api.example.com/data")
        if err != nil {
            reject(err)
            return
        }
        defer resp.Body.Close()
        body, err := io.ReadAll(resp.Body)
        if err != nil {
            reject(err)
            return
        }
        resolve(string(body))
    })
})

Note: Like NewTask, NewTaskEither accepts func() *Future[R]. The difference is in the methods available on the returned type — TaskEither provides Match, OrElse, ToEither, and ToTask.

Methods

te.OrElse("fallback")                    // blocks, returns value or fallback
te.ToEither()                            // blocks, returns Either[error, T]
te.ToTask("fallback")                    // converts to Task (uses fallback on error)
te.Match(
    func(err error) mo.Either[error, string] { ... },  // on error
    func(v string) mo.Either[error, string] { ... },    // on success
)

State[S, A] — Stateful Computations

Represents a computation that threads state through a series of operations. The state type S flows through the computation while producing result values of type A.

Constructor

// State computation: takes state, returns (result, newState)
counter := mo.NewState(func(count int) (string, int) {
    return fmt.Sprintf("count=%d", count), count + 1
})

result, newState := counter.Run(0)  // ("count=0", 1)

ReturnState — wrap a value without modifying state

state := mo.ReturnState[int, string]("hello")
result, s := state.Run(42)  // ("hello", 42) — state unchanged

State Manipulation

// Get — return current state as result
getter := mo.NewState(func(s int) (int, int) { return s, s })

// Put — replace state
putter := state.Put(100)
_, s := putter.Run(0)  // (_, 100)

// Modify — transform state
modified := state.Modify(func(s int) int { return s * 2 })
_, s := modified.Run(5)  // (_, 10)

Chaining State Computations

State is useful for accumulating results while threading context:

// Parse tokens while tracking position
type ParseState struct {
    Input    string
    Position int
}

parseChar := mo.NewState(func(s ParseState) (byte, ParseState) {
    ch := s.Input[s.Position]
    return ch, ParseState{Input: s.Input, Position: s.Position + 1}
})

When to Use Advanced Types

Most Go projects only need Option, Result, and Either. The advanced types are valuable when building functional pipelines or when you want explicit control over when side effects execute.

Either[L, R] API Reference

A discriminated union representing a value of one of two possible types. By convention, Left is the "alternative" path and Right is the "primary" path, but neither implies success or failure.

Constructors

Type Checking

Value Extraction

Transformations

Swap — exchange left and right

e := mo.Left[string, int]("hello")
swapped := e.Swap()  // Either[int, string] — Right("hello")

MapLeft / MapRight — transform one side

The callback receives the value and must return a new Either[L, R]:

e := mo.Left[string, int]("hello")
upper := e.MapLeft(func(s string) mo.Either[string, int] {
    return mo.Left[string, int](strings.ToUpper(s))
})
// Left("HELLO")

e2 := mo.Right[string, int](42)
doubled := e2.MapRight(func(v int) mo.Either[string, int] {
    return mo.Right[string, int](v * 2)
})
// Right(84)

Go limitation: Like Option.Map and Result.Map, direct Either methods cannot change the type parameters. Use sub-package either.MapLeft/either.MapRight for type-changing transforms — see Pipelines Reference.

Match — pattern matching

e.Match(
    func(left string) mo.Either[string, int] {
        fmt.Println("Left:", left)
        return mo.Left[string, int](left)
    },
    func(right int) mo.Either[string, int] {
        fmt.Println("Right:", right)
        return mo.Right[string, int](right)
    },
)

ForEach — side effects

e.ForEach(
    func(left string) { fmt.Println("Left:", left) },
    func(right int) { fmt.Println("Right:", right) },
)

Either vs Result

Result[T] is equivalent to Either[error, T] — use result.ToEither() to convert.

Either3[T1, T2, T3] — Three-Type Union

Constructors

e := mo.NewEither3Arg1[string, int, bool]("hello")  // T1 variant
e := mo.NewEither3Arg2[string, int, bool](42)         // T2 variant
e := mo.NewEither3Arg3[string, int, bool](true)       // T3 variant

Type Checking and Extraction

e.IsArg1()  // true if T1
e.IsArg2()  // true if T2
e.IsArg3()  // true if T3

val, ok := e.Arg1()      // (T1, bool)
val := e.MustArg1()      // T1 or panics
val := e.Arg1OrElse(fb)  // T1 or fallback
val := e.Arg1OrEmpty()   // T1 or zero value
t1, t2, t3 := e.Unpack() // all three (two will be zero)

Pattern Matching

e.Match(
    func(s string) mo.Either3[string, int, bool] { ... },
    func(i int) mo.Either3[string, int, bool] { ... },
    func(b bool) mo.Either3[string, int, bool] { ... },
)

Transformations

MapArg callbacks receive the value and return a new Either3:

e.MapArg1(func(s string) mo.Either3[string, int, bool] {
    return mo.NewEither3Arg1[string, int, bool](strings.ToUpper(s))
})
e.MapArg2(func(i int) mo.Either3[string, int, bool] {
    return mo.NewEither3Arg2[string, int, bool](i * 2)
})

Either4 and Either5

Follow the exact same pattern as Either3 with 4 and 5 type parameters respectively:

• Either4[T1, T2, T3, T4]: NewEither4Arg1 through NewEither4Arg4, IsArg1-IsArg4, MapArg1-MapArg4
• Either5[T1, T2, T3, T4, T5]: NewEither5Arg1 through NewEither5Arg5, IsArg1-IsArg5, MapArg1-MapArg5

Use Either3+ when you need a type-safe union of multiple types — for example, an API that returns different response shapes depending on the request type.

Functional Programming and Monads in Go

What is Functional Programming?

Functional programming (FP) treats computation as evaluation of mathematical functions. Core principles:

• Immutability — data doesn't change after creation; transformations produce new values
• Pure functions — same input always produces same output, no side effects
• Composition — build complex behavior by chaining simple functions
• Types as documentation — types express constraints and invariants

Go isn't a pure FP language, but Go 1.18+ generics make FP patterns practical. samber/mo brings the most battle-tested FP abstractions — monads — to Go.

What is a Monad?

A monad is a design pattern (not a class or interface) that:

1. Wraps a value in a context (Option wraps "maybe absent", Result wraps "maybe failed") 2. Chains operations that transform the wrapped value without unwrapping it 3. Handles the context automatically — if an Option is None, Map/FlatMap skip the transformation; if a Result is Err, subsequent Maps short-circuit

Think of it as a container with a policy: "I hold a value, and I know what to do when operations succeed or fail."

The Railway Metaphor

Imagine two parallel railway tracks:

• Happy track (top): data flows through transformations successfully
• Error track (bottom): once something goes wrong, the train switches to the error track and skips remaining transformations

Input → [Transform A] → [Transform B] → [Transform C] → Output
          ↓ (error)       (skipped)       (skipped)
       Error track ────────────────────────────────────→ Error

This is exactly how Result.Map and Result.FlatMap work — errors propagate automatically without explicit if/else checks.

Why Monads Are Valuable in Go

1. Compile-Time Nil Safety (Option)

Go's type system doesn't distinguish "this pointer could be nil" from "this pointer is always valid". Option[T] makes this explicit:

// Without mo — caller must remember to check nil
func FindUser(id string) *User { ... }  // might return nil

// With mo — the type TELLS you it might be absent
func FindUser(id string) mo.Option[User] { ... }  // caller must handle None

The type signature is the documentation. No nil pointer panics at runtime — the compiler forces you to handle absence.

2. Railway-Oriented Error Handling (Result)

Go's idiomatic error handling requires checking errors at every step:

// Without mo — repetitive error checking
data, err := readFile(path)
if err != nil { return err }
config, err := parseConfig(data)
if err != nil { return err }
validated, err := validate(config)
if err != nil { return err }

With Result and mo.Do, errors short-circuit through the chain:

// With mo — errors propagate automatically via Do notation
result := mo.Do(func() Config {
    data := mo.TupleToResult(readFile(path)).MustGet()
    config := mo.TupleToResult(parseConfig(data)).MustGet()
    validated := mo.TupleToResult(validate(config)).MustGet()
    return validated
})

Same logic, less boilerplate. The error path is handled by the monad — any MustGet() failure short-circuits to Err.

Note: Direct .Map/.FlatMap methods cannot change the type parameter (Go methods cannot introduce new generic types). For type-changing pipelines, use sub-package result.Pipe functions or mo.Do notation as shown above.

3. Composable Pipelines

Monads compose naturally. You can build complex data transformations from simple, testable pieces:

import "github.com/samber/mo/option"

result := option.Pipe3(
    getUserOption(id),
    option.Map(func(u User) string { return u.Email }),
    option.FlatMap(func(email string) mo.Option[string] {
        if isValid(email) { return mo.Some(email) }
        return mo.None[string]()
    }),
    option.Map(func(email string) EmailAddress { return NewEmailAddress(email) }),
)

Each step is a pure function. The pipeline handles None propagation. Each step is independently testable.

The Three Core Monads

Option — Represents Absence

Problem it solves: nil pointer panics, ambiguous zero values.

Use Option when: a value might legitimately be absent (nullable DB columns, optional config, cache lookups).

Don't use Option when: a zero value is meaningful (empty string is valid, 0 is a valid count).

Result — Represents Fallibility

Problem it solves: verbose error checking, lost error context in chains.

Use Result when: you're chaining multiple fallible operations and want errors to propagate automatically.

Don't use Result when: you need to inspect or modify the error at each step (standard Go error handling is more explicit).

Either — Represents Alternatives

Problem it solves: functions that legitimately return one of two types.

Use Either when: both outcomes are valid, neither is an "error". If one side is always an error, use Result instead.

When to Use mo vs Plain Go

Use mo when:

• You're building data transformation pipelines with multiple steps
• You need type-safe nullable values (especially in JSON/DB models)
• Error handling chains become repetitive
• You want to make impossible states unrepresentable in the type system

Stick with plain Go when:

• Simple one-step operations where if err != nil is clear enough
• Performance-critical hot paths (monads add thin allocation overhead)
• Your team isn't familiar with FP concepts (readability > cleverness)
• The operation has complex error recovery at each step (explicit handling is clearer)

Option[T] API Reference

Constructors

Query Methods

Value Extraction

Transformations

Map — transform the value if present

opt := mo.Some(42)
doubled := opt.Map(func(v int) (int, bool) {
    return v * 2, true  // (new value, keep as Some)
})
// Some(84)

// Return false to convert to None
filtered := opt.Map(func(v int) (int, bool) {
    return v, v > 100  // None because 42 <= 100
})

Go limitation: Option.Map takes func(T) (T, bool) — the input and output types must be the same T. The bool controls whether the result is Some or None. To change the type (e.g. Option[int] to Option[string]), use sub-package option.Map — see Pipelines Reference.

MapValue — transform without filter

opt := mo.Some(42)
doubled := opt.MapValue(func(v int) int { return v * 2 })
// Some(84) — always stays Some if input was Some, no bool needed

Unlike Map, MapValue's callback returns just T (not (T, bool)), so it cannot convert to None.

MapNone — provide value when absent

opt := mo.None[int]()
filled := opt.MapNone(func() (int, bool) {
    return 42, true  // provide default as Some
})
// Some(42)

FlatMap — chain Options (same type)

func findUser(id string) mo.Option[User] { ... }
func refreshUser(u User) mo.Option[User] { ... }

refreshed := findUser("123").FlatMap(func(u User) mo.Option[User] {
    return refreshUser(u)  // same type: Option[User] -> Option[User]
})

Go limitation: Direct .FlatMap requires func(T) Option[T] — same input and output type. For type-changing chains (e.g. Option[User] to Option[string]), use option.FlatMap from the sub-package or mo.Do notation.

Match — handle both cases

opt.Match(
    func(v int) (int, bool) {
        fmt.Println("Got:", v)
        return v, true       // keep as Some
    },
    func() (int, bool) {
        fmt.Println("Empty!")
        return 0, false       // stay as None
    },
)

ForEach — side effect on present value

opt.ForEach(func(v int) {
    fmt.Println("Value:", v)  // only executes if present
})

Equality

mo.Some(42).Equal(mo.Some(42))  // true
mo.Some(42).Equal(mo.None[int]())  // false
mo.None[int]().Equal(mo.None[int]())  // true

Serialization

Option implements multiple encoding interfaces:

Database Support

Option implements sql.Scanner and driver.Valuer:

type User struct {
    ID    int
    Phone mo.Option[string]  // nullable column
}

// Scanning
err := row.Scan(&u.ID, &u.Phone)

// Inserting
_, err := db.Exec("INSERT INTO users (id, phone) VALUES ($1, $2)", u.ID, u.Phone)

Go 1.24+ omitzero Support

type Response struct {
    Data    string            `json:"data"`
    Extra   mo.Option[string] `json:"extra,omitzero"`  // omitted when None
}

IsZero() returns true when the Option is None, enabling the omitzero JSON tag.

Pipeline Sub-Packages Reference

samber/mo provides sub-packages (option, result, either, either3, either4, either5) with standalone functions for type-changing transformations and composable pipelines.

Why Sub-Packages Exist

Direct methods on Option/Result/Either (.Map, .FlatMap) cannot change the type parameter because Go methods cannot introduce new type parameters. For example:

opt := mo.Some(42)
// opt.Map can return Option[int], but NOT Option[string]
// because Map's signature is: func (o Option[T]) Map(func(T) (T, bool)) Option[T]

Sub-package functions solve this by being standalone generic functions:

import "github.com/samber/mo/option"

// option.Map CAN change the type: Option[int] -> Option[string]
strOpt := option.Map(func(v int) string {
    return strconv.Itoa(v)
})(mo.Some(42))
// Some("42")

option/ Package

Transformation Functions

Pipe Functions

Chain multiple transformations in a readable pipeline:

import "github.com/samber/mo/option"

result := option.Pipe3(
    mo.Some(42),                                                          // Option[int]
    option.Map(func(v int) string { return strconv.Itoa(v) }),            // -> Option[string]
    option.Map(func(s string) []byte { return []byte(s) }),               // -> Option[[]byte]
    option.FlatMap(func(b []byte) mo.Option[string] {                     // -> Option[string]
        if len(b) > 0 { return mo.Some(string(b)) }
        return mo.None[string]()
    }),
)

Available: option.Pipe1 through option.Pipe10 (1 to 10 transformation steps).

result/ Package

Transformation Functions

Pipe Functions

import "github.com/samber/mo/result"

parsed := result.Pipe2(
    mo.TupleToResult(os.ReadFile("config.yaml")),                         // Result[[]byte]
    result.Map(func(data []byte) Config {                                 // -> Result[Config]
        var cfg Config
        yaml.Unmarshal(data, &cfg)
        return cfg
    }),
    result.FlatMap(func(cfg Config) mo.Result[ValidConfig] {              // -> Result[ValidConfig]
        return validateConfig(cfg)
    }),
)

Available: result.Pipe1 through result.Pipe10.

either/ Package

Transformation Functions

Pipe Functions

import "github.com/samber/mo/either"

result := either.Pipe2(
    mo.Right[error, int](42),
    either.MapRight(func(v int) string { return strconv.Itoa(v) }),
    either.MapRight(func(s string) []byte { return []byte(s) }),
)

Available: either.Pipe1 through either.Pipe10.

either3/, either4/, either5/ Packages

Each provides:

• Match with handlers for each argument type
• MapArg1, MapArg2, MapArg3 (up to MapArg5 for either5)
• Pipe1 through Pipe10

When to Use Pipes vs Direct Methods

Example: Combined Usage

// Start with direct method (same type)
opt := mo.Some(42).
    Map(func(v int) (int, bool) { return v * 2, true })  // still Option[int]

// Then use pipe for type change
result := option.Pipe2(
    opt,
    option.Map(func(v int) string { return strconv.Itoa(v) }),  // -> Option[string]
    option.Map(func(s string) User { return User{Name: s} }),   // -> Option[User]
)

Result[T] API Reference

Constructors

Do Notation

result := mo.Do(func() int {
    a := mo.Ok(10).MustGet()     // panics if Err -> caught by Do
    b := mo.Ok(32).MustGet()
    return a + b
})
// Ok(42)

mo.Do executes a closure and catches any panic from MustGet() calls, converting them to Err. This enables imperative-style code with monadic error propagation.

Query Methods

Value Extraction

Transformations

Map — transform successful value

result := mo.Ok(42).
    Map(func(v int) (int, error) {
        return v * 2, nil
    })
// Ok(84)

// Errors short-circuit
result := mo.Err[int](errors.New("fail")).
    Map(func(v int) (int, error) {
        return v * 2, nil  // never called
    })
// Err("fail")

Go limitation: Result.Map takes func(T) (T, error) — the input and output types must be the same T. Returning a non-nil error converts Ok to Err. To change the type (e.g. Result[[]byte] to Result[Config]), use sub-package result.Map or mo.Do notation — see Pipelines Reference.

MapValue — transform without error possibility

result := mo.Ok(42).MapValue(func(v int) int {
    return v * 2
})
// Ok(84) — no error possible in the mapper

MapErr — transform error state

result := mo.Err[int](errors.New("fail")).
    MapErr(func(err error) (int, error) {
        return 0, fmt.Errorf("wrapped: %w", err)
    })
// Err("wrapped: fail")

FlatMap — chain Results

func parseAge(s string) mo.Result[int] {
    v, err := strconv.Atoi(s)
    return mo.TupleToResult(v, err)
}

func validateAge(age int) mo.Result[int] {
    if age < 0 || age > 150 {
        return mo.Errf[int]("invalid age: %d", age)
    }
    return mo.Ok(age)
}

result := parseAge("25").FlatMap(func(age int) mo.Result[int] {
    return validateAge(age)
})
// Ok(25)

Match — handle both cases

result.Match(
    func(v int) (int, error) {
        fmt.Println("Success:", v)
        return v, nil
    },
    func(err error) (int, error) {
        fmt.Println("Error:", err)
        return 0, err
    },
)

ForEach — side effect on success

result.ForEach(func(v int) {
    fmt.Println("Got:", v)  // only executes if Ok
})

Conversion

either := result.ToEither()  // Either[error, T]
// Ok(42) -> Right(42)
// Err(e) -> Left(e)

JSON Serialization

Result marshals to JSON-RPC format:

// Ok(42) marshals to:
{"result": 42}

// Err("fail") marshals to:
{"error": {"message": "fail"}}