Merge branch 'feature/errors'

Author: 4ybakut2004

Gemfile.lock

@@ -32,4 +32,4 @@ DEPENDENCIES
   single_action_service!
 
 BUNDLED WITH
-   1.17.3
+   2.2.9

README.md

@@ -22,70 +22,139 @@ Or install it yourself as:
 
 ## Usage
 
-1. Inherit:
+Create an inheritor from a `SingleActionService::Base` with a single method named `call`
+
 ```ruby
-class MySingleAction < SingleActionService::Base
+class Summator < SingleActionService::Base
+  def call
+  end
 end
 ```
-2. Create a constructor with parameters or pass them to call:
+
+Create a constructor with parameters
+
 ```ruby
-# Usually a data source is passed
-def initialize(x, y)
-  @x = x
-  @y = y
+class Summator < SingleActionService::Base
+  def initialize(x, y)
+    @x = x
+    @y = y
+  end
 end
 ```
-or
+
+or pass them to the call method
+
 ```ruby
-def call(x, y)
+class Summator < SingleActionService::Base
+  def call(x, y)
+  end
 end
 ```
-3. Perform the action:
-```ruby
-sum = x + y
-```
-4. Return the result:
-```ruby
-success(sum)
-```
-or without data
+
+Perform the action and return the result by calling `success(data = nil)`
+
 ```ruby
-success
+class Summator < SingleActionService::Base
+  def call(x, y)
+    sum = x + y
+    success(sum)
+  end
+end
 ```
-5. Or return an error:
+
+or return the error based on the validations by calling `error(data: nil, code: nil)`
+
 ```ruby
-return error(data: sum, code: 1) unless sum.positive?
+class Summator < SingleActionService::Base
+  NIL_NUMBERS_ERROR = :nil_numbers_error
+
+  def call(x, y)
+    if x.nil? || y.nil?
+      return error(code: NIL_NUMBERS_ERROR)
+    end
+  end
+end
 ```
-The 'data' parameter is any data (optional).
 
-The 'code' parameter is used to identify the error (optional).
+Call the service and process a result
 
-6. You can process the result received from the service as follows:
 ```ruby
-action = MySingleAction.new
-result = action.call(1,2)
-# or uses result.error?
+summator = Summator.new
+result = summator.call(1, 2)
+
 if result.success?
   result.data
 else
-  {
-    error_code: result.error_code,
-    data: result.data
-  }
+  result.error_code
 end
 ```
-or uses data! if you want to throw an exception
+
+Or you can use a `data!` method if you want to throw an exception when an error has occurred:
+
 ```ruby
 begin
-  result = MySingleAction.new.call(1,2).data!
+  result = Summator.new.call(1, 2).data!
 rescue SingleActionService::InvalidResult => e
-  {
-    error_code: e.result.error_code,
-    data: e.result.data
-  }
+  e.result.error_code
 end
 ```
 
+You can define a list of errors of a service by calling a `self.errors(errors_data)` method.<br/>For each error, a method `#{error_name}_error(data = nil)` will be generated to instantiate the result with the appropriate code and optional data:
+
+```ruby
+class Summator < SingleActionService::Base
+  errors [
+    { name: :nil_numbers, code: 1 }
+  ]
+
+  def call(x, y)
+    if x.nil? || y.nil?
+      return nil_numbers_error
+    end
+  end
+end
+```
+
+You can check for the specific error calling an autogenerated checking method of the result:
+
+```ruby
+result = Summator.new.call(nil, nil)
+result.nil_numbers_error? # true
+```
+
+## API Reference
+
+### SingleActionService::Base
+
+A base class for services. Create an inheritor from him to use it. Methods:
+
+Name                             |Description
+---------------------------------|-----------
+`success(data = nil)`            |Returns a successful `SingleActionService::Result` with<br/>data passed in arguments.
+`error(data: nil, code: nil)`    |Returns an error `SingleActionService::Result` with<br/> data and the error code passed in arguments.
+`#{error_name}_error(data = nil)`|Autogenerated method to create an error result <br/>with the specific error code<br/>without having to pass it in arguments.<br/>Generated for each error passed to the `self.errors` method.<br/>Returns an error `SingleActionService::Result` with<br/> data passed to arguments.
+`self.errors(errors_data)`       |Call this method to identify possible service errors.<br/>Accepts an array of objects:<br/>`{ name: :error_name, code: :error_code }`
+
+### SingleActionService::Result
+
+A base class for the result that the service returns. Instantiated by service methods such as `success`, `error` and autogenerated error methods. Methods:
+
+Name                  |Description
+----------------------|-----------
+`success?`            |Call this method to check the result for success.<br/>Returns `true` for successful results created by the<br/>`success` method of a service.
+`error?`              |Call this method to check the result for error.<br/>Returns `false` for error results created by the<br/>`error` method of a service or by autogenerated<br/> error methods.
+`#{error_name}_error?`|Call this method to check the result for the specific error.<br/>Autogenerated for each error passed to the `self.errors`<br/> of a service.
+`data`                |Returns data passed to the result instantiation method
+`data!`               |Returns data passed to the result instantiation method.<br/>Throws a `SingleActionService::InvalidResult`<br/>exception if the result contains an error.
+
+### SingleActionService::InvalidResult
+
+An exception thrown by the `data!` method of a result. Methods:
+
+Name        |Description
+------------|-----------
+`result`    |Returns a `SingleActionService::Result`
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/sequenia/single_action_service. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

lib/single_action_service.rb

