f_service 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb3dfcc7d2f09fe4bd1cabca95a9520b06badf64e1d8fd7a238e0b904cdbbfe9
-  data.tar.gz: 4f71a8ecfb48c4b928b7240d63a63469a36f46635b081f221d064b0603d73be7
+  metadata.gz: 4997e65a2e3054de3de7a252a3e85143d41701f44046982ffc583c486755aa1d
+  data.tar.gz: ea5212762e5529ec315dac3437d29ac75a5c20058d30fdc382fe31b6f18288a6
 SHA512:
-  metadata.gz: 1e3378dc3e210fd41aa994270792eb5a2dbf003f351964d81e08c4505404bc90b765fd33c4d49d39893a83d64dded6d1a5efa72bc4699ec23d7cd6273535e22d
-  data.tar.gz: 175330f3f2fbccdcc9b74f93b69ffa0a4002699139b63d19208da97327722346b154f83d46bde3f71bf23016ef23065727cb5c876fb45ed076375652da70e5b7
+  metadata.gz: f3c51bf4006bb0b037361690fabb7e0af7895b393394561ed9a784d89ffe063bd48e573406fbee6675e5d3ef5f9ca3f9085240c6855ece5a7a50259dd6264e98
+  data.tar.gz: 7af0dfcf8f92fb8ac39b43efc044c5f623c9c52084b0b1a9542a9d6f1902dbe7444eb5b3b00ec043302dfe9b6e78eb879bc1cb335c2e078930bb15c49a9fe176

data/.github/.dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "09:00"
+  open-pull-requests-limit: 10

data/.github/workflows/tests-and-linter.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [2.5, 2.6, 2.7, '3.0']
+        ruby: [3.0, 3.1, 3.2, 3.3]
 
     steps:
       - uses: actions/checkout@v2

data/.rubocop.yml

@@ -2,6 +2,7 @@ require:
   - rubocop-rspec
 
 AllCops:
+  TargetRubyVersion: 3.0.0
   NewCops: enable
 
 Layout/LineLength:
@@ -17,3 +18,21 @@ Style/DocumentationMethod:
 Naming/MethodName:
   Exclude:
     - lib/f_service/base.rb
+
+RSpec/ContextWording:
+  Prefixes:
+    - and
+    - but
+    - when
+    - with
+    - without
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/NestedGroups:
+  Enabled: false
+
+##### RUBYGEMS #####
+Gemspec/RequireMFA:
+  Enabled: false

data/CHANGELOG.md

@@ -10,9 +10,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- ### Removed -->
 ---
 
+## 0.3.0
+### Added
+ - Drop Support to Ruby 2.6 and 2.7
+ - Add Support to Ruby 3.2 and 3.3
+ - Changed and_error to use a matcher instead of equality comparation #51
+
+## 0.3.0
+### Added
+- Added Rspec Helper `#mock_service` #41;
+- Added Rspec Matcher `#have_succeed_with` and `#have_failed_with` #41;
+- Added `Success()`, `Failure()`, `Check()`, `Try()` now can be multipe types #41;
+- Changed Depreacate `Result#type` method #41;
+- Changed Deprecate method `#then` for Success and Failure classes #40
+- Added RSpec support for mock and match results #35
+- Deprecate method `#then` for Success and Failure classes #40;
+- Removed deprecated method `#on` #33
+- Changed Capture just one callback per result #30;
+
 ## 0.2.0
 ### Added
