resonad 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7eee55274773363f0220a61e2d4714d11a129869
-  data.tar.gz: 05873de655e1cc85fe147e7b247788ad273f10d9
+SHA256:
+  metadata.gz: 2751182e01f6cf2c97cdc99d46cb716ec1e517d52680bc75c92fd0f5c1bd693f
+  data.tar.gz: 2d1a5a21e81f7da804fa099d16a8b3a2032472e6f89112e4284942d050087293
 SHA512:
-  metadata.gz: 34f5b90502c5737493195d5e44ed8b6686f1c9cb3145c240c09609db89deb5e577196e01ba55e3bdf3a9511d4107f996d8a26bbbcc7c4e55fc01f645956e312b
-  data.tar.gz: a1a80de205c720d7f2ba54e799b97ad7cb0da4edac82b5dfba6aba8ab4b1fa87d7133fc03f71d452b4c834cf9c399ee85f076696290bcccbc6e81e3ac9cda482
+  metadata.gz: 6571a2f2e4e2ae98dee8c40efbf0bccf0aed09b6bc18cce47a5fb3fc83cc77c32141b31807d9b64b2842c62dfc737025ac24234dc22a1285f0e9910dae97cced
+  data.tar.gz: a000acabecf552daebeff7f10b1e57ab44f7fba224e8e85deb25acb7904b0c97981453931f008b68547b2fdade0e3ebec8d8b868af6757f4271a4a434f075cdb

data/.rspec

@@ -1,2 +1,6 @@
+--require spec_helper
+<% if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.7') %>
+  --exclude-pattern spec/pattern_matching_spec.rb
+<% end %>
 --format documentation
 --color

data/.ruby-version

@@ -0,0 +1 @@
+2.7

data/.travis.yml

@@ -1,13 +1,25 @@
 language: ruby
+script: bundle exec rspec
+
+# test old rubies
 rvm:
-- 2.2.7
-- 2.3.4
-- 2.4.1
-cache: bundler
+  - 2.2.10
+  - 2.3.8
+  - 2.4.10
+  - 2.5.8
+  - 2.6.6
+
+# test on latest ruby
+matrix:
+  include:
+    - rvm: 2.7.1
+      env: LATEST_RUBY=true
+
+# Rubygems deployment
 deploy:
   provider: rubygems
   on:
     tags: true
-    rvm: 2.4.1
+    condition: $LATEST_RUBY = true
   api_key:
     secure: 0+R2SaUaKOZE0U4FwHiC/0DLepizJ1anjfvFEWk5pYVkaZl6HuaSYq50g8ff4VqXBH955Y5W7tFI8gfg4ZY9jrivHyEZT9Yoz3PFFPxcqSdVbDsV12RQt7ZjzW0HbvUhFu9nlrVACfFsLt4WFG61pyhXvewghp1p4JBp2UxeTk1kyL7U+wfWsp1RpcKiHkaLBeWJ0N87j4QkhTfcWlModLqN/19ATigvfyDjrwerkTescVmQi4TzfAiwkeAiDgUB32FkwJjbX9RfIko33CsuctuDRU/HT+RWiXcGAxdHZx4dtQpP9pAiNTVxXdIq+QAvitekIah70pdCTNKrOh3tDj3kglkUK23MqU6kdeXjmUn9r4SuzHCX0sVf16UpfnwuryDDPlG1ISY+mf7BARr/wNQWuAD4MA4kWiPGMqT/0uoysbY7dt44lkO9NV7HBbqs2shqqMtmgPgDoJ+SGTXo8LvrjuL0jHB2/MoHziiqWDKLQ9PS2Fcqp/06d5u8GcSRt7dcgo2rvwnMwRdUW6iCV0zQgzrNccWn/SsJROtgzEIkuLJYO0GIOCgNBJ0euorWqQBEEPniltwh5StSgH2bL5khdPxiI+LhsL7UDhWGiNFl5tlQp8Ob98WmmQ39ZyVAGKlJoe2rdE/IaDVfysVvQV5XzYUVRn4ZKftwubo5Zvw=

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.0] - 2020-07-12
+### Added
+- more documentation
+- support for Ruby 2.7 pattern matching
+- `#otherwise` alias for `#or_else`
+- `#map_value` alias for `#map`
+- alternate constructor methods
+- aliases for `#on_success` and `#on_failure`
+- `Success` and `Failure` class constants to `Resonad::Mixin`
+- `Resonad::PublicMixin` for people who want the previous behaviour of
+  `Resonad::Mixin`
+### Changed
+- The methods provided by `Resonad::Mixin` are now private. Replace with
+  `Resonad::PublicMixin` to revert them back to being public.
+
+## [1.2.0] - 2017-05-22
+### Added
+- `Resonad.Success()` and `Resonad.Failure()` arguments are optional, and
+  default to nil.
+- `#successful?` and `#ok?` as new aliases for `#success?`
+- `#failed?` and `#bad?` as new aliases for `#failure?`
+
+## [1.1.1] - 2017-05-09
+### Fixed
+- Aliased methods `#and_then` and `#or_else` were not aliased properly.
+
+## [1.1.0] - 2017-05-01
+### Added
+- `Resonad::Mixin`
+### Changed
+- `Resonad` is now a class. `Resonad::Success` and `Resonad::Failure` now
+  inherit from `Resonad`.
+
+## [1.0.2] - 2017-04-22
+### Fixed
+- Typo in class names
+
+## [1.0.1] - 2017-04-22
+### Changed
+- Nothing (bumped to force a deploy)
+
+## [1.0.0] - 2017-04-22
+### Added
+- Everything (initial release)

