samber/mo

mo - Monads

🦄 samber/mo brings monads and popular FP abstractions to Go projects. samber/mo uses the recent Go 1.18+ Generics.

Inspired by:

• Scala
• Rust
• FP-TS

See also:

• samber/ro: Reactive Programming for Go: declarative and composable API for event-driven applications
• samber/lo: A Lodash-style Go library based on Go 1.18+ Generics
• samber/do: A dependency injection toolkit based on Go 1.18+ Generics
• samber/cc-skills-golang: AI Agent Skills for Golang

^{💖 Sponsored by:}

DBOS - Durable workflow orchestration library for Go

Why this name?

I love short name for such utility library. This name is similar to "Monad Go" and no Go package uses this name.

💡 Features

We currently support the following data types:

• Option[T] (Maybe)
• Result[T]
• Either[A, B]
• EitherX[T1, ..., TX] (With X between 3 and 5)
• Future[T]
• IO[T]
• IOEither[T]
• Task[T]
• TaskEither[T]
• State[S, A]

🚀 Install

go get github.com/samber/mo@v1

# AI Agent Skill
npx skills add https://github.com/samber/cc-skills-golang --skill golang-samber-mo

This library is v1 and follows SemVer strictly.

No breaking changes will be made to exported APIs before v2.0.0.

This library has no dependencies except the Go std lib.

💡 Quick start

You can import mo using:

import (
    "github.com/samber/mo"
)

Quick example using the option sub-package Pipe3 to compose transformations:

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

out := option.Pipe3(
    mo.Some(21),
    option.Map(func(v int) int { return v * 2 }),
    option.FlatMap(func(v int) mo.Option[int] { return mo.None[int]() }),
    option.Map(func(v int) int { return v + 21 }),
)
// out == None[int]

Then use one of the helpers below:

option1 := mo.Some(42)
// Some(42)

option1.
    FlatMap(func (value int) Option[int] {
        return Some(value*2)
    }).
    FlatMap(func (value int) Option[int] {
        return Some(value%2)
    }).
    FlatMap(func (value int) Option[int] {
        return Some(value+21)
    }).
    OrElse(1234)
// 21

option2 := mo.None[int]()
// None

option2.OrElse(1234)
// 1234

option3 := option1.Match(
    func(i int) (int, bool) {
        // when value is present
        return i * 2, true
    },
    func() (int, bool) {
        // when value is absent
        return 0, false
    },
)
// Some(42)

More examples in documentation.

Tips for lazy developers

I cannot recommend it, but in case you are too lazy for repeating mo. everywhere, you can import the entire library into the namespace.

import (
    . "github.com/samber/mo"
)

I take no responsibility on this junk. 😁 💩

🤠 Documentation and examples

GoDoc: https://godoc.org/github.com/samber/mo

Option[T any]

Option is a container for an optional value of type T. If value exists, Option is of type Some. If the value is absent, Option is of type None.

Implements:

• mo.Foldable[T, U]

Constructors:

• mo.Some() doc - play
• mo.None() doc - play
• mo.TupleToOption() doc - play
• mo.EmptyableToOption() doc - play
• mo.PointerToOption() doc - play

Methods:

• .IsPresent() doc - play
• .IsSome() doc - play
• .IsAbsent() doc - play
• .IsNone() doc - play
• .Size() doc - play
• .Get() doc - play
• .MustGet() doc - play
• .OrElse() doc - play
• .OrEmpty() doc - play
• .ToPointer() doc - play
• .ForEach() doc
• .Match() doc - play
• .Map() doc - play
• .MapNone() doc - play
• .MapValue() doc
• .FlatMap() doc - play
• .MarshalJSON() doc
• .UnmarshalJSON() doc
• .MarshalText() doc
• .UnmarshalText() doc
• .MarshalBinary() doc
• .UnmarshalBinary() doc
• .GobEncode() doc
• .GobDecode() doc
• .Scan() doc
• .Value() doc

Other:

• mo.Fold[T, U, R any](f Foldable[T, U], successFunc func(U) R, failureFunc func(T) R) R doc

Sub-package option (transformations and pipes):

• option.Map()() doc
• option.FlatMap()() doc
• option.Match()() doc
• option.FlatMatch()() doc
• option.Pipe1..Pipe10() docs

Result[T any]

Result respresent a result of an action having one of the following output: success or failure. An instance of Result is an instance of either Ok or Err. It could be compared to Either[error, T].

Implements:

• mo.Foldable[T, U]

Constructors:

• mo.Ok() doc - play
• mo.Err() doc - play
• mo.Errf() doc - play
• mo.TupleToResult() doc - play
• mo.Try() doc - play

Methods:

• .IsOk() doc - play
• .IsError() doc - play
• .Error() doc - play
• .Get() doc - play
• .MustGet() doc - play
• .OrElse() doc - play
• .OrEmpty() doc - play
• .ToEither() doc - play
• .ForEach() doc - play
• .Match() doc - play
• .Map() doc - play
• .MapValue() doc - play
• .MapErr() doc - play
• .FlatMap() doc - play

Other:

• mo.Fold[T, U, R any](f Foldable[T, U], successFunc func(U) R, failureFunc func(T) R) R doc
• mo.Do[T any](fn func() T) (result mo.Result[T]) doc

Sub-package result (transformations and pipes):

• result.Map()() doc
• result.FlatMap()() doc
• result.Match()() doc
• result.FlatMatch()() doc
• result.Pipe1..Pipe10() docs

Either[L any, R any]