-- Add `and_catch` as alias for `then` (partially fix [#23](https://github.com/Fretadao/f_service/issues/23)).
+- Add `and_then` as alias for `then` (partially fix [#23](https://github.com/Fretadao/f_service/issues/23)).
 - Add `catch` to `Failure` and `Success`. It acts as an inverted `then` and has a `or_else` alias.
 - Add support to custom `data` property to be passed when calling `Base#Check`.
 - Add support to multiple type checks on `Result#on_success` and `Result#on_failure` hooks.

data/Gemfile

@@ -6,8 +6,10 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'pry'
+  gem 'pry-nav'
   gem 'rake', '~> 13.0.0'
-  gem 'rubocop', '~> 0.82.0', require: false
+  gem 'rubocop', '~> 1.60.2', require: false
   gem 'rubocop-rspec', require: false
 end
 

data/Gemfile.lock

@@ -1,32 +1,47 @@
 PATH
   remote: .
   specs:
-    f_service (0.2.0)
+    f_service (0.3.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.0)
-    backport (1.1.2)
-    benchmark (0.1.0)
+    ast (2.4.2)
+    backport (1.2.0)
+    benchmark (0.3.0)
+    coderay (1.1.3)
     diff-lcs (1.3)
     docile (1.3.5)
     e2mmap (0.1.0)
-    jaro_winkler (1.5.4)
-    maruku (0.7.3)
-    mini_portile2 (2.5.0)
-    nokogiri (1.11.1)
-      mini_portile2 (~> 2.5.0)
+    jaro_winkler (1.5.6)
+    json (2.7.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    language_server-protocol (3.17.0.3)
+    method_source (1.0.0)
+    mini_portile2 (2.8.6)
+    nokogiri (1.16.5)
+      mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    parallel (1.19.1)
-    parser (2.7.1.1)
-      ast (~> 2.4.0)
-    racc (1.5.2)
-    rainbow (3.0.0)
+    parallel (1.24.0)
+    parser (3.3.0.5)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-nav (1.0.0)
+      pry (>= 0.9.10, < 0.15)
+    racc (1.7.3)
+    rainbow (3.1.1)
     rake (13.0.1)
-    reverse_markdown (1.4.0)
+    regexp_parser (2.9.0)
+    reverse_markdown (2.1.1)
       nokogiri
-    rexml (3.2.4)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -40,55 +55,68 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-support (3.9.2)
-    rubocop (0.82.0)
-      jaro_winkler (~> 1.5.1)
+    rubocop (1.60.2)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 2.7.0.1)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      rexml
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.30.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-rspec (1.38.1)
-      rubocop (>= 0.68.1)
-    ruby-progressbar (1.10.1)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    rubocop-capybara (2.20.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.25.1)
+      rubocop (~> 1.41)
+    rubocop-rspec (2.26.1)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+    ruby-progressbar (1.13.0)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.2)
-    solargraph (0.38.6)
+    solargraph (0.41.2)
       backport (~> 1.1)
       benchmark
       bundler (>= 1.17.2)
       e2mmap
       jaro_winkler (~> 1.5)
-      maruku (~> 0.7, >= 0.7.3)
-      nokogiri (~> 1.9, >= 1.9.1)
-      parser (~> 2.3)
-      reverse_markdown (~> 1.0, >= 1.0.5)
-      rubocop (~> 0.52)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      parser (~> 3.0)
+      reverse_markdown (>= 1.0.5, < 3)
+      rubocop (>= 0.52)
       thor (~> 1.0)
       tilt (~> 2.0)
-      yard (~> 0.9)
-    thor (1.0.1)
-    tilt (2.0.10)
-    unicode-display_width (1.7.0)
-    yard (0.9.24)
+      yard (~> 0.9, >= 0.9.24)
+    strscan (3.1.0)
+    thor (1.3.0)
+    tilt (2.3.0)
+    unicode-display_width (2.5.0)
+    yard (0.9.36)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 2.0)
   f_service!
+  pry
+  pry-nav
   rake (~> 13.0.0)
   rspec (~> 3.0)
-  rubocop (~> 0.82.0)
+  rubocop (~> 1.60.2)
   rubocop-rspec
   simplecov
   solargraph
   yard
 
 BUNDLED WITH
-   2.1.4
+   2.2.32

data/README.md

@@ -58,17 +58,17 @@ end
 
 The next step is writing the `#run` method, which is where the work should be done.
 Use the methods `#Success` and `#Failure` to handle your return values.
-You can optionally specify a type and a value for your result.
+You can optionally specify a list of types which represents that result and a value for your result.
 
 ```ruby
 class User::Create < FService::Base
   # ...
   def run
-    return Failure(:no_name) if @name.nil?
+    return Failure(:no_name, :invalid_attribute) if @name.nil?
 
     user = UserRepository.create(name: @name)
-    if user.valid?
-      Success(:created, data: user)
+    if user.save
+      Success(:success, :created, data: user)
     else
       Failure(:creation_failed, data: user.errors)
     end
@@ -128,6 +128,29 @@ class UsersController < BaseController
 end
 ```
 
+Or else it is possible to specify an unhandled option to ensure that the callback will process that message anyway the
+error.
+
+```ruby
+class UsersController < BaseController
+  def create
+    User::Create.(user_params)
+                .on_success(unhandled: true) { |value| return json_success(value) }
+                .on_failure(unhandled: true) { |error| return json_error(error) }
+  end
+end
+```
+
+```ruby
+class UsersController < BaseController
+  def create
+    User::Create.(user_params)
+                .on_success { |value| return json_success(value) }
+                .on_failure { |error| return json_error(error) }
+  end
+end
+```
+
 > You can ignore any of the callbacks, if you want to.
 
 Going further, you can match the Result type, in case you want to handle them differently:
@@ -166,6 +189,15 @@ class UsersController < BaseController
 end
 ```
 
+### Type precedence
+
+FService matches the service's types from left to right, from more specific to more generic.
+For example, the following result `Failure(:unprocessable_entity, :client_error, :http_response)` will match in the following order:
+1. `:unprocessable_entity`;
+2. `:client_error`;
+3. `:http_response`;
+4. unmatched block;
+
 ### Chaining services
 
 Since all services return Results, you can chain service calls making a data pipeline.
@@ -206,10 +238,10 @@ You can use `Check` to converts a boolean to a Result, truthy values map to `Suc
 
 ```ruby
 Check(:math_works) { 1 < 2 }
-# => #<Success @value=true, @type=:math_works>
+# => #<Success @value=true, @types=[:math_works]>
 
 Check(:math_works) { 1 > 2 }
-# => #<Failure @error=false, @type=:math_works>
+# => #<Failure @error=false, @types=[:math_works]>
 ```
 
 `Try` transforms an exception into a `Failure` if some exception is raised for the given block. You can specify which exception class to watch for
@@ -228,10 +260,61 @@ class IHateEvenNumbers < FService::Base
 end
 
 IHateEvenNumbers.call
-# => #<Success @value=9, @type=:rand_int>
+# => #<Success @value=9, @types=[:rand_int]>
 
 IHateEvenNumbers.call
-# => #<Failure @error=#<RuntimeError: Yuck! It's a 4>, @type=:rand_int>
+# => #<Failure @error=#<RuntimeError: Yuck! It's a 4>, @types=[:rand_int]>
+```
+
+## Testing
+
+We provide some helpers and matchers to make ease to test code envolving Fservice services.
+
+To make available in the system, in the file 'spec/spec_helper.rb' or 'spec/rails_helper.rb'
+
+add the folowing require:
+
+```rb
+require 'f_service/rspec'
+```
+
+### Mocking a result
+
+```rb
+mock_service(Uer::Create)
+# => Mocks a successful result with all values nil
+
+mock_service(Uer::Create, result: :success)
+# => Mocks a successful result with all values nil
+
+mock_service(Uer::Create, result: :success, types: [:created, :success])
+# => Mocks a successful result with type created
+
+mock_service(Uer::Create, result: :success, types: :created, value: instance_spy(User))
+# => Mocks a successful result with type created and a value
+
+mock_service(Uer::Create, result: :failure)
+# => Mocs a failure with all nil values
+
+mock_service(User::Create, result: :failure, types: [:unprocessable_entity, :client_error])
+# => Mocs a failure with a failure type
+
+mock_service(User::Create, result: :failure, types: [:unprocessable_entity, :client_error], value: { name: ["can't be blank"] })
+# => Mocs a failure with a failure type and an error value
+```
+
+### Matching a result
+
+```rb
+expect(User::Create.(name: 'Joe')).to have_succeed_with(:created)
+
+expect(User::Create.(name: 'Joe')).to have_succeed_with(:created).and_value(an_instance_of(User))
+
+expect(User::Create.(name: nil)).to have_failed_with(:invalid_attributes)
+
+expect(User::Create.(name: nil)).to have_failed_with(:invalid_attributes).and_error({ name: ["can't be blank"] })
+
+expect(User::Create.(name: nil)).to have_failed_with(:invalid_attributes).and_error(a_hash_including(name: ["can't be blank"]))
 ```
 
 ## API Docs

data/f_service.gemspec

@@ -7,8 +7,8 @@ require 'f_service/version'
 Gem::Specification.new do |spec|
   spec.name    = 'f_service'
   spec.version = FService::VERSION
-  spec.authors = ['Matheus Richard']
-  spec.email   = ['matheusrichardt@gmail.com']
+  spec.authors = ['Fretadao Tech Team']
+  spec.email = ['tech@fretadao.com.br']
 
   spec.summary     = 'A small, monad-based service class'
   spec.description = <<-DESCRIPTION
@@ -19,6 +19,7 @@ Gem::Specification.new do |spec|
 
   spec.homepage = 'https://github.com/Fretadao/f_service'
   spec.license  = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
 
   spec.metadata['homepage_uri']    = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/Fretadao/f_service'
@@ -33,6 +34,4 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
-
-  spec.add_development_dependency 'bundler', '~> 2.0'
 end

data/lib/f_service/base.rb

@@ -101,69 +101,70 @@ module FService
     def success(data = nil)
       FService.deprecate!(
         name: "#{self.class}##{__method__}",
-        alternative: '#Success'
+        alternative: '#Success',
+        from: caller[0]
       )
 
       Result::Success.new(data)
     end
 
     # Returns a successful result.
-    # You can optionally specify a type and a value for your result.
+    # You can optionally specify a list of types and a value for your result.
     # You'll probably want to return this inside {#run}.
     #
     #
     # @example
     #   def run
     #     Success()
-    #     # => #<Success @value=nil, @type=nil>
+    #     # => #<Success @value=nil, @types=[]>
     #
     #     Success(:ok)
-    #     # => #<Success @value=nil, @type=:ok>
+    #     # => #<Success @value=nil, @types=[:ok]>
     #
     #     Success(data: 10)
-    #     # => #<Success @value=10, @type=nil>
+    #     # => #<Success @value=10, @types=[]>
     #
     #     Success(:ok, data: 10)
-    #     # => #<Success @value=10, @type=:ok>
+    #     # => #<Success @value=10, @types=[:ok]>
     #   end
     #
-    # @param type the Result type
+    # @param types the Result types
     # @param data the result value
     # @return [Result::Success] a successful result
-    def Success(type = nil, data: nil)
-      Result::Success.new(data, type)
+    def Success(*types, data: nil)
+      Result::Success.new(data, types)
     end
 
     # Returns a failed result.
-    # You can optionally specify a type and a value for your result.
+    # You can optionally specify types and a value for your result.
     # You'll probably want to return this inside {#run}.
     #
     #
     # @example
     #   def run
     #     Failure()
-    #     # => #<Failure @error=nil, @type=nil>
+    #     # => #<Failure @error=nil, @types=[]>
     #
     #     Failure(:not_a_number)
-    #     # => #<Failure @error=nil, @type=:not_a_number>
+    #     # => #<Failure @error=nil, @types=[:not_a_number]>
     #
     #     Failure(data: "10")
-    #     # => #<Failure @error="10", @type=nil>
+    #     # => #<Failure @error="10", @types=[]>
     #
     #     Failure(:not_a_number, data: "10")
-    #     # => #<Failure @error="10", @type=:not_a_number>
+    #     # => #<Failure @error="10", @types=[:not_a_number]>
     #   end
     #
-    # @param type the Result type
+    # @param types the Result types
     # @param data the result value
     # @return [Result::Failure] a failed result
-    def Failure(type = nil, data: nil)
-      Result::Failure.new(data, type)
+    def Failure(*types, data: nil)
+      Result::Failure.new(data, types)
     end
 
     # Converts a boolean to a Result.
     # Truthy values map to Success, and falsey values map to Failures.
-    # You can optionally provide a type for the result.
+    # You can optionally provide a types for the result.
     # The result value defaults as the evaluated value of the given block.
     # If you want another value you can pass it through the `data:` argument.
     #
@@ -171,34 +172,34 @@ module FService
     #   class CheckMathWorks < FService::Base
     #     def run
     #       Check(:math_works) { 1 < 2 }
-    #       # => #<Success @value=true, @type=:math_works>
+    #       # => #<Success @value=true, @types=[:math_works]>
     #
     #       Check(:math_works) { 1 > 2 }
-    #       # => #<Failure @error=false, @type=:math_works>
+    #       # => #<Failure @error=false, @types=[:math_works]>
     #
     #       Check(:math_works, data: 1 + 2) { 1 > 2 }
-    #       # => #<Failure @type=:math_works, @error=3>
+    #       # => #<Failure @types=:math_works, @error=3>
     #     end
     #
     #       Check(:math_works, data: 1 + 2) { 1 < 2 }
-    #       # => #<Success @type=:math_works, @value=3>
+    #       # => #<Success @types=[:math_works], @value=3>
     #     end
     #   end
     #
-    # @param type the Result type
+    # @param types the Result types
     # @return [Result::Success, Result::Failure] a Result from the boolean expression
-    def Check(type = nil, data: nil)
+    def Check(*types, data: nil)
       res = yield
 
       final_data = data || res
 
-      res ? Success(type, data: final_data) : Failure(type, data: final_data)
+      res ? Success(*types, data: final_data) : Failure(*types, data: final_data)
     end
 
     # If the given block raises an exception, it wraps it in a Failure.
     # Otherwise, maps the block value in a Success object.
     # You can specify which exceptions to watch for.
-    # It's possible to provide a type for the result too.
+    # It's possible to provide a types for the result too.
     #
     # @example
     #   class IHateEvenNumbers < FService::Base
@@ -213,20 +214,20 @@ module FService
     #   end
     #
     #   IHateEvenNumbers.call
-    #   # => #<Success @value=9, @type=:rand_int>
+    #   # => #<Success @value=9, @types=[:rand_int]>
     #
     #   IHateEvenNumbers.call
-    #   # => #<Failure @error=#<RuntimeError: Yuck! It's a 4>, @type=:rand_int>
+    #   # => #<Failure @error=#<RuntimeError: Yuck! It's a 4>, @types=[:rand_int]>
     #
-    # @param type the Result type
+    # @param types the Result types
     # @param catch the exception list to catch
     # @return [Result::Success, Result::Failure] a result from the boolean expression
-    def Try(type = nil, catch: StandardError)
+    def Try(*types, catch: StandardError)
       res = yield
 
-      Success(type, data: res)
+      Success(*types, data: res)
     rescue *catch => e
-      Failure(type, data: e)
+      Failure(*types, data: e)
     end
 
     # Returns a failed operation.
@@ -250,7 +251,8 @@ module FService
     def failure(data = nil)
       FService.deprecate!(
         name: "#{self.class}##{__method__}",
-        alternative: '#Failure'
+        alternative: '#Failure',
+        from: caller[0]
       )
 
       Result::Failure.new(data)
@@ -283,7 +285,8 @@ module FService
     def result(condition, data = nil)
       FService.deprecate!(
         name: "#{self.class}##{__method__}",
-        alternative: '#Check'
+        alternative: '#Check',
+        from: caller[0]
       )
 
       condition ? success(data) : failure(data)

data/lib/f_service/result/base.rb

@@ -7,24 +7,38 @@ module FService
     #
     # @abstract
     class Base
-      %i[initialize then successful? failed? value value! error].each do |method_name|
+      attr_reader :types
+
+      %i[and_then successful? failed? value value! error].each do |method_name|
         define_method(method_name) do |*_args|
           raise NotImplementedError, "called #{method_name} on class Result::Base"
         end
       end
 
-      # "Pattern matching"-like method for results.
-      # It will run the success path if Result is a Success.
-      # Otherwise, it will run the failure path.
-      #
+      # You usually shouldn't call this directly. See {FService::Base#Failure} and {FService::Base#Success}.
+      def initialize(types = [])
+        @handled = false
+        @types = types
+        @matching_types = []
+      end
+
+      # Implements old attribute type. Its deprecated in favor of using types.
+      def type
+        FService.deprecate!(name: "#{self.class}##{__method__}", alternative: '#types', from: caller[0])
+
+        types.size == 1 ? types.first : Array(@matching_types).first
+      end
+
+      # This hook runs if the result is successful.
+      # Can receive one or more types to be checked before running the given block.
       #
       # @example
       #   class UsersController < BaseController
       #     def update
-      #       User::Update.(user: user).on(
-      #         success: ->(value) { return json_success(value) },
-      #         failure: ->(error) { return json_error(error) }
-      #       )
+      #       User::Update.(user: user)
+      #                   .on_success(:type, :type2) { return json_success({ status: :ok }) } # run only if type matches
+      #                   .on_success { |value| return json_success(value) }
+      #                   .on_failure { |error| return json_error(error) } # this won't run
       #     end
       #
       #     private
@@ -34,33 +48,13 @@ module FService
       #     end
       #   end
       #
-      # @param success [#call] a lambda (or anything that responds to #call) to run on success
-      # @param failure [#call] a lambda (or anything that responds to #call) to run on failure
-      # @deprecated Use {#on_success} and/or {#on_failure} instead.
-      # @api public
-      def on(success:, failure:)
-        FService.deprecate!(
-          name: "#{self.class}##{__method__}",
-          alternative: '#on_success and/or #on_failure'
-        )
-
-        if successful?
-          success.call(value)
-        else
-          failure.call(error)
-        end
-      end
-
-      # This hook runs if the result is successful.
-      # Can receive one or more types to be checked before running the given block.
-      #
       # @example
       #   class UsersController < BaseController
       #     def update
       #       User::Update.(user: user)
       #                   .on_success(:type, :type2) { return json_success({ status: :ok }) } # run only if type matches
-      #                   .on_success { |value| return json_success(value) }
-      #                   .on_failure { |error| return json_error(error) } # this won't run
+      #                   .on_success(unhandled: true) { |value| return json_success(value) }
+      #                   .on_failure(unhandled: true) { |error| return json_error(error) } # this won't run
       #     end
       #
       #     private
@@ -74,8 +68,13 @@ module FService
       # @yieldparam type type of the failure object
       # @return [Success, Failure] the original Result object
       # @api public
-      def on_success(*target_types)
-        yield(*to_ary) if successful? && expected_type?(target_types)
+      def on_success(*target_types, unhandled: false)
+        if successful? && unhandled? && expected_type?(target_types, unhandled: unhandled)
+          match_types(target_types)
+          yield(*to_ary)
+          @handled = true
+          freeze
+        end
 
         self
       end
@@ -99,12 +98,33 @@ module FService
       #     end
       #   end
       #
+      # @example
+      #   class UsersController < BaseController
+      #     def update
+      #       User::Update.(user: user)
+      #                   .on_success(:unhandled: true) { |value| return json_success(value) } # this won't run
+      #                   .on_failure(:type, :type2) { |error| return json_error(error) } # runs only if type matches
+      #                   .on_failure(:unhandled: true) { |error| return json_error(error) }
+      #     end
+      #
+      #     private
+      #
+      #     def user
+      #       @user ||= User.find_by!(slug: params[:slug])
+      #     end
+      #   end
+      #
       # @yieldparam value value of the failure object
       # @yieldparam type type of the failure object
       # @return [Success, Failure] the original Result object
       # @api public
-      def on_failure(*target_types)
-        yield(*to_ary) if failed? && expected_type?(target_types)
+      def on_failure(*target_types, unhandled: false)
+        if failed? && unhandled? && expected_type?(target_types, unhandled: unhandled)
+          match_types(target_types)
+          yield(*to_ary)
+          @handled = true
+          freeze
+        end
 
         self
       end
@@ -115,13 +135,25 @@ module FService
       def to_ary
         data = successful? ? value : error
 
-        [data, type]
+        [data, @matching_types.first]
       end
 
       private
 
-      def expected_type?(target_types)
-        target_types.include?(type) || target_types.empty?
+      def handled?
+        @handled
+      end
+
+      def unhandled?
+        !handled?
+      end
+
+      def expected_type?(target_types, unhandled:)
+        target_types.empty? || unhandled || target_types.any? { |target_type| types.include?(target_type) }
+      end
+
+      def match_types(target_types)
+        @matching_types = target_types.empty? ? types : target_types & types
       end
     end
   end

data/lib/f_service/result/failure.rb

@@ -10,20 +10,19 @@ module FService
     #
     # @!attribute [r] error
     #   @return [Object] the provided error for the result
-    # @!attribute [r] type
-    #   @return [Object] the provided type for the result. Defaults to nil.
+    # @!attribute [r] types
+    #   @return [Object] the provided types for the result. Defaults to nil.
     # @api public
     class Failure < Result::Base
-      attr_reader :error, :type
+      attr_reader :error
 
       # Creates a failed operation.
       # You usually shouldn't call this directly. See {FService::Base#Failure}.
       #
       # @param error [Object] failure value.
-      def initialize(error, type = nil)
+      def initialize(error, types = [])
+        super(types)
         @error = error
-        @type = type
-        freeze
       end
 
       # Returns false.
@@ -110,7 +109,12 @@ module FService
       def and_then
         self
       end
-      alias then and_then
+
+      # See #and_then
+      def then
+        FService.deprecate!(name: "#{self.class}##{__method__}", alternative: '#and_then', from: caller[0])
+        and_then
+      end
 
       # Outputs a string representation of the object
       #

data/lib/f_service/result/success.rb

@@ -9,20 +9,19 @@ module FService
     #
     # @!attribute [r] value
     #   @return [Object] the provided value for the result
-    # @!attribute [r] type
-    #   @return [Object] the provided type for the result. Defaults to nil.
+    # @!attribute [r] types
+    #   @return [Object] the provided types for the result. Defaults to nil.
     # @api public
     class Success < Result::Base
-      attr_reader :value, :type
+      attr_reader :value
 
       # Creates a successful operation.
       # You usually shouldn't call this directly. See {FService::Base#Success}.
       #
       # @param value [Object] success value.
-      def initialize(value, type = nil)
+      def initialize(value, types = [])
+        super(types)
         @value = value
-        @type = type
-        freeze
       end
 
       # Returns true.
@@ -79,11 +78,17 @@ module FService
       #   end
       #
       # @yieldparam value pass {#value} to a block
-      # @yieldparam type pass {#type} to a block
+      # @yieldparam types pass {#types} to a block
       def and_then
         yield(*to_ary)
       end
-      alias then and_then
+
+      # See #and_then
+      def then(&block)
+        FService.deprecate!(name: "#{self.class}##{__method__}", alternative: '#and_then', from: caller[0])
+
+        and_then(&block)
+      end
 
       # Returns itself to the given block.
       # Use this to chain multiple actions or service calls (only valid when they return a Result).

data/lib/f_service/rspec/support/helpers/result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Methods to mock a FService result from a service call.
+module FServiceResultHelpers
+  # Create an Fservice result Success or Failure.
+  def f_service_result(result, value = nil, types = [])
+    if result == :success
+      FService::Result::Success.new(value, Array(types))
+    else
+      FService::Result::Failure.new(value, Array(types))
+    end
+  end
+
+  # Mock a Fservice service call returning a result.
+  def mock_service(service, result: :success, value: nil, type: :not_passed, types: [])
+    result_types = Array(types)
+
+    if type != :not_passed
+      alternative = "mock_service(..., types: [#{type.inspect}])"
+      name = 'mock_service'
+      FService.deprecate_argument_name(name: name, argument_name: :type, alternative: alternative, from: caller[0])
+      result_types = Array(type)
+    end
+
+    service_result = f_service_result(result, value, result_types)
+    allow(service).to receive(:call).and_return(service_result)
+  end
+end
+
+RSpec.configure do |config|
+  config.include FServiceResultHelpers
+end

data/lib/f_service/rspec/support/helpers.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/result'

data/lib/f_service/rspec/support/matchers/result.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+RSpec::Matchers.define :have_failed_with do |*expected_types|
+  match do |actual|
+    matched = actual.is_a?(FService::Result::Failure) && actual.types == expected_types
+
+    matched &&= values_match?(@expected_error, actual.error) if defined?(@expected_error)
+
+    matched
+  end
+
+  chain :and_error do |expected_error|
+    @expected_error = expected_error
+  end
+
+  failure_message do |actual|
+    if actual.is_a?(FService::Result::Failure)
+      message = "expected failure's types '#{actual.types.inspect}' to be equal '#{expected_types.inspect}'"
+      if defined?(@expected_error)
+        has_description = @expected_error.respond_to?(:description)
+        message += " and error '#{actual.error.inspect}' to be "
+        message += has_description ? @expected_error.description : "equal '#{@expected_error.inspect}'"
+      end
+
+      message
+    else
+      "result '#{actual.inspect}' is not a Failure object"
+    end
+  end
+end
+
+RSpec::Matchers.define :have_succeed_with do |*expected_types|
+  match do |actual|
+    matched = actual.is_a?(FService::Result::Success) && actual.types == expected_types
+
+    matched &&= values_match?(@expected_value, actual.value) if defined?(@expected_value)
+
+    matched
+  end
+
+  chain :and_value do |expected_value|
+    @expected_value = expected_value
+  end
+
+  failure_message do |actual|
+    if actual.is_a?(FService::Result::Success)
+      message = "expected success's types '#{actual.types.inspect}' to be equal '#{expected_types.inspect}'"
+      if defined?(@expected_value)
+        has_description = @expected_value.respond_to?(:description)
+        message += " and value '#{actual.value.inspect}' to be "
+        message += has_description ? @expected_value.description : "equal '#{@expected_value.inspect}'"
+      end
+
+      message
+    else
+      "result '#{actual.inspect}' is not a Success object"
+    end
+  end
+end

data/lib/f_service/rspec/support/matchers.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'matchers/result'

data/lib/f_service/rspec/support.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'support/helpers'
+require_relative 'support/matchers'

data/lib/f_service/rspec.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'rspec/support'

data/lib/f_service/version.rb

@@ -2,5 +2,5 @@
 
 module FService
   # Current version of the gem
-  VERSION = '0.2.0'
+  VERSION = '0.3.1'
 end

data/lib/f_service.rb

@@ -9,9 +9,24 @@ module FService
   # Marks a method as deprecated
   #
   # @api private
-  def self.deprecate!(name:, alternative:)
-    warn "[DEPRECATED] #{name} is deprecated; " \
-         "use #{alternative} instead. " \
-         'It will be removed on the next release.'
+  def self.deprecate!(name:, alternative:, from: nil)
+    warn_message = ["\n[DEPRECATED] #{name} is deprecated; "]
+    warn_message << ["called from #{from}; "] unless from.nil?
+    warn_message << "use #{alternative} instead. "
+    warn_message << 'It will be removed on the next release.'
+
+    warn warn_message.join("\n")
+  end
+
+  # Marks an argument as deprecated
+  #
+  # @api private
+  def self.deprecate_argument_name(name:, argument_name:, alternative:, from: nil)
+    warn_message = ["\n[DEPRECATED] #{name} passing #{argument_name.inspect} is deprecated; "]
+    warn_message << ["called from #{from}; "] unless from.nil?
+    warn_message << "use #{alternative} instead. "
+    warn_message << 'It will be removed on the next release.'
+
+    warn warn_message.join("\n")
   end
 end

metadata

@@ -1,39 +1,26 @@
 --- !ruby/object:Gem::Specification
 name: f_service
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
-- Matheus Richard
+- Fretadao Tech Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-08 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
+date: 2024-07-18 00:00:00.000000000 Z
+dependencies: []
 description: |2
       FService is a small gem that provides a base class for your services (aka operations).
       The goal is to make services simpler, safer and more composable.
       It uses the Result monad for handling operations.
 email:
-- matheusrichardt@gmail.com
+- tech@fretadao.com.br
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/.dependabot.yml"
 - ".github/workflows/tests-and-linter.yml"
 - ".gitignore"
 - ".rubocop.yml"
@@ -52,6 +39,12 @@ files:
 - lib/f_service/result/base.rb
 - lib/f_service/result/failure.rb
 - lib/f_service/result/success.rb
+- lib/f_service/rspec.rb
+- lib/f_service/rspec/support.rb
+- lib/f_service/rspec/support/helpers.rb
+- lib/f_service/rspec/support/helpers/result.rb
+- lib/f_service/rspec/support/matchers.rb
+- lib/f_service/rspec/support/matchers/result.rb
 - lib/f_service/version.rb
 - logo.png
 homepage: https://github.com/Fretadao/f_service
@@ -70,14 +63,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.5.11
 signing_key: 
 specification_version: 4
 summary: A small, monad-based service class