f_service 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a994a8e96a8aa3f6db41ba6f9dcb358a716b2c1cdce8e82c8b92f70458e941c
-  data.tar.gz: 99906aece6b382536fcda4ccb21e3874ccc755d6dfc2418fe98dd2019504513d
+  metadata.gz: 6cb29d87cf5c970b2b185ed2c3da41020f40122e2d0857af068302fb32e55400
+  data.tar.gz: 27a89660bb6d1e65d537f5d6617cc8175f600ab71efca79f65875a1b6adf0c97
 SHA512:
-  metadata.gz: 0430b236523a17dae5c2afeb3db37d8354fbdce15f96789121ec184a41004242ccce40bd2a73d742f49a5312efa8dda9e6da207ceff41ef9eafabd03794e88d9
-  data.tar.gz: 3d7c7439d7283f69d494c8e402b2c08f906073c4089d7e031e6b7a00e40b66577ce7aac860b8ed49378335d4be9f867dfeb5a982a2fd6cd9bcb1b34a1094e839
+  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,12 +11,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [2.4, 2.5, 2.6, 2.7]
+        ruby: [2.6, 2.7, 3.0, 3.1]
 
     steps:
       - uses: actions/checkout@v2
       - name: Set up Ruby ${{ matrix.ruby }}
-        uses: actions/setup-ruby@v1
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
       - name: Build and test with Rake

data/.rubocop.yml

@@ -12,4 +12,22 @@ Metrics/BlockLength:
     - "spec/**/*"
 
 Style/DocumentationMethod:
-  Enabled: true
+  Enabled: true
+
+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

@@ -4,16 +4,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
-_Nothing here_
+## Unreleased (master)
+<!-- ### Added -->
+<!-- ### Changed -->
+<!-- ### 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_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.
+- Yields result type on blocks (`then`, `on_success` and `on_failure`).
+- Add type check on `Result#on_success` and `Result#on_failure` hooks.
+- Add method `Base#Try`. It wraps exceptions in Failures.
+- Add method `Base#Check`. It converts booleans to Results.
+- Add methods `#Success(type, data:)` and `#Failure(type, data:)` on `FService::Base`.
+  These methods allow defining the type and value of the Result object.
+- Allow adding types on `Result`s.
+- Add `#on_success` and `#on_failure` hooks on Result objects.
+- Link to Changelog on gemspec.
+
+### Changed
+- **[Deprecation]** Mark `Base#result` as deprecated. They will be removed on the next release. Use the `Base#Check` instead.
+- **[Deprecation]** Mark `Base#success` and `Base#failure` as deprecated. They will be removed on the next release. Use the `Base#Success` and `Base#Failure` instead.
+- **[Deprecation]** Mark `Result#on` as deprecated. It will be removed on the next release. Use the`Result#on_success` and/or `Result#on_failure` hooks instead.
 
 ## 0.1.1
 ### Added
 First usable version with:
-- Result based services;
-- Type check on results;
-- Pattern matching with `#call`ables;
-- Safe chaining calls with `#then`;
+- Result based services
+- Type check on results
+- Pattern matching with `#call`ables
+- Safe chaining calls with `#then`
 
 ## 0.1.0
-- **Yanked**
+- **Yanked**

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.1.1)
+    f_service (0.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -9,22 +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.2)
+    docile (1.3.5)
     e2mmap (0.1.0)
     jaro_winkler (1.5.4)
     maruku (0.7.3)
-    mini_portile2 (2.4.0)
-    nokogiri (1.10.9)
-      mini_portile2 (~> 2.4.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)
+    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)
@@ -49,10 +58,12 @@ GEM
     rubocop-rspec (1.38.1)
       rubocop (>= 0.68.1)
     ruby-progressbar (1.10.1)
-    simplecov (0.18.2)
+    simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
-    simplecov-html (0.12.0)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
     solargraph (0.38.6)
       backport (~> 1.1)
       benchmark
@@ -78,6 +89,8 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.0)
   f_service!
+  pry
+  pry-nav
   rake (~> 13.0.0)
   rspec (~> 3.0)
   rubocop (~> 0.82.0)
