f_service 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb3dfcc7d2f09fe4bd1cabca95a9520b06badf64e1d8fd7a238e0b904cdbbfe9
-  data.tar.gz: 4f71a8ecfb48c4b928b7240d63a63469a36f46635b081f221d064b0603d73be7
+  metadata.gz: 6cb29d87cf5c970b2b185ed2c3da41020f40122e2d0857af068302fb32e55400
+  data.tar.gz: 27a89660bb6d1e65d537f5d6617cc8175f600ab71efca79f65875a1b6adf0c97
 SHA512:
-  metadata.gz: 1e3378dc3e210fd41aa994270792eb5a2dbf003f351964d81e08c4505404bc90b765fd33c4d49d39893a83d64dded6d1a5efa72bc4699ec23d7cd6273535e22d
-  data.tar.gz: 175330f3f2fbccdcc9b74f93b69ffa0a4002699139b63d19208da97327722346b154f83d46bde3f71bf23016ef23065727cb5c876fb45ed076375652da70e5b7
+  metadata.gz: 2b444953aee676163a2b076d814b3cc801b0808a30660c4edd2f19172754d58c41a7fcb3129a52cf95c1a0fdb8546419a55a8101b6882459673cd647d520f660
+  data.tar.gz: 0e2f10e1ad6cf4ba7ba2375b2302661429721b7bf4023afcb1559909205eb7e8f013efbb3da07c4b7926b2e967592c31a6c930ca6d6e69b195bba97342407b69

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: [2.6, 2.7, 3.0, 3.1]
 
     steps:
       - uses: actions/checkout@v2

data/.rubocop.yml

@@ -17,3 +17,17 @@ 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

data/CHANGELOG.md

@@ -10,9 +10,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- ### Removed -->
 ---
 
+## 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,6 +6,8 @@ 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-rspec', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    f_service (0.2.0)
+    f_service (0.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -9,24 +9,31 @@ GEM
     ast (2.4.0)
     backport (1.1.2)
     benchmark (0.1.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)
+    method_source (1.0.0)
+    mini_portile2 (2.8.1)
+    nokogiri (1.14.3)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     parallel (1.19.1)
     parser (2.7.1.1)
       ast (~> 2.4.0)
-    racc (1.5.2)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-nav (1.0.0)
+      pry (>= 0.9.10, < 0.15)
+    racc (1.6.2)
     rainbow (3.0.0)
     rake (13.0.1)
     reverse_markdown (1.4.0)
       nokogiri
-    rexml (3.2.4)
+    rexml (3.2.5)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -82,6 +89,8 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.0)
   f_service!
+  pry
+  pry-nav
   rake (~> 13.0.0)
   rspec (~> 3.0)
   rubocop (~> 0.82.0)
@@ -91,4 +100,4 @@ DEPENDENCIES
   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,12 @@ class UsersController < BaseController
 end
 ```
 
+### Types precedence
+
+FService matches types from left to right, from more specific to more generic.
+Example (:unprocessable_entity, :client_error, :http_response)
+Then, result will match first :unprocessable_entity, after :client_error, after :http_response, then not matched.
+
 ### Chaining services
 
 Since all services return Results, you can chain service calls making a data pipeline.
@@ -206,10 +235,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 +257,59 @@ 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
+
+```
+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"] })
 ```
 
 ## 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

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 &&= actual.error == @expected_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.0'
 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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: f_service
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
-- Matheus Richard
+- Fretadao Tech Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-08 00:00:00.000000000 Z
+date: 2023-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -29,11 +29,12 @@ description: |2
       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 +53,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
@@ -77,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.3.5
 signing_key: 
 specification_version: 4
 summary: A small, monad-based service class