f_service 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a994a8e96a8aa3f6db41ba6f9dcb358a716b2c1cdce8e82c8b92f70458e941c
-  data.tar.gz: 99906aece6b382536fcda4ccb21e3874ccc755d6dfc2418fe98dd2019504513d
+  metadata.gz: cb3dfcc7d2f09fe4bd1cabca95a9520b06badf64e1d8fd7a238e0b904cdbbfe9
+  data.tar.gz: 4f71a8ecfb48c4b928b7240d63a63469a36f46635b081f221d064b0603d73be7
 SHA512:
-  metadata.gz: 0430b236523a17dae5c2afeb3db37d8354fbdce15f96789121ec184a41004242ccce40bd2a73d742f49a5312efa8dda9e6da207ceff41ef9eafabd03794e88d9
-  data.tar.gz: 3d7c7439d7283f69d494c8e402b2c08f906073c4089d7e031e6b7a00e40b66577ce7aac860b8ed49378335d4be9f867dfeb5a982a2fd6cd9bcb1b34a1094e839
+  metadata.gz: 1e3378dc3e210fd41aa994270792eb5a2dbf003f351964d81e08c4505404bc90b765fd33c4d49d39893a83d64dded6d1a5efa72bc4699ec23d7cd6273535e22d
+  data.tar.gz: 175330f3f2fbccdcc9b74f93b69ffa0a4002699139b63d19208da97327722346b154f83d46bde3f71bf23016ef23065727cb5c876fb45ed076375652da70e5b7

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.5, 2.6, 2.7, '3.0']
 
     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,8 @@ Metrics/BlockLength:
     - "spec/**/*"
 
 Style/DocumentationMethod:
-  Enabled: true
+  Enabled: true
+
+Naming/MethodName:
+  Exclude:
+    - lib/f_service/base.rb

data/CHANGELOG.md

@@ -4,16 +4,40 @@ 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.2.0
+### Added
+- Add `and_catch` 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.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    f_service (0.1.1)
+    f_service (0.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -10,16 +10,18 @@ GEM
     backport (1.1.2)
     benchmark (0.1.0)
     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)
+    mini_portile2 (2.5.0)
+    nokogiri (1.11.1)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
     parallel (1.19.1)
     parser (2.7.1.1)
       ast (~> 2.4.0)
+    racc (1.5.2)
     rainbow (3.0.0)
     rake (13.0.1)
     reverse_markdown (1.4.0)
@@ -49,10 +51,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
@@ -87,4 +91,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.0.2
+   2.1.4

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 type 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) if @name.nil?
 
     user = UserRepository.create(name: @name)
     if user.valid?