data/README.md

@@ -1,15 +1,26 @@
+[![Build Status](https://travis-ci.org/tomdalling/resonad.svg?branch=master)](https://travis-ci.org/tomdalling/resonad)
+
 # Resonad
 
-Usage example (assume each method returns a `Resonad`):
+Lightweight, functional "result" objects that can be used instead of exceptions.
+
+Read: [Result Objects - Errors Without Exceptions](https://www.rubypigeon.com/posts/result-objects-errors-without-exceptions/)
+
+## Typical Usage Example
+
+Assuming each method returns a `Resonad` (Ruby 2.7 syntax):
 
 ```ruby
 find_widget(widget_id)
-  .and_then { |widget| update_widget(widget) }
-  .on_success { |widget| logger.info("Updated #{widget}" }
-  .on_failure { |error| logger.warn("Widget update failed because #{error}") }
+  .and_then { update_widget(_1) }
+  .on_success { logger.info("Updated #{_1}" }
+  .on_failure { logger.warn("Widget update failed because #{_1}") }
 ```
 
-Success type:
+## Success Type
+
+A value that represents success. Wraps a `value` that can be any arbitrary
+object.
 
 ```ruby
 result = Resonad.Success(5)
@@ -19,7 +30,10 @@ result.value #=> 5
 result.error #=> raises an exception
 ```
 
-Failure type:
+## Failure Type
+
+A value that represents a failure. Wraps an `error` that can be any arbitrary
+object.
 
 ```ruby
 result = Resonad.Failure(:buzz)
@@ -29,39 +43,199 @@ result.value #=> raises an exception
 result.error #=> :buzz
 ```
 
-Mapping monads:
+## Mapping
+
+Non-destructive update for the `value` of a `Success` object. Does nothing to
+`Failure` objects.
+
+The block takes the `value` as an argument, and returns the new `value`.
 
 ```ruby
 result = Resonad.Success(5)
-  .map { |i| i + 1 }
-  .map { |i| i + 1 }
-  .map { |i| i + 1 }
+  .map { _1 + 1 }  # 5 + 1 -> 6
+  .map { _1 + 1 }  # 6 + 1 -> 7
+  .map { _1 + 1 }  # 7 + 1 -> 8
 result.success? #=> true
 result.value #=> 8
 
 result = Resonad.Failure(:buzz)
-  .map { |i| i + 1 }
-  .map { |i| i + 1 }
-  .map { |i| i + 1 }
+  .map { _1 + 1 }  # not run
+  .map { _1 + 1 }  # not run
+  .map { _1 + 1 }  # not run
 result.success? #=> false
 result.error #=> :buzz
 ```
 
-Flat mapping monads (a.k.a. `and_then`):
+
+## Aliases
+
+Lots of the Resonad methods have aliases.
+
+Personally, I can never remember if it's `success?` or `successful?` or `ok?`,
+so let's just do it the Ruby way and allow all of them.
+
+```ruby
+# >>> object creation aliases (same for failure) <<<
+result = Resonad.Success(5)
+result = Resonad.success(5)  # lowercase, for those offended by capital letters
+result = Resonad::Success[5]  # class constructor method
+
+# >>> success aliases <<<
+result.success?  #=> true
+result.successful?  #=> true
+result.ok?  #=> true
+
+# >>> failure aliases <<<
+result.failure?  #=> false
+result.failed?  #=> false
+result.bad?  #=> false
+
+# >>> mapping aliases <<<
+result.map { _1 + 1 }  #=> Success(6)
+result.map_value { _1 + 1 }  #=> Success(6)
+
+# >>> flat mapping aliases <<<
+result.and_then { Resonad.Success(_1 + 1) }  #=> Success(6)
+result.flat_map { Resonad.Success(_1 + 1) }  #=> Success(6)
+
+# >>> error flat mapping aliases <<<
+result.or_else { Resonad.Failure(_1 + 1) }  # not run
+result.otherwise { Resonad.Failure(_1 + 1) }  # not run
+result.flat_map_error { Resonad.Success(_1 + 1) }  # not run
+
+# >>> conditional tap aliases <<<
+# pattern: (on_|if_|when_)(success_alias|failure_alias)
+result.on_success { puts "hi" }  # outputs "hi"
+result.if_success { puts "hi" }  # outputs "hi"
+result.when_success { puts "hi" }  # outputs "hi"
+result.on_ok { puts "hi" }  # outputs "hi"
+result.if_ok { puts "hi" }  # outputs "hi"
+result.when_ok { puts "hi" }  # outputs "hi"
+result.on_successful { puts "hi" }  # outputs "hi"
+result.if_successful { puts "hi" }  # outputs "hi"
+result.when_successful { puts "hi" }  # outputs "hi"
+result.on_failure { puts "hi" }  # not run
+result.if_failure { puts "hi" }  # not run
+result.when_failure { puts "hi" }  # not run
+result.on_bad { puts "hi" }  # not run
+result.if_bad { puts "hi" }  # not run
+result.when_bad { puts "hi" }  # not run
+result.on_failed { puts "hi" }  # not run
+result.if_failed { puts "hi" }  # not run
+result.when_failed { puts "hi" }  # not run
+```
+
+
+## Flat Mapping (a.k.a. `and_then`)
+
+Non-destructive update for a `Success` object. Either turns it into another
+`Success` (can have a different `value`), or turns it into a `Failure`. Does
+nothing to `Failure` objects.
+
+The block takes the `value` as an argument, and returns a `Resonad` (either
+`Success` or `Failure`). 
 
 ```ruby
 result = Resonad.Success(5)
-  .and_then { |i| Resonad.Success(i + 1) }
-  .and_then { |i| Resonad.Failure("buzz #{i}") }
-  .and_then { |i| Resonad.Success(i + 1) }
+  .and_then { Resonad.Success(_1 + 1) }  # updates to Success(6)
+  .and_then { Resonad.Failure("buzz #{_1}") }  # updates to Failure("buzz 6")
+  .and_then { Resonad.Success(_1 + 1) }  # not run (because it's a failure)
   .error #=> "buzz 6"
 
-# can also use the less-nice `flat_map` method
-result
-  .flat_map { |i| Resonad.Success(i + 1) }
+# also has a less-friendly but more-technically-descriptive alias: `flat_map`
+result.flat_map { Resonad.Success(_1 + 1) }
 ```
 
-Automatic exception rescuing:
+This is different to Ruby's `#then` method added in 2.6. The block for `#then`
+would take a Resonad argument, regardless of whether it's `Success` or
+`Failure`. The block for `#and_then` takes a _`Success` object's value_, and
+only runs on `Success` objects, not `Failure` objects.
+
+
+## Error Mapping
+
+Just as `Success` objects can be chained with `#map` and `#and_then`, so can
+`Failure` objects with `#map_error` and `#or_else`. This isn't used as often,
+but has a few use cases such as:
+
+```ruby
+# Use Case: convert an error value into another error value
+make_http_request  #=> Failure(404)
+  .map_error { |status_code| "HTTP #{status_code} Error" }
+  .error #=> "HTTP 404 Error"
+
+# Use Case: recover from error, turning into Success
+load_config_file  #=> Failure(:config_file_missing)
+  .or_else { try_recover_from(_1) }
+  .value  #=> { :setting => 'default' }
+
+def try_recover_from(error)
+  if error == :config_file_missing
+    Resonad.Success({ setting: 'default' })
+  else
+    Resonad.Failure(error)
+  end
+end
+```
+
+
+## Conditional Tap
+
+If you're in the middle of a long chain of methods, and you don't want to break
+the chain to run some kind of side effect, you can use the `#on_success` and
+`#on_failure` methods. These run an arbitrary block code, but do not affect the
+result object in any way. They work like Ruby's `#tap` method, but `Failure`
+objects will not run `on_success` blocks, and `Success` objects will not run
+`on_failure` blocks.
+
+```ruby
+do_step_1
+  .and_then { do_step_2(_1) }
+  .and_then { do_step_3(_1) }
+  .on_success { puts "Successful step 3 result: #{_1}" }
+  .and_then { do_step_4(_1) }
+  .and_then { do_step_5(_1) }
+  .on_failure { puts "Uh oh! Step 5 failed: #{_1} }
+  .and_then { do_step_6(_1) }
+  .and_then { do_step_7(_1) }
+```
+
+There are lots of aliases for these methods. See the "Aliases" section above.
+
+
+## Pattern Matching Support
+
+If you are using Ruby 2.7 or later, you can pattern match on Resonad objects.
+For example:
+
+```ruby
+case result
+in { value: }  # match any Success
+  puts value
+in { error: :not_found } # match Failure(:not_found)
+  puts "Thing not found"
+in { error: String => msg } # match any Failure with a String error
+  puts "Failed to fetch thing because #{msg}"
+in { error: } # match any Failure
+  raise "Unhandled error: #{error.inspect}"
+end
+```
+
+`Resonad.Success(5)` deconstructs to:
+
+ - Hash: `{ value: 5 }`
+ - Array: `[:success, 5]`
+
+And `Resonad.Failure('yikes')` deconstructs to:
+
+ - Hash: `{ error: 'yikes' }`
+ - Array: `[:failure, 'yikes']`
+
+
+## Automatic Exception Rescuing
+
+If no exception is raised, wraps the block's return value in `Success`. If an
+exception is raised, wraps the exception object in `Failure`.
 
 ```ruby
 def try_divide(top, bottom)
@@ -76,3 +250,55 @@ nope = try_divide(6, 0)
 nope.success? #=> false
 node.error #=> #<ZeroDivisionError: ZeroDivisionError>
 ```
+
+
+## Convenience Mixin
+
+If you're tired of typing "Resonad." in front of everything, you can include
+the `Resonad::Mixin` mixin.
+
+```ruby
+class RobotFortuneTeller
+  include Resonad::Mixin
+
+  def next_fortune
+    case rand(0..100)
+    when 0..70
+      # title-case constructor from Resonad::Mixin
+      Success("today is auspicious")
+    when 71..95
+      # lower-case constructor from Resonad::Mixin
+      success("ill omens abound")
+    else
+      # direct access to classes from Resonad::Mixin
+      Failure.new("MALFUNCTION")
+    end
+  end
+end
+```
+
+Note that `Resonad::Mixin` provides private methods, and private constants, so
+you can't do this:
+
+```ruby
+RobotFortuneTeller.new.Success(5)
+  #=> NoMethodError: private method `Success' called for #<RobotFortuneTeller:0x00007fe7fc0ff0c8>
+
+RobotFortuneTeller::Success
+  #=> NameError: private constant Resonad::Mixin::Success referenced
+```
+
+If you want the methods/constants to be public, then use `Resonad::PublicMixin`
+instead.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at:
+https://github.com/tomdalling/resonad
+
+I'm open to PRs that make the gem more convenient, or that makes calling code
+read better.
+
+Make sure your PR has full test coverage.
+

data/lib/resonad.rb

@@ -2,28 +2,17 @@ class Resonad
   class NonExistentError < StandardError; end
   class NonExistentValue < StandardError; end
 
-  module Mixin
-    def Success(value=nil)
+  class Success < Resonad
+    attr_accessor :value
+
+    def self.[](value = nil)
       if nil == value
         NIL_SUCCESS
       else
-        Success.new(value)
+        new(value)
       end
     end
 
-    def Failure(error=nil)
-      if nil == error
-        NIL_FAILURE
-      else
-        Failure.new(error)
-      end
-    end
-  end
-  extend Mixin
-
-  class Success < Resonad
-    attr_accessor :value
-
     def initialize(value)
       @value = value
       freeze
@@ -66,11 +55,27 @@ class Resonad
     def flat_map_error
       self
     end
+
+    def deconstruct
+      [:success, value]
+    end
+
+    def deconstruct_keys(_)
+      { value: value }
+    end
   end
 
   class Failure < Resonad
     attr_accessor :error
 
+    def self.[](error = nil)
+      if nil == error
+        NIL_FAILURE
+      else
+        new(error)
+      end
+    end
+
     def initialize(error)
       @error = error
       freeze
@@ -113,8 +118,35 @@ class Resonad
     def flat_map_error
       yield error
     end
+
+    def deconstruct
+      [:failure, error]
+    end
+
+    def deconstruct_keys(_)
+      { error: error }
+    end
   end
 
+  module PublicMixin
+    Success = ::Resonad::Success
+    Failure = ::Resonad::Failure
+
+    def Success(*args); Success[*args]; end
+    def success(*args); Success[*args]; end
+    def Failure(*args); Failure[*args]; end
+    def failure(*args); Failure[*args]; end
+  end
+
+  Mixin = PublicMixin.dup.tap do |mixin|
+    mixin.module_eval do
+      private(*public_instance_methods)
+      private_constant(*constants)
+    end
+  end
+
+  extend PublicMixin
+
   def self.rescuing_from(*exception_classes)
     Success(yield)
   rescue Exception => e
@@ -143,6 +175,11 @@ class Resonad
   def failed?; failure?; end
   def bad?; failure?; end
 
+  def map(&block)
+    raise NotImplementedError, "should be implemented in subclass"
+  end
+  def map_value(&block); map(&block); end
+
   def flat_map
     raise NotImplementedError, "should be implemented in subclass"
   end
@@ -152,6 +189,31 @@ class Resonad
     raise NotImplementedError, "should be implemented in subclass"
   end
   def or_else(&block); flat_map_error(&block); end
+  def otherwise(&block); flat_map_error(&block); end
+
+  def on_success(&block)
+    raise NotImplementedError, "should be implemented in subclass"
+  end
+  def if_success(&block); on_success(&block); end
+  def when_success(&block); on_success(&block); end
+  def on_ok(&block); on_success(&block); end
+  def if_ok(&block); on_success(&block); end
+  def when_ok(&block); on_success(&block); end
+  def on_successful(&block); on_success(&block); end
+  def if_successful(&block); on_success(&block); end
+  def when_successful(&block); on_success(&block); end
+
+  def on_failure(&block)
+    raise NotImplementedError, "should be implemented in subclass"
+  end
+  def if_failure(&block); on_failure(&block); end
+  def when_failure(&block); on_failure(&block); end
+  def on_bad(&block); on_failure(&block); end
+  def if_bad(&block); on_failure(&block); end
+  def when_bad(&block); on_failure(&block); end
+  def on_failed(&block); on_failure(&block); end
+  def if_failed(&block); on_failure(&block); end
+  def when_failed(&block); on_failure(&block); end
 
   NIL_SUCCESS = Success.new(nil)
   NIL_FAILURE = Failure.new(nil)

data/lib/resonad/version.rb

@@ -1,3 +1,3 @@
 class Resonad
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/resonad.gemspec

@@ -20,8 +20,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.14"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler", ">= 1.15"
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "gem-release", "~> 0.7"
+  spec.add_development_dependency "gem-release", "~> 2.1"
 end

metadata

@@ -1,43 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: resonad
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Tom Dalling
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-22 00:00:00.000000000 Z
+date: 2020-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.14'
+        version: '1.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.14'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '1.15'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '2.1'
 description: Objects that represent success or failure
 email:
 - tom@tomdalling.com
@@ -75,12 +61,13 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".ruby-version"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
 - bin/console
 - bin/setup
 - lib/resonad.rb
@@ -106,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: Objects that represent success or failure

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec