to-result 0.0.4 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6db91d218609e2e2694dbc1ef6754d8e7c9951d27b8bb73ad521c856db4b9c75
-  data.tar.gz: 90f313139ed88c00b1c1877c4d8c94d3629d2d1662fee8315a64e65894ea81d4
+  metadata.gz: fc48c861de210a05cba164c61710457447f04b60b492ef15791ab7e5c28a3375
+  data.tar.gz: fb5802866e75958e710ec9a0be23584f8f737101ef8afd18c5b212a775539c1c
 SHA512:
-  metadata.gz: 4113a67772569963f5b8c4f9711168903aab0a16daddf4d00a2fb1ef288651989b46b64a07e8d4b97fd8ab83e3df716c9f2cd850fb8eecb350ae30ad68359fac
-  data.tar.gz: 0604e31717e86753ff06df3bda5754b11916bb27b5f5b8b0b22a3d2ad73a98d3269ba4f0da3ba81c73247161815118a22e580ac6f69538555788e091052fd335
+  metadata.gz: 60728e022ce553988082effc1ab86a3260cf399a464bddea06d936e6428bf54f0604a8b86638ee7932526a20d72b3c80bcc491f6d816d6d17bdd93326c11b2ce
+  data.tar.gz: 959d7af9b3eb1367269c6650ca9c9babedd8c3cfd6e36403d3d4f01b750219dc7781cec78e4bc2a4972ce34e230d157dbd17a8bee70b7c9cc24c407fb71f5bc3

data/CHANGELOG.md

@@ -1,4 +1,25 @@
 # Changelog
+
+## [0.1.1](https://github.com/a-chris/to-result/tree/0.1.1) (2023-08-16)
+
+HOTFIXES:
+
+- Always pass the error to the `on_error` callable object instead of mixed `error/Failure(error)`
+
+## [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
@@ -20,6 +41,4 @@
 
 [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)*
+\* _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.4)
+    to-result (0.1.1)
+      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

@@ -1,11 +1,11 @@
 
 # ToResult
 
-ToResult is a wrapper built over `dry-monads` to make the `Do Notation`, `Result` and `Try` concepts more handy and consistent to use, in particular to implement the **Railway Pattern**.
+ToResult is a wrapper built over `dry-monads` to make the `Do Notation`, `Result` and `Try` concepts more handy and consistent to use, especially to implement the **Railway Pattern**.
 
 ## 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
 
@@ -97,7 +120,7 @@ class MyClass
 end
 ```
 
-now you can always use `ToResult` all the time you wanted to use `Success`, `Failure` or `Try` but with a more convenient interface and consistent behaviour.
+now you can always use `ToResult` all the time you wanted to use `Try` or return `Success/Failure` but with a more convenient interface and consistent behaviour, my goal is to have a solution that can be used for every use-case.
 
 Look at this:
 
@@ -114,20 +137,48 @@ 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')
 ```
 
+## Local and global callback on errors
+to-result gives you the possibility to define a callback to be called when an error is raised inside the `ToResult` block, this is a handy place to log errors.
+
+You can define a global callback, usually defined into an initializer:
+
+```ruby
+# initializers/to_result.rb
+
+ToResultMixin.configure do |c|
+  c.on_error = Proc.new { |e| Logger.log_error(e) }
+end
+```
+
+or a local callback:
+
+```ruby
+ToResult(on_error: proc { |e| Logger.log_error(e) }) do
+  yield Failure(StandardError.new('error code'))
+end
+```
+
+you can even use both at the same time but keep in mind that **local callback overrides the global one**.
+
+
+## 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
-- [ ] any other suggestion would be appreciated 😁
+- [x] transform/process the catched error => this can be handled with `alt_map` or other methods already available in `dry-monads`
+- [ ] any type of suggestion is appreciated 😁
 
 ## Authors
 

data/lib/to-result.rb

@@ -5,6 +5,12 @@ module ToResultMixin
 
   class Configuration
     attr_accessor :on_error
+
+    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
@@ -19,27 +25,38 @@ 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)
-        return error
-      rescue *exceptions => e
-        @@configuration.on_error.call(e) if @@configuration.on_error.respond_to?(:call)
+        failure = error = e.result
+        error = error.failure if error.respond_to?(:failure)
+        on_error.call(error) if on_error.respond_to?(:call)
+        return failure
+      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

@@ -1,5 +1,9 @@
 class FakeLogger
-  def self.log_error
-    true
+  def self.log_error(e)
+    e
+  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,18 +56,59 @@ 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
 
+  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 }
+        c.on_error = Proc.new { |e| FakeLogger.log_error(e) }
       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
+
+    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) { yield Failure(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.4'
+  s.version     = '0.1.1'
   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.4
+  version: 0.1.1
 platform: ruby
 authors:
 - Christian Toscano
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-08 00:00:00.000000000 Z
-dependencies: []
+date: 2023-08-16 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:
@@ -46,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: A wrapper over dry-monads to offer a handy and consistent way to implement