to-result 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 842070fb5be7a4388055318b3956091d4869885c76d745c0dd01ba87cde415e5
-  data.tar.gz: 0a7c4e93685409f3f96479df8482255e501a88db53523c55d2f5f171255f58a3
+  metadata.gz: bc8202a00d4cc8938cac602f09b0a9b0694a29421bedb0c71be82f94fad66e89
+  data.tar.gz: 783334b0487c880174639c699eb61fc6eacd695086a5c5b9b531947bd1645b30
 SHA512:
-  metadata.gz: c16327c7a1420c8c1b711d98ffd59de246a3221c98dd6a3bae2cf3650c731c558ccbb02effccdd25d6f9f99e0097d030d751cf8c1dac40569b97dd95b4845817
-  data.tar.gz: 23d78aac99bc431eb9b47aafe9aca8dde5b95615766a60305ce016638a3c26e74ac632f5c19bf9c913a5ce70a2ba14d187dc3aea99f8c5876155db4ad9cbed34
+  metadata.gz: 4e2b40217e547f2cabbcc84847f1f257676863997c088f4e2c43416a608fd804b07bf7586e95d6ab60b8c70fa501b6cd297deb7d9ad7a86f0acade0977ef5f64
+  data.tar.gz: feceedd4425f782ee47637da08a69fbef6f54b226a5bd104e6a8f22ea219a9b4be1fd30ffac56e88df0ec1aa2212f4c2ea2994b81f51155f8d1dae8ff29fb41b

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## [0.1.0](https://github.com/a-chris/to-result/tree/0.1.0) (2022-10-28)
+
+- Explicit requires `dry-monads` >= 1.x, just for convenience
+
+BREAKING CHANGES:
+
+- The arrays of exceptions to catch is now received using the `only` argument key, e.g. `ToResult(only: [ArgumentError])`
+- Setting the global `on_error` with a non-callable object (an object that does not respond to `call`) will raise `TypeError`
+
+NEW FEATURES:
+
+- Added local `on_error` that can be used to override or run a one-time block when an error is catched
+  `ToResult(on_error: Proc { |e| puts e })`
+
+## [0.0.4](https://github.com/a-chris/to-result/tree/0.0.4) (2022-10-08)
+
+- Adds a global `configuration` object for ToResult
+- Adds `on_error` field in `configuration` to execute a block every time a error is catched
+
+[Full Changelog](https://github.com/a-chris/to-result/compare/0.0.3...0.0.4)
+
+## [0.0.3](https://github.com/a-chris/to-result/tree/0.0.3) (2022-10-08)
+
+- Fixed file name, `require 'to_result'` is not needed anymore to make this gem work.
+
+[Full Changelog](https://github.com/a-chris/to-result/compare/0.0.2...0.0.3)
+
+## [0.0.2](https://github.com/a-chris/to-result/tree/0.0.2) (2022-09-18)
+
+[Full Changelog](https://github.com/a-chris/to-result/compare/0.0.1...0.0.2)
+
+## [0.0.1](https://github.com/a-chris/to-result/tree/0.0.1) (2022-09-18)
+
+[Full Changelog](https://github.com/a-chris/to-result/compare/8dce552d6d07a2a145c45dbf7d05dbe6b0c5c578...0.0.1)
+
+\* _This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)_

data/Gemfile

@@ -5,7 +5,7 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in pulsarcli.gemspec
 gemspec
 
-gem 'dry-monads', '~> 1.4'
+gem 'dry-monads', '~> 1.5'
 
 gem 'byebug', '~> 11.1'
 

data/Gemfile.lock

@@ -1,27 +1,31 @@
 PATH
   remote: .
   specs:
-    to-result (0.0.3)
+    to-result (0.1.0)
+      dry-monads (~> 1.5)
 
 GEM
   remote: https://rubygems.org/
   specs:
     byebug (11.1.3)
     concurrent-ruby (1.1.10)
-    dry-core (0.8.1)
+    dry-core (0.9.1)
       concurrent-ruby (~> 1.0)
-    dry-monads (1.4.0)
+      zeitwerk (~> 2.6)
+    dry-monads (1.5.0)
       concurrent-ruby (~> 1.0)
-      dry-core (~> 0.7)
+      dry-core (~> 0.9, >= 0.9)
+      zeitwerk (~> 2.6)
     minitest (5.16.3)
     mocha (1.15.0)
+    zeitwerk (2.6.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   byebug (~> 11.1)
-  dry-monads (~> 1.4)
+  dry-monads (~> 1.5)
   minitest (~> 5.16)
   mocha (~> 1.15)
   to-result!

data/README.md

@@ -5,7 +5,7 @@ ToResult is a wrapper built over `dry-monads` to make the `Do Notation`, `Result
 
 ## Why I created ToResult
 
-`dry-monads` is full of edge cases that require to write boilerplate code everytime I want a method to return a `Success` or `Failure`, for example:
+`dry-monads` requires to write boilerplate code everytime we want a method to return a `Success` or `Failure`, for example:
 
 ```ruby
 def my_method
@@ -15,7 +15,7 @@ rescue StandardError => e
 end
 ```
 
-so I started using `Try`, that makes the code easier to read and faster to write:
+yes, we can use `Try` which makes the code easier to read and faster to write:
 ```ruby
 def my_method
   Try do
@@ -24,11 +24,11 @@ def my_method
 end
 ```
 
-but I feel like `to_result` is not really visible at the end of the code and if you forget to write it (as always happens to me) your application blows up.
+but I feel like `to_result` is not really visible at the end of the block and if you forget to write it (as always happens to me) your application blows up.
 
-But this is not the bigget problem, bear with me.
+But this is not the biggest problem, bear with me.
 
-One of the biggest problem is that we cannot use the `Do Notation` inside a `Try` block:
+One of the biggest problem is that we cannot use the **Do Notation** inside a `Try` block:
 ```ruby
 # this will return a Failure(Dry::Monads::Do::Halt)
 def my_method
@@ -50,7 +50,30 @@ rescue StandardError => e
 end
 ```
 
-because they will raise a `Dry::Monads::Do::Halt` exception and the original exception will be forever lost if we do not "unbox" the exception with `e.result`.
+because they will raise a `Dry::Monads::Do::Halt` exception and the original error will be forever lost if we do not "unbox" the exception with `e.result` like this:
+
+```ruby
+def my_method
+  yield Failure('error code')
+rescue Dry::Monads::Do::Halt => e
+  return e.result
+rescue StandardError => e
+  Failure(e)
+end
+```
+
+to be honest this is an implementation detail I don't want to care about while I'm writing my business logic and as far as I've seen this is really hard for junior developers to figure out what is happening with `Do::Halt`.
+
+With this gem, `to-result`, that piece of code can be written as:
+```ruby
+def my_method
+  ToResult do
+    yield Failure('error code')
+  end
+end
+```
+
+and it will return `Failure('error code')` without all the effort to think about `Do::Halt`. Moreover, you can keep using `ToResult` everytime you could have used `Try` or monads in general, so you have just **one way** to write monads in your code.
 
 ## Installation
 
@@ -114,19 +137,23 @@ ToResult { yield Failure('error code') }
 ToResult { yield Failure(StandardError.new('error code')) }
 # returns Failure(StandardError('error code'))
 
-ToResult([YourCustomError]) { yield Failure(YourCustomError.new('error code')) }
+ToResult(only: [YourCustomError]) { yield Failure(YourCustomError.new('error code')) }
 # returns Failure(YourCustomError('error code'))
 
-ToResult([ArgumentError]) { yield Failure(YourCustomError.new('error code')) }
+ToResult(only: [ArgumentError]) { yield Failure(YourCustomError.new('error code')) }
 # raises YourCustomError('error code')
 ```
 
+## Changelog
+
+[Changelog](CHANGELOG.md)
+
 ## Roadmap
 I'm already planning to implement some useful features:
 - [x] write more examples/documentation/tests
-- [ ] configurable error logging when an exception is catched inside `DoResult`
+- [x] configurable error logging when an exception is catched inside `DoResult`
 e.g. sending the log to Airbrake or whathever service you are using
-- [ ] transform/process the catched error
+- [x] transform/process the catched error => this can be handled with `alt_map` or other methods already available in `dry-monads`
 - [ ] any other suggestion would be appreciated 😁
 
 ## Authors

data/lib/to-result.rb

@@ -3,9 +3,17 @@ require 'dry/monads'
 module ToResultMixin
   include Dry::Monads[:do, :result, :try]
 
-  Configuration = Struct.new(:on_error)
+  class Configuration
+    attr_accessor :on_error
 
-  @@configuration = Configuration.new(on_error: nil)
+    def on_error=(value)
+      raise TypeError.new('on_error is expected to be a callable object') unless value.respond_to?(:call)
+
+      @on_error = value
+    end
+  end
+
+  @@configuration = Configuration.new
 
   #
   # Allow to override the @@configuration fields
@@ -17,27 +25,37 @@ module ToResultMixin
   #
   # ToResult executes a block of code and returns Success or Failure.
   # All exceptions inherited from StandardError are catched and
-  # converted to Failure or you can pass a list of exceptions to catch.
+  # converted to Failure or you can pass a custom list of exceptions
+  # to catch using `only`.
+  #
+  # Passing the `on_error` block overrides the global on_error defined in to the Configuration,
+  # it is possible to pass `nil` to not execute a block when an error is catched.
   #
-  # @param [Array<Class>] exceptions
-  # @param [Proc] &f
+  #
+  # @param [Array<Class>] only is the array of Exception to catch
+  # @param [Proc|Method] on_error is the function to be executed in case of error. It overrides the global on_error.
+  # @param [Proc] &f is the block to run
   #
   # @return [Success]
   # @return [Failure]
   #
-  def ToResult(exceptions = [StandardError], &f)
-    Try.run(
-      exceptions,
+  def ToResult(only: [StandardError], **args, &f)
+    # on_error included in args so we can distinguish when it's passed but it's nil
+    # from when it's not passed at all
+    on_error ||= args.key?(:on_error) ? args[:on_error] : @@configuration.on_error
+
+    f_wrapper =
       Proc.new do
         f.call
       rescue Dry::Monads::Do::Halt => e
         error = e.result
-        @@configuration.on_error.call(error) if @@configuration.on_error.respond_to?(:call)
+        on_error.call(error) if on_error.respond_to?(:call)
         return error
-      rescue *exceptions => e
-        @@configuration.on_error.call(e) if @@configuration.on_error.respond_to?(:call)
+      rescue *only => e
+        on_error.call(e) if on_error.respond_to?(:call)
         raise e
       end
-    ).to_result
+
+    Try.run(only, f_wrapper).to_result
   end
 end

data/tests/support/fake_logger.rb

@@ -2,4 +2,8 @@ class FakeLogger
   def self.log_error
     true
   end
+
+  def self.return_error(e)
+    e
+  end
 end

data/tests/to_result_test.rb

@@ -36,12 +36,12 @@ class ToResultTest < Minitest::Test
 
   def test_exception_included_in_exceptions_list
     expected = ArgumentError.new(@value)
-    assert ToResult([ArgumentError]) { raise expected } == Failure(expected)
+    assert ToResult(only: [ArgumentError]) { raise expected } == Failure(expected)
   end
 
   def test_exception_not_included_in_exceptions_list
     expected = NameError.new(@value)
-    assert_raises(NameError) { ToResult([ArgumentError]) { raise expected } }
+    assert_raises(NameError) { ToResult(only: [ArgumentError]) { raise expected } }
   end
 
   def test_yield_failure
@@ -56,13 +56,58 @@ class ToResultTest < Minitest::Test
     assert ToResult { yield expected } == expected
   end
 
-  def test_on_error
-    FakeLogger.expects(:log_error).once
+  def test_invalid_global_on_error
+    assert_raises(TypeError) do
+      ToResultMixin.configure { |c| c.on_error = 'invalid value' }
+    end
+  end
 
-    ToResultMixin.configure do |c|
-      c.on_error = Proc.new { FakeLogger.log_error }
+  def setup_global_on_error
+    # creating a clean room just for testing purpose
+    clean_room = Class.new(Object)
+    clean_room.new.instance_eval do
+      ToResultMixin.configure do |c|
+        c.on_error = Proc.new { FakeLogger.log_error }
+      end
     end
+  end
+
+  def test_global_on_error
+    setup_global_on_error
+
+    FakeLogger.expects(:log_error).once
+
+    expected = StandardError.new(@value)
+    assert ToResult { raise expected } == Failure(expected)
+  end
+
+  def test_local_on_error_overrides_global
+    setup_global_on_error
+
+    FakeLogger.expects(:log_error).once
+
+    local_on_error = Proc.new { FakeLogger.log_error }
+
+    expected = StandardError.new(@value)
+    assert ToResult(on_error: local_on_error) { raise expected } == Failure(expected)
+  end
+
+  def test_local_on_error_overrides_global_nil
+    setup_global_on_error
+
+    FakeLogger.expects(:log_error).never
 
-    ToResult { raise StandardError.new(@value) }
+    local_on_error = nil
+
+    expected = StandardError.new(@value)
+    assert ToResult(on_error: local_on_error) { raise expected } == Failure(expected)
+  end
+
+  def test_local_on_error_without_global
+    local_on_error = Proc.new { |e| FakeLogger.return_error(e) }
+
+    expected = StandardError.new(@value)
+    FakeLogger.expects(:return_error).with(expected).returns(expected).once
+    assert ToResult(on_error: local_on_error) { raise expected } == Failure(expected)
   end
 end

data/to-result.gemspec

@@ -5,7 +5,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |s|
   s.name        = 'to-result'
-  s.version     = '0.0.3'
+  s.version     = '0.1.0'
   s.summary     = 'A wrapper over dry-monads to offer a handy and consistent way to implement the Railway pattern.'
   s.description = 'A wrapper over dry-monads to offer a handy and consistent way to implement the Railway pattern.'
   s.authors     = ['Christian Toscano']
@@ -14,4 +14,6 @@ Gem::Specification.new do |s|
 
   s.require_paths = ['lib']
   s.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR).reject { |f| (f == '.gitignore') || f =~ /^examples/ }
+
+  s.add_dependency 'dry-monads', '~> 1.5'
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: to-result
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Christian Toscano
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-08 00:00:00.000000000 Z
-dependencies: []
+date: 2022-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 description: A wrapper over dry-monads to offer a handy and consistent way to implement
   the Railway pattern.
 email:
@@ -17,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE