servactory 1.5.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f9511d2fb9a463c46f04ba4e6f005b14f9048039524a1aed476ee1a4fa997ef
-  data.tar.gz: f5e03fa8943d3a5fd4735ec3817528202ce3b2e06106d81f0ad08fde2e4e4baf
+  metadata.gz: dd3981fb61af74a47cc5d5279a51796d78527c2b4b16c3bdb69f7bd94e32932f
+  data.tar.gz: ca8ad9beca25c5dd04a9f7bb584ced4cef6b3f35d6d14c68c0d297ef817b8025
 SHA512:
-  metadata.gz: 406a99f8386dc97033fd28231e8b11438aa8827878ee332b11efa43747b92f7fcc993b547413733651a93bc0d1f59f6799f4b7e70778038f685d91206ff35be9
-  data.tar.gz: 2895de4a4fc256dcec75cddaddc0ff92b70e9cf42de13309acde95447b0466d4afa8103d52b6ec66e219109065f7f9ffea022c7c41789e88383f32cf08a5e8bb
+  metadata.gz: e95bffde026a1b55bca088e15d86c2ec2b78ff4838be5f683c574e9ea1ed148a993a3075c4fb7b72493d3667b7280b4fe177edd748262bd77193425571aabb96
+  data.tar.gz: c41af274f2c6c858f29cef27f7b9d0b61ebf106712f9a55ca739782f2bbb2e12758c51a4271901505fdd81028ec435b52308244a2d581ee8c82841b768169b7f

data/README.md