-      success(status: "User successfully created!", data: user)
+      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,63 @@ 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) }
+                .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: ->(value) { return json_success(value) },
-      failure: ->(error) { return json_error(error) }
-    )
+    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
 ```
-> You can use any object that responds to #call, not only Lambdas.
 
 ### 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 +175,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 +187,53 @@ 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, @type=:math_works>
+
+Check(:math_works) { 1 > 2 }
+# => #<Failure @error=false, @type=: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, @type=:rand_int>
+
+IHateEvenNumbers.call
+# => #<Failure @error=#<RuntimeError: Yuck! It's a 4>, @type=:rand_int>
+```
+
 ## API Docs
 
 You can access the API docs [here](https://www.rubydoc.info/gems/f_service/).

data/f_service.gemspec

@@ -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.rb

@@ -6,4 +6,12 @@ require_relative 'f_service/base'
 #
 # @api public
 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.'
+  end
 end

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,137 @@ 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'
+      )
+
+      Result::Success.new(data)
+    end
+
+    # Returns a successful result.
+    # You can optionally specify a type 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(:ok)
+    #     # => #<Success @value=nil, @type=:ok>
+    #
+    #     Success(data: 10)
+    #     # => #<Success @value=10, @type=nil>
+    #
+    #     Success(:ok, data: 10)
+    #     # => #<Success @value=10, @type=:ok>
+    #   end
+    #
+    # @param type the Result type
+    # @param data the result value
+    # @return [Result::Success] a successful result
+    def Success(type = nil, data: nil)
+      Result::Success.new(data, type)
+    end
+
+    # Returns a failed result.
+    # You can optionally specify a type 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(:not_a_number)
+    #     # => #<Failure @error=nil, @type=:not_a_number>
+    #
+    #     Failure(data: "10")
+    #     # => #<Failure @error="10", @type=nil>
+    #
+    #     Failure(:not_a_number, data: "10")
+    #     # => #<Failure @error="10", @type=:not_a_number>
+    #   end
+    #
+    # @param type the Result type
+    # @param data the result value
+    # @return [Result::Failure] a failed result
+    def Failure(type = nil, data: nil)
+      Result::Failure.new(data, type)
+    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.
+    # 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, @type=:math_works>
+    #
+    #       Check(:math_works) { 1 > 2 }
+    #       # => #<Failure @error=false, @type=:math_works>
+    #
+    #       Check(:math_works, data: 1 + 2) { 1 > 2 }
+    #       # => #<Failure @type=:math_works, @error=3>
+    #     end
+    #
+    #       Check(:math_works, data: 1 + 2) { 1 < 2 }
+    #       # => #<Success @type=:math_works, @value=3>
+    #     end
+    #   end
+    #
+    # @param type the Result type
+    # @return [Result::Success, Result::Failure] a Result from the boolean expression
+    def Check(type = nil, data: nil)
+      res = yield
+
+      final_data = data || res
+
+      res ? Success(type, data: final_data) : Failure(type, 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.
+    #
+    # @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, @type=:rand_int>
+    #
+    #   IHateEvenNumbers.call
+    #   # => #<Failure @error=#<RuntimeError: Yuck! It's a 4>, @type=:rand_int>
+    #
+    # @param type the Result type
+    # @param catch the exception list to catch
+    # @return [Result::Success, Result::Failure] a result from the boolean expression
+    def Try(type = nil, catch: StandardError)
+      res = yield
+
+      Success(type, data: res)
+    rescue *catch => e
+      Failure(type, data: e)
     end
 
     # Returns a failed operation.
@@ -93,12 +245,18 @@ 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'
+      )
+
+      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 +278,14 @@ 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'
+      )
+
       condition ? success(data) : failure(data)
     end
   end

data/lib/f_service/result/base.rb

@@ -36,14 +36,93 @@ module FService
       #
       # @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
+      #     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_success(*target_types)
+        yield(*to_ary) if successful? && expected_type?(target_types)
+
+        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
+      #
+      # @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)
+
+        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, type]
+      end
+
+      private
+
+      def expected_type?(target_types)
+        target_types.include?(type) || target_types.empty?
+      end
     end
   end
 end

data/lib/f_service/result/failure.rb

@@ -8,17 +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] type
+    #   @return [Object] the provided type for the result. Defaults to nil.
     # @api public
     class Failure < Result::Base
-      # Returns the provided error
-      attr_reader :error
+      attr_reader :error, :type
 
       # 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, type = nil)
         @error = error
+        @type = type
         freeze
       end
 
@@ -55,6 +59,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 +95,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,9 +107,10 @@ module FService
       #   end
       #
       # @return [self]
-      def then
+      def and_then
         self
       end
+      alias then and_then
 
       # Outputs a string representation of the object
       #

data/lib/f_service/result/success.rb

@@ -7,17 +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] type
+    #   @return [Object] the provided type for the result. Defaults to nil.
     # @api public
     class Success < Result::Base
-      # Returns the provided value.
-      attr_reader :value
+      attr_reader :value, :type
 
       # 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, type = nil)
         @value = value
+        @type = type
         freeze
       end
 
@@ -63,8 +67,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,10 +78,38 @@ module FService
       #     end
       #   end
       #
-      # @yieldparam [result] value pass {#value} to a block
-      def then
-        yield value
+      # @yieldparam value pass {#value} to a block
+      # @yieldparam type pass {#type} to a block
+      def and_then
+        yield(*to_ary)
       end
+      alias then and_then
+
+      # 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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: f_service
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Matheus Richard
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-15 00:00:00.000000000 Z
+date: 2021-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,6 +53,7 @@ files:
 - lib/f_service/result/failure.rb
 - lib/f_service/result/success.rb
 - lib/f_service/version.rb
+- logo.png
 homepage: https://github.com/Fretadao/f_service
 licenses:
 - MIT
@@ -60,6 +61,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 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: A small, monad-based service class