@@ -1,7 +1,9 @@
-require "single_action_service/exceptions"
-require "single_action_service/base"
-require "single_action_service/result"
-require "single_action_service/version"
+require 'single_action_service/exceptions'
+require 'single_action_service/module_helper'
+require 'single_action_service/base'
+require 'single_action_service/result'
+require 'single_action_service/service_error'
+require 'single_action_service/version'
 
 module SingleActionService
 end

lib/single_action_service/base.rb

@@ -1,13 +1,100 @@
-module SingleActionService
-  class Base
-    protected
+# Parent class for services.
+# A service is an object that implements part of the business logic.
+# Create an inheritor to use it
+# and call 'success' or 'error' methods to return a result object.
+class SingleActionService::Base
+  protected
 
-    def success(data = nil)
-      Result.new(true, data: data)
+  # Helper methods to setup the service
+  class << self
+    # Some usefull methods that exists in Rails
+    # but does not exists in the pure ruby
+    unless respond_to?(:module_parent)
+      include SingleActionService::ModuleHelper
     end
 
-    def error(data: nil, code: nil)
-      Result.new(false, data: data, error_code: code)
+    # Call this method to generate methods in the service to return
+    # specific errors.
+    #
+    # @param errors_data is an array of hashes with information about errors.
+    # Each hash can contain keys:
+    # :name => A symbol representing a name of the error.
+    # :code => A symbol representing an error code of the error.
+    #
+    # For each name, a method "#{name}_error" will be generated
+    # to return a result with the corresponding error code.
+    # The returned result will have "#{name}_error?" methods
+    # for checking for a specific error.
+    #
+    # For example, if you pass an array:
+    # [{ name: :already_exists, code: :'errors.already_exists' }],
+    # the 'already_exists_error' method will be generated to return the
+    # result with a :'errors.already_exists' code.
+    # You can check for the error by calling 'already_exists_error?'
+    # method on the result object.
+    def errors(errors_data = nil)
+      return @errors if errors_data.nil?
+
+      parse_errors(errors_data)
+      create_result_class
+      define_methods_to_create_error_results
+    end
+
+    def parse_errors(errors_data)
+      @errors = errors_data.map do |error_data|
+        SingleActionService::ServiceError.new(**error_data)
+      end
+    end
+
+    def create_result_class
+      demodulized_name = name.split('::').last
+      result_class_name = "#{demodulized_name}Result"
+      return if module_parent.const_defined?(result_class_name)
+
+      # Programmatically create the inheritor for the service result object
+      # with autogenerated methods for checking for errors.
+      errors = @errors
+      @result_class = Class.new(SingleActionService::Result) do
+        def self.define_error_checking_method(error)
+          method_name = "#{error.name}_error?"
+
+          define_method(method_name) do
+            error_code == error.code
+          end
+        end
+
+        errors.each do |error|
+          define_error_checking_method(error)
+        end
+      end
+
+      module_parent.const_set(result_class_name, @result_class)
     end
+
+    def define_methods_to_create_error_results
+      @errors.each do |error_object|
+        result_method_name = "#{error_object.name}_error"
+        define_method(result_method_name) do |data = nil|
+          error(code: error_object.code, data: data)
+        end
+      end
+    end
+
+    def result_class
+      @result_class ||= SingleActionService::Result
+    end
+  end
+
+  # @return a result with a success indicator and passed data.
+  # @param data is any data to return from service.
+  def success(data = nil)
+    self.class.result_class.new(true, data: data)
+  end
+
+  # @return a result with an error indicator, passed data and error code.
+  # @param data is any data to return from the service.
+  # @param code is an error code of the occurred error.
+  def error(data: nil, code: nil)
+    self.class.result_class.new(false, data: data, error_code: code)
   end
 end

lib/single_action_service/exceptions.rb

@@ -7,6 +7,7 @@ class InvalidResult < ArgumentError
     attr_reader :result
 
     def initialize(result)
+      super
       @result = result
     end
   end

lib/single_action_service/module_helper.rb

@@ -0,0 +1,21 @@
+module SingleActionService::ModuleHelper
+  def module_parent
+    module_parent_name ? constantize(module_parent_name) : Object
+  end
+
+  def constantize(string)
+    string.split('::').inject(Object) do |module_object, class_name|
+      module_object.const_get(class_name)
+    end
+  end
+
+  def module_parent_name
+    if defined?(@parent_name)
+      @parent_name
+    else
+      parent_name = name =~ /::[^:]+\z/ ? -$` : nil
+      @parent_name = parent_name unless frozen?
+      parent_name
+    end
+  end
+end

lib/single_action_service/result.rb

@@ -1,25 +1,23 @@
-module SingleActionService
-  class Result
-    attr_accessor :status, :data, :error_code
+class SingleActionService::Result
+  attr_accessor :status, :data, :error_code
 
-    def initialize(status, data: nil, error_code: nil)
-      @status = status
-      @data = data
-      @error_code = error_code
-    end
+  def initialize(status, data: nil, error_code: nil)
+    @status = status
+    @data = data
+    @error_code = error_code
+  end
 
-    def success?
-      status
-    end
+  def success?
+    status
+  end
 
-    def error?
-      !success?
-    end
+  def error?
+    !success?
+  end
 
-    def data!
-      return data if success?
+  def data!
+    return data if success?
 
-      raise InvalidResult.new(self)
-    end
+    raise SingleActionService::InvalidResult, self
   end
 end

lib/single_action_service/service_error.rb

@@ -0,0 +1,8 @@
+class SingleActionService::ServiceError
+  attr_accessor :code, :name
+
+  def initialize(code: nil, name: nil)
+    @code = code
+    @name = name
+  end
+end

lib/single_action_service/version.rb

@@ -1,3 +1,3 @@
 module SingleActionService
-  VERSION = "0.3.0"
+  VERSION = '0.4.0'.freeze
 end