mona-result

Mona::Result

Provides a result monad, with OK holding a value, and Err holding a failure, with optional reason, and metadata.

Also provides a dict result monad, a hash-like result, which provides #sequence whose semantics mirror do notation

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add mona-result

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install mona-result

Usage

Result = Mona::Result

# basic OK
success = Result.ok(1) # => #<OK 1>
success.ok? # => true
success.err? # => false
success.value # => 1

success.and_tap { puts "it is #{_1}" }
       .and_then { _1 * 5 }
       .value_or { :nope }
# OUT: it is 1
# => 5

# basic Err
failure = Result.err(4, :not_prime) # => #<Err 4 reason: :not_prime>
failure.ok? # => false
failure.err? # => true
failure.failure # => 4
failure.reason # => :not_prime

failure.and_tap { puts "it is #{_1}" }
       .and_then { _1 * 5 }
       .value_or { :nope }
# => :nope

# Dict with sequence, example using a fictional repository.
# #set can take a [Symbol, Symbol] key argument where left is OK key, right is Err key
result = Result.dict do |d|
  d.set :user, UserRepo.find user_id
  d.set :input, PostInput.valid(attributes)
  d.set [:post, :input], PostRepo.create user_id: user_id, **d[:input]
end
# if find user fails:  # => #<Err {:user=>NotFoundError} reason: :not_found, key: :user>
# if validation fails: # => #<Err {:user=>User, :input=>PostInput(invalid)} reason: :invalid, key: :input>
# if create fails:     # => #<Err {:user=>User, :input=>PostInput(db err)} reason: :db_err, key: :input>
# if all ok:           # => #<OK: {:user=>User, :post=>Post}>

# Action - a callable sequence
divide = Result.action do |x, y|
  set :numerator, x
  set :divisor, y.zero? ? Result.err(y, :is_zero) : y
  puts "ready to calculate answer"
  set :answer, numerator / divisor
  puts "answer was: #{answer}"
end

divide.call(12, 4)
# OUT: ready to calculate answer
# OUT: answer was: 3
# => #<OK {:numerator=>12, :divisor=>4, :answer=>3}>

result = divide.call(12, 0) # => #<Err {:numerator=>12, :divisor=>0} reason: :is_zero, key: :divisor>
result.err? # => true
result.failure # => {:numerator=>12, :divisor=>0}
result.reason # => :is_zero
result.meta # => {:key=>:divisor}

Pattern matching is supported in the following way:

case result
in :ok, value
in :err, failure, reason, { **meta }
end

case result
in ok:
in err:, reason:, **meta
end

You can also match a result, using similar semantics, the difference from using case/pattern-match is that a Mona::Result::NoMatchError is raised, which keeps a reference to the result (which is useful for differentially handling errors in an enclosing scope - not currently possible with ruby's NoMatchingPatternError which does not contain any information about the failed match)

Mona::Result.match(result) do |on|
  on.ok            { |value| puts "ok" }
  on.err(key: :x)  { |failure, reason, **meta| puts "error with meta :key => :x" }
  on.err(:invalid) { |failure, reason, **meta| puts "error with reason :invalid" }
  on.err           { |failure, reason, **meta| puts "error" }
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mona-rb/mona-result.

License

The gem is available as open source under the terms of the MIT License.