dry-monads 1.3

View dry-monads on GitHub

Result

The Result monad is useful to express a series of computations that might return an error object with additional information.

The Result mixin has two type constructors: Success and Failure. The Success can be thought of as "everything went successfully" and the Failure is used when "something has gone wrong".

bind

Use bind for composing several possibly-failing operations:

require 'dry/monads'

class AssociateUser
  include Dry::Monads[:result]

  def call(user_id:, address_id:)
    find_user(user_id).bind do |user|
      find_address(address_id).fmap do |address|
        user.update(address_id: address.id)
      end
    end
  end

  private

  def find_user(id)
    user = User.find_by(id: id)

    if user
      Success(user)
    else
      Failure(:user_not_found)
    end
  end

  def find_address(id)
    address = Address.find_by(id: id)

    if address
      Success(address)
    else
      Failure(:address_not_found)
    end
  end
end

AssociateUser.new.(user_id: 1, address_id: 2)

fmap

An example of using fmap with Success and Failure.

extend Dry::Monads[:result]

result = if foo > bar
  Success(10)
else
  Failure("wrong")
end.fmap { |x| x * 2 }

# If everything went successfully
result # => Success(20)
# If it did not
result # => Failure("wrong")

# #fmap accepts a proc, just like #bind

upcase = :upcase.to_proc

Success('hello').fmap(upcase) # => Success("HELLO")

value_or

value_or is a safe and recommended way of extracting values.

extend Dry::Monads[:result]

Success(10).value_or(0) # => 10
Failure('Error').value_or(0) # => 0

value!

If you're 100% sure you're dealing with a Success case you might use value! for extracting the value without providing a default. Beware, this will raise an exception if you call it on Failure.

extend Dry::Monads[:result]

Success(10).value! # => 10
Failure('Error').value!
# => Dry::Monads::UnwrapError: value! was called on Failure

or

An example of using or with Success and Failure.

extend Dry::Monads[:result]

Success(10).or(Success(99)) # => Success(10)
Failure("error").or(Failure("new error")) # => Failure("new error")
Failure("error").or { |err| Failure("new #{err}") } # => Failure("new error")

failure

Use failure for unwrapping the value from a Failure instance.

extend Dry::Monads[:result]

Failure('Error').failure # => "Error"

to_maybe

Sometimes it's useful to turn a Result into a Maybe.

extend Dry::Monads[:result, :maybe]

result = if foo > bar
  Success(10)
else
  Failure("wrong")
end.to_maybe

# If everything went successfully
result # => Some(10)
# If it did not
result # => None()

failure? and success?

You can explicitly check the type by calling failure? or success? on a monadic value.

either

either maps a Result to some type by taking two callables, for Success and Failure cases respectively:

Success(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 2
Failure(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 3

Adding constraints to Failure values.

You can add type constraints to values passed to Failure. This will raise an exception if value doesn't meet the constraints:

require 'dry-types'

module Types
  include Dry.Types()
end

class Operation
  Error = Types.Instance(RangeError)
  include Dry::Monads::Result(Error)

  def call(value)
    case value
    when 0..1
      Success(:success)
    when -Float::INFINITY..0, 1..Float::INFINITY
      Failure(RangeError.new('Error'))
    else
      Failure(TypeError.new('Type error'))
    end
  end
end

Operation.new.call(0.5) # => Success(:success)
Operation.new.call(5) # => Failure(#<RangeError: Error>)
Operation.new.call("5") # => Dry::Monads::InvalidFailureTypeError: Cannot create Failure from #<TypeError: Type error>, it doesn't meet the constraints

octocatEdit on GitHub