Either represents a value of 2 possible types. An instance of Either is an instance of either A or B.

Implements:

• mo.Foldable[T, U]

Constructors:

• mo.Left() doc
• mo.Right() doc

Methods:

• .IsLeft() doc
• .IsRight() doc
• .Left() doc
• .Right() doc
• .MustLeft() doc
• .MustRight() doc
• .Unpack() doc
• .LeftOrElse() doc
• .RightOrElse() doc
• .LeftOrEmpty() doc
• .RightOrEmpty() doc
• .Swap() doc
• .ForEach() doc
• .Match() doc
• .MapLeft() doc
• .MapRight() doc

Other:

• mo.Fold[T, U, R any](f Foldable[T, U], successFunc func(U) R, failureFunc func(T) R) R doc

Sub-package either (transformations and pipes):

• either.MapLeft()() doc
• either.MapRight()() doc
• either.Match()() doc
• either.Swap()() doc
• either.Pipe1..Pipe10() docs

EitherX[T1, ..., TX] (With X between 3 and 5)

EitherX respresents a value of X possible types. For example, an Either3 value is either T1, T2 or T3.

Constructors:

• mo.NewEitherXArgY() doc. Eg:
  • mo.NewEither3Arg1[A, B, C](A)
  • mo.NewEither3Arg2[A, B, C](B)
  • mo.NewEither3Arg3[A, B, C](C)
  • mo.NewEither4Arg1[A, B, C, D](A)
  • mo.NewEither4Arg2[A, B, C, D](B)
  • ...

Methods:

• .IsArgX() doc
• .ArgX() doc
• .MustArgX() doc
• .Unpack() doc
• .ArgXOrElse() doc
• .ArgXOrEmpty() doc
• .ForEach() doc
• .Match() doc
• .MapArgX() doc

Sub-packages either3, either4, either5 (transformations and pipes):

• either3 docs: https://pkg.go.dev/github.com/samber/mo/either3

  • either3.Match()() doc
  • either3.MapArg1()() doc
  • either3.MapArg2()() doc
  • either3.MapArg3()() doc
  • either3.Pipe1..Pipe10() docs

• either4 docs: https://pkg.go.dev/github.com/samber/mo/either4

  • either4.Match()() doc
  • either4.MapArg1()() doc
  • either4.MapArg2()() doc
  • either4.MapArg3()() doc
  • either4.Pipe1..Pipe10() docs

• either5 docs: https://pkg.go.dev/github.com/samber/mo/either5

  • either5.Match()() doc
  • either5.MapArg1()() doc
  • either5.MapArg2()() doc
  • either5.MapArg3()() doc
  • either5.Pipe1..Pipe10() docs

Future[T any]

Future represents a value which may or may not currently be available, but will be available at some point, or an exception if that value could not be made available.

Constructors:

• mo.NewFuture() doc

Methods:

• .Then() doc
• .Catch() doc
• .Finally() doc
• .Collect() doc
• .Result() doc
• .Cancel() doc

IO[T any]

IO represents a non-deterministic synchronous computation that can cause side effects, yields a value of type R and never fails.

Constructors:

• mo.NewIO() doc
• mo.NewIO1() doc
• mo.NewIO2() doc
• mo.NewIO3() doc
• mo.NewIO4() doc
• mo.NewIO5() doc

Methods:

• .Run() doc

IOEither[T any]

IO represents a non-deterministic synchronous computation that can cause side effects, yields a value of type R and can fail.

Constructors:

• mo.NewIOEither() doc
• mo.NewIOEither1() doc
• mo.NewIOEither2() doc
• mo.NewIOEither3() doc
• mo.NewIOEither4() doc
• mo.NewIOEither5() doc

Methods:

• .Run() doc

Task[T any]

Task represents a non-deterministic asynchronous computation that can cause side effects, yields a value of type R and never fails.

Constructors:

• mo.NewTask() doc
• mo.NewTask1() doc
• mo.NewTask2() doc
• mo.NewTask3() doc
• mo.NewTask4() doc
• mo.NewTask5() doc
• mo.NewTaskFromIO() doc
• mo.NewTaskFromIO1() doc
• mo.NewTaskFromIO2() doc
• mo.NewTaskFromIO3() doc
• mo.NewTaskFromIO4() doc
• mo.NewTaskFromIO5() doc

Methods:

• .Run() doc

TaskEither[T any]

TaskEither represents a non-deterministic asynchronous computation that can cause side effects, yields a value of type R and can fail.

Constructors:

• mo.NewTaskEither() doc
• mo.NewTaskEitherFromIOEither() doc

Methods:

• .Run() doc
• .OrElse() doc
• .Match() doc
• .TryCatch() doc
• .ToTask() doc
• .ToEither() doc

State[S any, A any]

State represents a function (S) -> (A, S), where S is state, A is result.

Constructors:

• mo.NewState() doc
• mo.ReturnState() doc

Methods:

• .Run() doc
• .Get() doc
• .Modify() doc
• .Put() doc

Foldable[T, U]

Foldable represents a type that can be folded into a single value based on its state.

• mo.Fold[T, U, R any](f Foldable[T, U], successFunc func(U) R, failureFunc func(T) R) R doc

🛩 Benchmark

// @TODO

This library does not use reflect package. We don't expect overhead.

🤝 Contributing

• Ping me on Twitter @samuelberthe (DMs, mentions, whatever :))
• Fork the project
• Fix open issues or request new features

Don't hesitate ;)

# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test

👤 Contributors

💫 Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2022 Samuel Berthe.

This project is MIT licensed.