@@ -87,4 +100,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.0.2
+   2.2.32

data/README.md

@@ -1,6 +1,19 @@
-![CI](https://github.com/Fretadao/f_service/workflows/Ruby/badge.svg)
-
-# FService
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Fretadao/f_service/master/logo.png" height="150">
+
+  <h1 align="center">FService</h1>
+
+  <p align="center">
+    <i>Simpler, safer and more composable operations</i>
+    <br>
+    <br>
+    <img src="https://img.shields.io/gem/v/f_service">
+    <img src="https://github.com/Fretadao/f_service/workflows/Ruby/badge.svg">
+    <a href="https://github.com/Fretadao/f_service/blob/master/LICENSE">
+      <img src="https://img.shields.io/github/license/Fretadao/f_service.svg" alt="License">
+    </a>
+  </p>
+</p>
 
 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.
@@ -23,7 +36,9 @@ Or install it yourself as:
     $ gem install f_service
 
 ## Usage
+
 ### Creating your service
+
 To start using it, you have to create your service class inheriting from FService::Base.
 
 ```ruby
@@ -32,6 +47,7 @@ end
 ```
 
 Now, define your initializer to setup data.
+
 ```ruby
 class User::Create < FService::Base
   def initialize(name:)
@@ -41,23 +57,25 @@ 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. The return can be any value.
+Use the methods `#Success` and `#Failure` to handle your return values.
+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 given") if @name.nil?
+    return Failure(:no_name, :invalid_attribute) if @name.nil?
 
     user = UserRepository.create(name: @name)
-    if user.valid?
-      success(status: "User successfully created!", data: user)
+    if user.save
+      Success(:success, :created, data: user)
     else
-      failure(status: "User could not be created!", data: user.errors)
+      Failure(:creation_failed, data: user.errors)
     end
   end
 end
 ```
+
 > Remember, you **have** to return an `FService::Result` at the end of your services.
 
 ### Using your service
@@ -70,7 +88,9 @@ User::Create.(name: name)
 User::Create.call(name: name)
 ```
 
-> We do **not** recommend manually initializing your service because it **will not** type check your result (and you could lose nice features like [pattern matching](#pattern-matching) and [service chaining](#chaining-services))!
+> We do **not** recommend manually initializing and running your service because it **will not**
+> type check your result (and you could lose nice features like [pattern
+> matching](#pattern-matching) and [service chaining](#chaining-services))!
 
 ### Using the result
 
@@ -91,24 +111,92 @@ class UsersController < BaseController
   end
 end
 ```
+
 > Note that you're not limited to using services inside controllers. They're just PORO's (Play Old Ruby Objects), so you can use in controllers, models, etc. (even other services!).
 
 ### Pattern matching
-The code above could be rewritten using the `#on` matcher too. It works similar to pattern matching:
+
+The code above could be rewritten using the `#on_success` and `#on_failure` hooks. They work similar to pattern matching:
 
 ```ruby
 class UsersController < BaseController
   def create
-    User::Create.(user_params).on(
-      success: ->(value) { return json_success(value) },
-      failure: ->(error) { return json_error(error) }
-    )
+    User::Create.(user_params)
+                .on_success { |value| return json_success(value) }
+                .on_failure { |error| return json_error(error) }
   end
 end
 ```
-> You can use any object that responds to #call, not only Lambdas.
+
+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:
+
+```ruby
+class UsersController < BaseController
+  def create
+    User::Create.(user_params)
+                .on_success(:user_created) { |value| return json_success(value) }
+                .on_success(:user_already_exists) { |value| return json_success(value) }
+                .on_failure(:invalid_data) { |error| return json_error(error) }
+                .on_failure(:critical_error) do |error|
+                  MyLogger.report_failure(error)
+
+                  return json_error(error)
+                end
+  end
+end
+```
+
+It's possible to provide multiple types to the hooks too. If the result type matches any of the given types,
+the hook will run.
+
+```ruby
+class UsersController < BaseController
+  def create
+    User::Create.(user_params)
+                .on_success(:user_created, :user_already_exists) { |value| return json_success(value) }
+                .on_failure(:invalid_data) { |error| return json_error(error) }
+                .on_failure(:critical_error) do |error|
+                  MyLogger.report_failure(error)
+
+                  return json_error(error)
+                end
+  end
+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.
 If some step fails, it will short circuit the call chain.
 
@@ -116,8 +204,8 @@ If some step fails, it will short circuit the call chain.
 class UsersController < BaseController
   def create
     result = User::Create.(user_params)
-                         .then { |user| User::Login.(user) }
-                         .then { |user| User::SendWelcomeEmail.(user) }
+                         .and_then { |user| User::Login.(user) }
+                         .and_then { |user| User::SendWelcomeEmail.(user) }
 
     if result.successful?
       json_success(result.value)
@@ -128,6 +216,102 @@ class UsersController < BaseController
 end
 ```
 
+You can use the `.to_proc` method on FService::Base to avoid explicit inputs when chaining services:
+
+```ruby
+class UsersController < BaseController
+  def create
+    result = User::Create.(user_params)
+                         .and_then(&User::Login)
+                         .and_then(&User::SendWelcomeEmail)
+    # ...
+  end
+end
+```
+
+### `Check` and `Try`
+
+You can use `Check` to converts a boolean to a Result, truthy values map to `Success`, and falsey values map to `Failures`:
+
+```ruby
+Check(:math_works) { 1 < 2 }
+# => #<Success @value=true, @types=[:math_works]>
+
+Check(:math_works) { 1 > 2 }
+# => #<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
+using the parameter `catch`.
+
+```ruby
+class IHateEvenNumbers < FService::Base
+  def run
+    Try(:rand_int) do
+      n = rand(1..10)
+      raise "Yuck! It's a #{n}" if n.even?
+
+      n
+    end
+  end
+end
+
+IHateEvenNumbers.call
+# => #<Success @value=9, @types=[:rand_int]>
+
+IHateEvenNumbers.call
+# => #<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
 
 You can access the API docs [here](https://www.rubydoc.info/gems/f_service/).

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
@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.metadata['homepage_uri']    = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/Fretadao/f_service'
   spec.metadata['documentation_uri'] = 'https://www.rubydoc.info/gems/f_service'
-  # spec.metadata['changelog_uri'] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata['changelog_uri'] = 'https://github.com/Fretadao/f_service/blob/master/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

data/lib/f_service/base.rb

@@ -10,20 +10,44 @@ module FService
   #
   # @abstract
   class Base
-    # Initializes and runs a new service.
-    #
-    # @example
-    #   User::UpdateName.(user: user, new_name: new_name)
-    #   # or
-    #   User::UpdateName.call(user: user, new_name: new_name)
-    #
-    # @note this method shouldn't be overridden in the subclasses
-    # @return [FService::Result::Success, FService::Result::Failure]
-    def self.call(*params)
-      result = new(*params).run
-      raise(FService::Error, 'Services must return a Result') unless result.is_a? Result::Base
+    class << self
+      # Initializes and runs a new service.
+      #
+      # @example
+      #   User::UpdateName.(user: user, new_name: new_name)
+      #   # or
+      #   User::UpdateName.call(user: user, new_name: new_name)
+      #
+      # @note this method shouldn't be overridden in the subclasses
+      # @return [Result::Success, Result::Failure]
+      def call(*args)
+        result = new(*args).run
+        raise(FService::Error, 'Services must return a Result') unless result.is_a? Result::Base
+
+        result
+      end
 
-      result
+      ruby2_keywords :call if respond_to?(:ruby2_keywords, true)
+
+      # Allows running a service without explicit giving params.
+      # This is useful when chaining services or mapping inputs to be processed.
+      #
+      # @example
+      #   # Assuming all classes here subclass FService::Base:
+      #
+      #   User::Create
+      #     .and_then(&User::Login)
+      #     .and_then(&SendWelcomeEmail)
+      #
+      #   # Mapping inputs:
+      #
+      #   [{ n:1 }, { n: 2 }].map(&DoubleNumber).map(&:value)
+      #   # => [2, 4]
+      #
+      # @return [Proc]
+      def to_proc
+        proc { |args| call(**args) }
+      end
     end
 
     # This method is where the main work of your service must be.
@@ -38,18 +62,18 @@ module FService
     #     end
     #
     #     def run
-    #       return failure('Missing user') if user.nil?
+    #       return Failure(:missing_user) if user.nil?
     #
     #       if @user.update(name: @new_name)
-    #         success(status: 'User successfully updated!', data: user)
+    #         Success(:created, data: user)
     #       else
-    #         failure(status: 'User could not be updated.', data: user.errors)
+    #         Failure(:creation_failed, data: user.errors)
     #       end
     #     end
     #   end
     #
     # @note this method SHOULD be overridden in the subclasses
-    # @return [FService::Result::Success, FService::Result::Failure]
+    # @return [Result::Success, Result::Failure]
     def run
       raise NotImplementedError, 'Services must implement #run'
     end
@@ -72,9 +96,138 @@ module FService
     #     end
     #   end
     #
-    # @return [FService::Result::Success] - a successful operation
+    # @deprecated Use {#Success} instead.
+    # @return [Result::Success] a successful operation
     def success(data = nil)
-      FService::Result::Success.new(data)
+      FService.deprecate!(
+        name: "#{self.class}##{__method__}",
+        alternative: '#Success',
+        from: caller[0]
+      )
+
+      Result::Success.new(data)
+    end
+
+    # Returns a successful 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, @types=[]>
+    #
+    #     Success(:ok)
+    #     # => #<Success @value=nil, @types=[:ok]>
+    #
+    #     Success(data: 10)
+    #     # => #<Success @value=10, @types=[]>
+    #
+    #     Success(:ok, data: 10)
+    #     # => #<Success @value=10, @types=[:ok]>
+    #   end
+    #
+    # @param types the Result types
+    # @param data the result value
+    # @return [Result::Success] a successful result
+    def Success(*types, data: nil)
+      Result::Success.new(data, types)
+    end
+
+    # Returns a failed 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, @types=[]>
+    #
+    #     Failure(:not_a_number)
+    #     # => #<Failure @error=nil, @types=[:not_a_number]>
+    #
+    #     Failure(data: "10")
+    #     # => #<Failure @error="10", @types=[]>
+    #
+    #     Failure(:not_a_number, data: "10")
+    #     # => #<Failure @error="10", @types=[:not_a_number]>
+    #   end
+    #
+    # @param types the Result types
+    # @param data the result value
+    # @return [Result::Failure] a failed result
+    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 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.
+    #
+    # @example
+    #   class CheckMathWorks < FService::Base
+    #     def run
+    #       Check(:math_works) { 1 < 2 }
+    #       # => #<Success @value=true, @types=[:math_works]>
+    #
+    #       Check(:math_works) { 1 > 2 }
+    #       # => #<Failure @error=false, @types=[:math_works]>
+    #
+    #       Check(:math_works, data: 1 + 2) { 1 > 2 }
+    #       # => #<Failure @types=:math_works, @error=3>
+    #     end
+    #
+    #       Check(:math_works, data: 1 + 2) { 1 < 2 }
+    #       # => #<Success @types=[:math_works], @value=3>
+    #     end
+    #   end
+    #
+    # @param types the Result types
+    # @return [Result::Success, Result::Failure] a Result from the boolean expression
+    def Check(*types, data: nil)
+      res = yield
+
+      final_data = data || res
+
+      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 types for the result too.
+    #
+    # @example
+    #   class IHateEvenNumbers < FService::Base
+    #     def run
+    #       Try(:rand_int) do
+    #         n = rand(1..10)
+    #         raise "Yuck! It's a #{n}" if n.even?
+    #
+    #         n
+    #       end
+    #     end
+    #   end
+    #
+    #   IHateEvenNumbers.call
+    #   # => #<Success @value=9, @types=[:rand_int]>
+    #
+    #   IHateEvenNumbers.call
+    #   # => #<Failure @error=#<RuntimeError: Yuck! It's a 4>, @types=[:rand_int]>
+    #
+    # @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(*types, catch: StandardError)
+      res = yield
+
+      Success(*types, data: res)
+    rescue *catch => e
+      Failure(*types, data: e)
     end
 
     # Returns a failed operation.
@@ -93,12 +246,19 @@ module FService
     #     end
     #   end
     #
-    # @return [FService::Result::Failure] - a failed operation
+    # @deprecated Use {#Failure} instead.
+    # @return [Result::Failure] a failed operation
     def failure(data = nil)
-      FService::Result::Failure.new(data)
+      FService.deprecate!(
+        name: "#{self.class}##{__method__}",
+        alternative: '#Failure',
+        from: caller[0]
+      )
+
+      Result::Failure.new(data)
     end
 
-    # Return either {FService::Result::Failure Success} or {FService::Result::Failure Failure}
+    # Return either {Result::Failure Success} or {Result::Failure Failure}
     # given the condition.
     #
     # @example
@@ -120,8 +280,15 @@ module FService
     #     end
     #   end
     #
-    # @return [FService::Result::Success, FService::Result::Failure]
+    # @deprecated Use {#Check} instead.
+    # @return [Result::Success, Result::Failure]
     def result(condition, data = nil)
+      FService.deprecate!(
+        name: "#{self.class}##{__method__}",
+        alternative: '#Check',
+        from: caller[0]
+      )
+
       condition ? success(data) : failure(data)
     end
   end

data/lib/f_service/result/base.rb

@@ -7,24 +7,54 @@ 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(: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
+      #
+      #     def user
+      #       @user ||= User.find_by!(slug: params[:slug])
+      #     end
+      #   end
       #
       # @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(unhandled: true) { |value| return json_success(value) }
+      #                   .on_failure(unhandled: true) { |error| return json_error(error) } # this won't run
       #     end
       #
       #     private
@@ -34,15 +64,96 @@ 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
+      # @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(success:, failure:)
-        if successful?
-          success.call(value)
-        else
-          failure.call(error)
+      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
+
+      # This hook runs if the result is failed.
+      # 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) } # this won't run
+      #                   .on_failure(:type, :type2) { |error| return json_error(error) } # runs only if type matches
+      #                   .on_failure { |error| return json_error(error) }
+      #     end
+      #
+      #     private
+      #
+      #     def user
+      #       @user ||= User.find_by!(slug: params[:slug])
+      #     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, unhandled: false)
+        if failed? && unhandled? && expected_type?(target_types, unhandled: unhandled)
+          match_types(target_types)
+          yield(*to_ary)
+          @handled = true
+          freeze
+        end
+
+        self
+      end
+
+      # Splits the result object into its components.
+      #
+      # @return [Array] value and type of the result object
+      def to_ary
+        data = successful? ? value : error
+
+        [data, @matching_types.first]
+      end
+
+      private
+
+      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

@@ -8,18 +8,21 @@ module FService
     # Represents a value of a failed operation.
     # The error field can contain any information you want.
     #
+    # @!attribute [r] error
+    #   @return [Object] the provided error for the result
+    # @!attribute [r] types
+    #   @return [Object] the provided types for the result. Defaults to nil.
     # @api public
     class Failure < Result::Base
-      # Returns the provided error
       attr_reader :error
 
       # Creates a failed operation.
-      # You usually shouldn't call this directly. See {FService::Base#failure}.
+      # You usually shouldn't call this directly. See {FService::Base#Failure}.
       #
       # @param error [Object] failure value.
-      def initialize(error)
+      def initialize(error, types = [])
+        super(types)
         @error = error
-        freeze
       end
 
       # Returns false.
@@ -55,6 +58,33 @@ module FService
         raise Result::Error, 'Failure objects do not have value'
       end
 
+      # Returns the current error to the given block.
+      # Use this to chain multiple service calls (since all services return Results).
+      # It works just like the `.and_then` method, but only runs if the result is a Failure.
+      #
+      #
+      # @example
+      #   class UpdateUserOnExternalService
+      #     attribute :user_params
+      #
+      #     def run
+      #       check_api_status
+      #         .and_then { update_user }
+      #         .or_else { create_update_worker }
+      #     end
+      #
+      #     private
+      #     # some code
+      #   end
+      #
+      # @yieldparam error pass {#error} to a block
+      # @yieldparam type pass {#type} to a block
+      def catch
+        yield(*to_ary)
+      end
+
+      alias or_else catch
+
       # Returns itself to the given block.
       # Use this to chain multiple service calls (since all services return Results).
       # It will short circuit your service call chain.
@@ -64,8 +94,8 @@ module FService
       #   class UsersController < BaseController
       #     def create
       #       result = User::Create.(user_params) # if this fails the following calls won't run
-      #                 .then { |user| User::SendWelcomeEmail.(user: user) }
-      #                 .then { |user| User::Login.(user: user) }
+      #                            .and_then { |user| User::SendWelcomeEmail.(user: user) }
+      #                            .and_then { |user| User::Login.(user: user) }
       #
       #       if result.successful?
       #         json_success(result.value)
@@ -76,10 +106,16 @@ module FService
       #   end
       #
       # @return [self]
-      def then
+      def and_then
         self
       end
 
+      # 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

@@ -7,18 +7,21 @@ module FService
     # Represents a value of a successful operation.
     # The value field can contain any information you want.
     #
+    # @!attribute [r] value
+    #   @return [Object] the provided value for the result
+    # @!attribute [r] types
+    #   @return [Object] the provided types for the result. Defaults to nil.
     # @api public
     class Success < Result::Base
-      # Returns the provided value.
       attr_reader :value
 
       # Creates a successful operation.
-      # You usually shouldn't call this directly. See {FService::Base#success}.
+      # You usually shouldn't call this directly. See {FService::Base#Success}.
       #
       # @param value [Object] success value.
-      def initialize(value)
+      def initialize(value, types = [])
+        super(types)
         @value = value
-        freeze
       end
 
       # Returns true.
@@ -63,8 +66,8 @@ module FService
       #   class UsersController < BaseController
       #     def create
       #       result = User::Create.(user_params)
-      #                 .then { |user| User::SendWelcomeEmail.(user: user) }
-      #                 .then { |user| User::Login.(user: user) }
+      #                            .and_then { |user| User::SendWelcomeEmail.(user: user) }
+      #                            .and_then { |user| User::Login.(user: user) }
       #
       #       if result.successful?
       #         json_success(result.value)
@@ -74,11 +77,45 @@ module FService
       #     end
       #   end
       #
-      # @yieldparam [result] value pass {#value} to a block
-      def then
-        yield value
+      # @yieldparam value pass {#value} to a block
+      # @yieldparam types pass {#types} to a block
+      def and_then
+        yield(*to_ary)
       end
 
+      # 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).
+      # It works just like the `.and_then` method, but only runs if service is a Failure.
+      #
+      #
+      # @example
+      #   class UpdateUserOnExternalService
+      #     attribute :user_params
+      #
+      #     def run
+      #       check_api_status
+      #         .and_then { update_user }
+      #         .or_else { create_update_worker }
+      #     end
+      #
+      #     private
+      #     # some code
+      #   end
+      #
+      # @return [self]
+      def catch
+        self
+      end
+
+      alias or_else catch
+
       # Outputs a string representation of the object
       #
       #

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.1.1'
+  VERSION = '0.3.0'
 end

data/lib/f_service.rb

@@ -6,4 +6,27 @@ require_relative 'f_service/base'
 #
 # @api public
 module FService
+  # Marks a method as deprecated
+  #
+  # @api private
+  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.1.1
+  version: 0.3.0
 platform: ruby
 authors:
-- Matheus Richard
+- Fretadao Tech Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-15 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,7 +53,14 @@ 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
 licenses:
 - MIT
@@ -60,6 +68,7 @@ metadata:
   homepage_uri: https://github.com/Fretadao/f_service
   source_code_uri: https://github.com/Fretadao/f_service
   documentation_uri: https://www.rubydoc.info/gems/f_service
+  changelog_uri: https://github.com/Fretadao/f_service/blob/master/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -75,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.3.5
 signing_key: 
 specification_version: 4
 summary: A small, monad-based service class