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

```ruby 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 :input=>PostInput(invalid) reason: :invalid, key: :input> # if create fails: # => #<Err :input=>PostInput(db err) reason: :db_err, key: :input> # if all ok: # => #<OK: :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 :divisor=>4, :answer=>3>

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

Pattern matching is supported in the following way:

```ruby 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)

ruby 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.