single_action_service 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 568daaaceb993e7f869cd2785cafc48d27c71faa16e11e971237fd3f483bc512
-  data.tar.gz: 75f0112d564ba9da90a88e8bfacbbb3987c83c577d1e7472c4539b859d79b1aa
+  metadata.gz: 6457094da633a11d6323fc370acdb124e0af8a74fd873a3b21b97e77a36ba7ac
+  data.tar.gz: 466715ec68f4508c7fd67c353b862965379a14ae4dd7ce718b6de8addd5b855f
 SHA512:
-  metadata.gz: aedab1f0637bc635e5824cbd5b906fdc26d5a4c66388c450e5c9030945fdb48e05e6d9803acfb1d1fefa6f6791b6d462e96d39202d1c0a922e9a4e018e939a4e
-  data.tar.gz: b7bea6bd03dc96471c71472d57d3cf2c71ba72c1f3e7053899a982b1c43b09bb89b8d8abaae4c412dd1b3064b88a0c972488720050326c69eae80a21af6c7db8
+  metadata.gz: 8cf3e5df350aa221819badc9064c14467bc9d35dc6fa124306ebdf33ab461b2c769a59a4b0859eaf9f4bcf0a5105c21db931dd41f25556691f148c55f5378e8f
+  data.tar.gz: 7faebeb6bce78ff1e2d6aa601da89df2cfcfaf30d6b1251ec3ae878440bb7c694f624f34e43cfc53ab5f2e6583fb08bdebf1c7879e3e4e09fe7ed21d732a02bf

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    single_action_service (0.3.0)
+    single_action_service (0.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.3)
-    rake (10.5.0)
+    rake (13.0.3)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -26,10 +26,10 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.17)
-  rake (~> 10.0)
+  bundler (~> 2.1)
+  rake (~> 13.0)
   rspec (~> 3.0)
   single_action_service!
 
 BUNDLED WITH
-   1.17.3
+   2.2.9

data/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.

data/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

data/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

data/lib/single_action_service/exceptions.rb

@@ -7,6 +7,7 @@ module SingleActionService
     attr_reader :result
 
     def initialize(result)
+      super
       @result = result
     end
   end

data/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

data/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

data/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

data/lib/single_action_service/version.rb

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

data/single_action_service.gemspec

@@ -1,29 +1,31 @@
-
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "single_action_service/version"
+require 'single_action_service/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "single_action_service"
+  spec.name          = 'single_action_service'
   spec.version       = SingleActionService::VERSION
-  spec.authors       = ["Bazov Peter"]
-  spec.email         = ["petr@sequenia.com"]
+  spec.authors       = ['Bazov Peter']
+  spec.email         = ['petr@sequenia.com']
 
-  spec.summary       = %q{Single Action Service}
-  spec.description   = %q{A Ruby library to organize the code}
-  spec.homepage      = "http://sequenia.com/"
-  spec.license       = "MIT"
+  spec.summary       = 'Single Action Service'
+  spec.description   = 'A Ruby library to organize the code'
+  spec.homepage      = 'https://github.com/sequenia/SingleActionService'
+  spec.license       = 'MIT'
 
   # 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.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  # The `git ls-files -z` loads the files in the RubyGem
+  # that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`
+      .split("\x0")
+      .reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.17"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'bundler', '~> 2.1'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: single_action_service
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Bazov Peter
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-16 00:00:00.000000000 Z
+date: 2021-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -73,10 +73,12 @@ files:
 - lib/single_action_service.rb
 - lib/single_action_service/base.rb
 - lib/single_action_service/exceptions.rb
+- lib/single_action_service/module_helper.rb
 - lib/single_action_service/result.rb
+- lib/single_action_service/service_error.rb
 - lib/single_action_service/version.rb
 - single_action_service.gemspec
-homepage: http://sequenia.com/
+homepage: https://github.com/sequenia/SingleActionService
 licenses:
 - MIT
 metadata: {}
@@ -95,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.2.3
 signing_key: 
 specification_version: 4
 summary: Single Action Service