@@ -5,7 +5,7 @@ A set of tools for building reliable services of any complexity.
 [![Gem version](https://img.shields.io/gem/v/servactory?logo=rubygems&logoColor=fff)](https://rubygems.org/gems/servactory)
 [![Release Date](https://img.shields.io/github/release-date/afuno/servactory)](https://github.com/afuno/servactory/releases)
 
-## Contents
+## Table of contents
 
 - [Requirements](#requirements)
 - [Getting started](#getting-started)
@@ -16,18 +16,19 @@ A set of tools for building reliable services of any complexity.
   - [Minimal example](#minimal-example)
   - [Call](#call)
   - [Result](#result)
-  - [Input attributes](#input-attributes)
-    - [Isolated usage](#isolated-usage)
-    - [As an internal argument](#isolated-usage)
-    - [Optional inputs](#optional-inputs)
-    - [As (internal name)](#as-internal-name)
-    - [An array of specific values](#an-array-of-specific-values)
-    - [Inclusion](#inclusion)
-    - [Must](#must)
-  - [Output attributes](#output-attributes)
-  - [Internal attributes](#internal-attributes)
+  - [Input](#input)
+    - [Type](#option-type)
+    - [Required](#option-required)
+    - [Internal](#option-internal)
+    - [Internal name](#option-as)
+    - [Array](#option-array)
+    - [Inclusion](#option-inclusion)
+    - [Must](#option-must)
+  - [Output](#output)
+  - [Internal](#internal)
   - [Make](#make)
   - [Failures](#failures)
+  - [Inheritance](#inheritance)
 - [I18n](#i18n)
 - [Testing](#testing)
 - [Thanks](#thanks)
@@ -69,9 +70,9 @@ As a first step, it is recommended to prepare the base class for further inherit
 
 module ApplicationService
   module Errors
-    class InputArgumentError < Servactory::Errors::InputArgumentError; end
-    class OutputArgumentError < Servactory::Errors::OutputArgumentError; end
-    class InternalArgumentError < Servactory::Errors::InternalArgumentError; end
+    class InputError < Servactory::Errors::InputError; end
+    class OutputError < Servactory::Errors::OutputError; end
+    class InternalError < Servactory::Errors::InternalError; end
 
     class Failure < Servactory::Errors::Failure; end
   end
@@ -86,9 +87,9 @@ end
 module ApplicationService
   class Base < Servactory::Base
     configuration do
-      input_argument_error_class ApplicationService::Errors::InputArgumentError
-      output_argument_error_class ApplicationService::Errors::OutputArgumentError
-      internal_argument_error_class ApplicationService::Errors::InternalArgumentError
+      input_error_class ApplicationService::Errors::InputError
+      output_error_class ApplicationService::Errors::OutputError
+      internal_error_class ApplicationService::Errors::InternalError
 
       failure_class ApplicationService::Errors::Failure
     end
@@ -155,11 +156,45 @@ And then you can work with this result, for example, in this way:
 Notification::SendJob.perform_later(service_result.user.id)
 ```
 
-### Input attributes
+### Input
 
-#### Isolated usage
+#### Option `type`
 
-With this approach, all input attributes are available only from `inputs`. This is default behaviour.
+Always required to specify. May contain one or more classes.
+
+```ruby
+class UsersService::Accept < ApplicationService::Base
+  input :user, type: User
+
+  # ...
+end
+```
+
+```ruby
+class ToggleService < ApplicationService::Base
+  input :flag, type: [TrueClass, FalseClass]
+
+  # ...
+end
+```
+
+#### Option `required`
+
+By default, `required` is set to `true`.
+
+```ruby
+class UsersService::Create < ApplicationService::Base
+  input :first_name, type: String
+  input :middle_name, type: String, required: false
+  input :last_name, type: String
+
+  # ...
+end
+```
+
+#### Option `internal`
+
+By default, `internal` is set to `false`.
 
 ```ruby
 class UsersService::Accept < ApplicationService::Base
@@ -175,10 +210,6 @@ class UsersService::Accept < ApplicationService::Base
 end
 ```
 
-#### As an internal argument
-
-With this approach, all input attributes are available from `inputs` as well as directly from the context.
-
 ```ruby
 class UsersService::Accept < ApplicationService::Base
   input :user, type: User, internal: true
@@ -193,21 +224,7 @@ class UsersService::Accept < ApplicationService::Base
 end
 ```
 
-#### Optional inputs
-
-By default, all inputs are required. To make an input optional, specify `false` in the `required` option.
-
-```ruby
-class UsersService::Create < ApplicationService::Base
-  input :first_name, type: String
-  input :middle_name, type: String, required: false
-  input :last_name, type: String
-
-  # ...
-end
-```
-
-#### As (internal name)
+#### Option `as`
 
 This option changes the name of the input within the service.
 
@@ -227,7 +244,9 @@ class NotificationService::Create < ApplicationService::Base
 end
 ```
 
-#### An array of specific values
+#### Option `array`
+
+Using this option will mean that the input argument is an array, each element of which has the specified type.
 
 ```ruby
 class PymentsService::Send < ApplicationService::Base
@@ -237,7 +256,7 @@ class PymentsService::Send < ApplicationService::Base
 end
 ```
 
-#### Inclusion
+#### Option `inclusion`
 
 ```ruby
 class EventService::Send < ApplicationService::Base
@@ -247,7 +266,7 @@ class EventService::Send < ApplicationService::Base
 end
 ```
 
-#### Must
+#### Option `must`
 
 Sometimes there are cases that require the implementation of a specific input attribute check. In such cases `must` can help.
 
@@ -266,7 +285,7 @@ class PymentsService::Send < ApplicationService::Base
 end
 ```
 
-### Output attributes
+### Output
 
 ```ruby
 class NotificationService::Create < ApplicationService::Base
@@ -284,7 +303,7 @@ class NotificationService::Create < ApplicationService::Base
 end
 ```
 
-### Internal attributes
+### Internal
 
 ```ruby
 class NotificationService::Create < ApplicationService::Base
@@ -351,10 +370,6 @@ def process_result
 end
 ```
 
-#### Inheritance
-
-Service inheritance is also supported.
-
 ### Failures
 
 The methods that are used in `make` may fail. In order to more informatively provide information about this outside the service, the following methods were prepared.
@@ -367,7 +382,7 @@ make :check!
 def check!
   return if inputs.invoice_number.start_with?("AA")
 
-  fail!("Invalid invoice number")
+  fail!(message: "Invalid invoice number")
 end
 ```
 
@@ -379,10 +394,32 @@ make :check!
 def check!
   return if inputs.invoice_number.start_with?("AA")
 
-  fail_input!(:invoice_number, "Invalid invoice number")
+  fail_input!(:invoice_number, message: "Invalid invoice number")
 end
 ```
 
+#### Metadata
+
+```ruby
+fail!(
+  message: "Invalid invoice number", 
+  meta: { 
+    invoice_number: inputs.invoice_number 
+  }
+)
+```
+
+```ruby
+exception.detailed_message  # => Invalid invoice number (ApplicationService::Errors::Failure)
+exception.message           # => Invalid invoice number
+exception.type              # => :fail
+exception.meta              # => {:invoice_number=>"BB-7650AE"}
+```
+
+### Inheritance
+
+Inheritance between services is also supported.
+
 ## I18n
 
 All texts are stored in the localization file. All texts can be changed or supplemented by new locales.

data/config/locales/en.yml

@@ -1,6 +1,6 @@
 en:
   servactory:
-    input_arguments:
+    inputs:
       checks:
         inclusion:
           default_error: "[%{service_class_name}] Wrong value in `%{input_name}`, must be one of `%{input_inclusion}`"
@@ -20,14 +20,14 @@ en:
           error: "[%{service_class_name}] Unexpected attributes: `%{unnecessary_attributes}`"
         rules:
           error: "[%{service_class_name}] Conflict in `%{input_name}` input options: `%{conflict_code}`"
-    internal_arguments:
+    internals:
       checks:
         type:
-          default_error: "[%{service_class_name}] Wrong type of internal argument `%{internal_argument_name}`, expected `%{expected_type}`, got `%{given_type}`"
-    output_arguments:
+          default_error: "[%{service_class_name}] Wrong type of internal attribute `%{internal_name}`, expected `%{expected_type}`, got `%{given_type}`"
+    outputs:
       checks:
         type:
-          default_error: "[%{service_class_name}] Wrong type of output argument `%{output_argument_name}`, expected `%{expected_type}`, got `%{given_type}`"
+          default_error: "[%{service_class_name}] Wrong type of output attribute `%{output_name}`, expected `%{expected_type}`, got `%{given_type}`"
       tools:
         conflicts:
           error: "[%{service_class_name}] Conflict between internal and output attributes `%{overlapping_attributes}`"

data/lib/servactory/base.rb

@@ -4,10 +4,10 @@ module Servactory
   class Base
     include Configuration::DSL
     include Context::DSL
-    include InputArguments::DSL
-    include InternalArguments::DSL
-    include OutputArguments::DSL
-    include MakeMethods::DSL
+    include Inputs::DSL
+    include Internals::DSL
+    include Outputs::DSL
+    include Methods::DSL
 
     private_class_method :new
   end

data/lib/servactory/configuration/factory.rb

@@ -3,16 +3,16 @@
 module Servactory
   module Configuration
     class Factory
-      def input_argument_error_class(input_argument_error_class)
-        Servactory.configuration.input_argument_error_class = input_argument_error_class
+      def input_error_class(input_error_class)
+        Servactory.configuration.input_error_class = input_error_class
       end
 
-      def output_argument_error_class(output_argument_error_class)
-        Servactory.configuration.output_argument_error_class = output_argument_error_class
+      def output_error_class(output_error_class)
+        Servactory.configuration.output_error_class = output_error_class
       end
 
-      def internal_argument_error_class(internal_argument_error_class)
-        Servactory.configuration.internal_argument_error_class = internal_argument_error_class
+      def internal_error_class(internal_error_class)
+        Servactory.configuration.internal_error_class = internal_error_class
       end
 
       def failure_class(failure_class)

data/lib/servactory/configuration/setup.rb

@@ -3,15 +3,15 @@
 module Servactory
   module Configuration
     class Setup
-      attr_accessor :input_argument_error_class,
-                    :internal_argument_error_class,
-                    :output_argument_error_class,
+      attr_accessor :input_error_class,
+                    :internal_error_class,
+                    :output_error_class,
                     :failure_class
 
       def initialize
-        @input_argument_error_class = Servactory::Errors::InputArgumentError
-        @internal_argument_error_class = Servactory::Errors::InternalArgumentError
-        @output_argument_error_class = Servactory::Errors::OutputArgumentError
+        @input_error_class = Servactory::Errors::InputError
+        @internal_error_class = Servactory::Errors::InternalError
+        @output_error_class = Servactory::Errors::OutputError
 
         @failure_class = Servactory::Errors::Failure
       end

data/lib/servactory/context/callable.rb

@@ -8,23 +8,23 @@ module Servactory
 
         assign_data_with(arguments)
 
-        input_arguments_workbench.find_unnecessary!
-        input_arguments_workbench.check_rules!
-        output_arguments_workbench.find_conflicts_in!(
-          collection_of_internal_arguments: collection_of_internal_arguments
+        inputs_workbench.find_unnecessary!
+        inputs_workbench.check_rules!
+        outputs_workbench.find_conflicts_in!(
+          collection_of_internals: collection_of_internals
         )
 
         prepare_data
 
-        input_arguments_workbench.check!
+        inputs_workbench.check!
 
-        make_methods_workbench.run!
+        methods_workbench.run!
 
         context_store.context.raise_first_fail
 
         Servactory::Result.prepare_for(
           context: context_store.context,
-          collection_of_output_arguments: collection_of_output_arguments
+          collection_of_outputs: collection_of_outputs
         )
       end
 
@@ -33,21 +33,21 @@ module Servactory
 
         assign_data_with(arguments)
 
-        input_arguments_workbench.find_unnecessary!
-        input_arguments_workbench.check_rules!
-        output_arguments_workbench.find_conflicts_in!(
-          collection_of_internal_arguments: collection_of_internal_arguments
+        inputs_workbench.find_unnecessary!
+        inputs_workbench.check_rules!
+        outputs_workbench.find_conflicts_in!(
+          collection_of_internals: collection_of_internals
         )
 
         prepare_data
 
-        input_arguments_workbench.check!
+        inputs_workbench.check!
 
-        make_methods_workbench.run!
+        methods_workbench.run!
 
         Servactory::Result.prepare_for(
           context: context_store.context,
-          collection_of_output_arguments: collection_of_output_arguments
+          collection_of_outputs: collection_of_outputs
         )
       end
 
@@ -56,21 +56,20 @@ module Servactory
       attr_reader :context_store
 
       def assign_data_with(arguments)
-        input_arguments_workbench.assign(
+        inputs_workbench.assign(
           context: context_store.context,
           arguments: arguments
         )
 
-        internal_arguments_workbench.assign(context: context_store.context)
-        output_arguments_workbench.assign(context: context_store.context)
-        make_methods_workbench.assign(context: context_store.context)
+        internals_workbench.assign(context: context_store.context)
+        outputs_workbench.assign(context: context_store.context)
+        methods_workbench.assign(context: context_store.context)
       end
 
       def prepare_data
-        input_arguments_workbench.prepare     # 1
-
-        output_arguments_workbench.prepare    # 2
-        internal_arguments_workbench.prepare  # 3
+        inputs_workbench.prepare      # 1
+        outputs_workbench.prepare     # 2
+        internals_workbench.prepare   # 3
       end
     end
   end

data/lib/servactory/context/configuration.rb

@@ -3,16 +3,16 @@
 module Servactory
   module Context
     class Configuration
-      def input_argument_error_class(input_argument_error_class)
-        Servactory.configuration.input_argument_error_class = input_argument_error_class
+      def input_error_class(input_error_class)
+        Servactory.configuration.input_error_class = input_error_class
       end
 
-      def output_argument_error_class(output_argument_error_class)
-        Servactory.configuration.output_argument_error_class = output_argument_error_class
+      def output_error_class(output_error_class)
+        Servactory.configuration.output_error_class = output_error_class
       end
 
-      def internal_argument_error_class(internal_argument_error_class)
-        Servactory.configuration.internal_argument_error_class = internal_argument_error_class
+      def internal_error_class(internal_error_class)
+        Servactory.configuration.internal_error_class = internal_error_class
       end
 
       def failure_class(failure_class)

data/lib/servactory/context/workspace/inputs.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Context
+    module Workspace
+      class Inputs
+        def initialize(**)
+          # NOTE: Look at the file `lib/servactory/inputs/tools/prepare.rb`
+        end
+      end
+    end
+  end
+end

data/lib/servactory/context/workspace.rb

@@ -6,26 +6,28 @@ module Servactory
       attr_reader :inputs
 
       def errors
-        @errors ||= Errors.new
+        @errors ||= Servactory::Errors::Collection.new
       end
 
       def assign_inputs(inputs)
         @inputs = inputs
       end
 
-      def fail_input!(input_attribute_name, message)
-        raise Servactory.configuration.input_argument_error_class,
-              Error.new(type: :input, attribute_name: input_attribute_name, message: message).message
+      def fail_input!(input_name, message:)
+        raise Servactory.configuration.input_error_class.new(
+          input_name: input_name,
+          message: message
+        )
       end
 
-      def fail!(error)
-        errors << Error.new(type: :fail, message: error)
+      def fail!(message:, meta: nil)
+        errors << Servactory.configuration.failure_class.new(message: message, meta: meta)
       end
 
       def raise_first_fail
         return if (tmp_errors = errors.for_fails.not_blank).empty?
 
-        raise Servactory.configuration.failure_class, tmp_errors.first.message
+        raise tmp_errors.first
       end
     end
   end

data/lib/servactory/errors/base.rb

@@ -2,6 +2,7 @@
 
 module Servactory
   module Errors
-    class Base < StandardError; end
+    class Base < StandardError
+    end
   end
 end

data/lib/servactory/errors/collection.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class Collection
+      # NOTE: http://words.steveklabnik.com/beware-subclassing-ruby-core-classes
+      extend Forwardable
+      def_delegators :@collection, :<<, :to_a, :filter, :reject, :empty?, :first
+
+      def initialize(collection = Set.new)
+        @collection = collection
+      end
+
+      def not_blank
+        Collection.new(reject(&:blank?))
+      end
+
+      def for_fails
+        filtered = filter { |error| error.is_a?(Failure) }
+
+        Collection.new(filtered)
+      end
+    end
+  end
+end

data/lib/servactory/errors/failure.rb

@@ -2,6 +2,16 @@
 
 module Servactory
   module Errors
-    class Failure < Servactory::Errors::Base; end
+    class Failure < Base
+      attr_reader :message,
+                  :meta
+
+      def initialize(message:, meta: nil)
+        @message = message
+        @meta = meta
+
+        super(message)
+      end
+    end
   end
 end

data/lib/servactory/errors/input_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class InputError < Base
+      attr_reader :message,
+                  :input_name
+
+      def initialize(message:, input_name: nil)
+        @message = message
+        @input_name = input_name&.to_sym
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/servactory/errors/internal_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class InternalError < Base
+      attr_reader :message
+
+      def initialize(message:)
+        @message = message
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/servactory/errors/output_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class OutputError < Base
+      attr_reader :message
+
+      def initialize(message:)
+        @message = message
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/servactory/{input_arguments → inputs}/checks/base.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 module Servactory
-  module InputArguments
+  module Inputs
     module Checks
       class Base
         protected
 
-        def add_error(message, **arguments)
-          message = message.call(**arguments) if message.is_a?(Proc)
+        def add_error(message, **attributes)
+          message = message.call(**attributes) if message.is_a?(Proc)
 
           errors << message
         end

data/lib/servactory/{input_arguments → inputs}/checks/errors.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Servactory
-  module InputArguments
+  module Inputs
     module Checks
       class Errors
         # NOTE: http://words.steveklabnik.com/beware-subclassing-ruby-core-classes

data/lib/servactory/{input_arguments → inputs}/checks/inclusion.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Servactory
-  module InputArguments
+  module Inputs
     module Checks
       class Inclusion < Base
         DEFAULT_MESSAGE = lambda do |service_class_name:, input:, value:|
           I18n.t(
-            "servactory.input_arguments.checks.inclusion.default_error",
+            "servactory.inputs.checks.inclusion.default_error",
             service_class_name: service_class_name,
             input_name: input.name,
             input_inclusion: input.inclusion[:in],