servactory 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ef221cf056da7376cec0a04e0dd92ddba328f34163fe050d74e3f0158eb1e17
-  data.tar.gz: 2bc1b62867fb2e6c09692bfd76c315bbf739202b445fc99e46511b6dd3437c6f
+  metadata.gz: d4ffa3b926585163837e461a8a1b129a81f951f88a8d715dd6e74297e0a37ddd
+  data.tar.gz: 1d1a3326828e282ad0f46bc76e2754fb44e0dbd5f2e00c452cd6e856866bcbbd
 SHA512:
-  metadata.gz: 126ca96b81dcbea82334b216f9b911c33282aca4c66c26d511655339cd56184ce6fac7475420184f6fcd4681d34afe210f8ebffe18e0894c635c6bcbdc045754
-  data.tar.gz: 22675c25495d5e2b3edfda926c5392985294c78c03e0e2d6f8930b8a8d5a7618dc94dd7cec413fba5b6ce234d23bbeea44c68cf58fc95d0e223c73c437721b43
+  metadata.gz: 07c4e1f255a4fabe953a3c1381229000b564b80fc0e4f1c08547fed23dcc9cb9b31ebab678d76f894ce55e5506120d412fab26bf214f433f00cf43d958b502d7
+  data.tar.gz: 85cadb2169b968a0e9cda6f9279d9be37b01acdc0f7f91ca2b7f8458e89a219213ad317b84002d1b7684bb695a73b4c5a3a6c092a4e3a61c05984e2ee027a164

data/README.md

@@ -2,6 +2,28 @@
 
 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)
+
+## Contents
+
+- [Requirements](https://github.com/afuno/servactory/edit/main/README.md#requirements)
+- [Getting started](https://github.com/afuno/servactory/edit/main/README.md#getting-started)
+  - [Conventions](https://github.com/afuno/servactory/edit/main/README.md#conventions)
+  - [Installation](https://github.com/afuno/servactory/edit/main/README.md#installation)
+  - [Preparation](https://github.com/afuno/servactory/edit/main/README.md#preparation)
+- [Usage](https://github.com/afuno/servactory/edit/main/README.md#usage)
+  - [Minimal example](https://github.com/afuno/servactory#minimal-example)
+  - [Input attributes](https://github.com/afuno/servactory#input-attributes)
+    - [Isolated usage](https://github.com/afuno/servactory#isolated-usage)
+    - [As an internal argument](https://github.com/afuno/servactory#isolated-usage)
+    - [Optional inputs](https://github.com/afuno/servactory#optional-inputs)
+    - [An array of specific values](https://github.com/afuno/servactory#an-array-of-specific-values)
+    - [Inclusion](https://github.com/afuno/servactory#inclusion)
+    - [Must](https://github.com/afuno/servactory#must)
+  - [Output attributes](https://github.com/afuno/servactory/edit/main/README.md#output-attributes)
+  - [Internal attributes](https://github.com/afuno/servactory/edit/main/README.md#internal-attributes)
+  - [Result](https://github.com/afuno/servactory/edit/main/README.md#result)
+
 ## Requirements
 
 - Ruby >= 2.7
@@ -70,7 +92,7 @@ end
 ### Minimal example
 
 ```ruby
-class SendService < ApplicationService::Base
+class MinimalService < ApplicationService::Base
   stage { make :something }
   
   private
@@ -81,36 +103,158 @@ class SendService < ApplicationService::Base
 end
 ```
 
-### Inputs
+### Input attributes
+
+#### Isolated usage
+
+With this approach, all input attributes are available only from `inputs`. This is default behaviour.
 
 ```ruby
-class SendService < ApplicationService::Base
+class UsersService::Accept < ApplicationService::Base
   input :user, type: User
   
-  stage { make :something }
+  stage { make :accept! }
   
   private
   
-  def something
-    # ...
+  def accept!
+    inputs.user.accept!
+  end
+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
+  
+  stage { make :accept! }
+  
+  private
+  
+  def accept!
+    user.accept!
   end
 end
 ```
 
-### Outputs
+#### 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, internal: true
+  input :middle_name, type: String, required: false
+  input :last_name, type: String, internal: true
+
+  # ...
+end
+```
+
+#### An array of specific values
+
+```ruby
+class PymentsService::Send < ApplicationService::Base
+  input :invoice_numbers, type: String, array: true
+
+  # ...
+end
+```
+
+#### Inclusion
+
+```ruby
+class EventService::Send < ApplicationService::Base
+  input :event_name, type: String, inclusion: %w[created rejected approved]
+
+  # ...
+end
+```
+
+#### Must
+
+Sometimes there are cases that require the implementation of a specific input attribute check. In such cases `must` can help.
 
 ```ruby
-class SendService < ApplicationService::Base
+class PymentsService::Send < ApplicationService::Base
+  input :invoice_numbers,
+        type: String,
+        array: true,
+        must: {
+          be_6_characters: {
+            is: ->(value:) { value.all? { |id| id.size == 6 } }
+          }
+        }
+
+  # ...
+end
+```
+
+### Output attributes
+
+```ruby
+class NotificationService::Create < ApplicationService::Base
   input :user, type: User
   
   output :notification, type: Notification
   
-  stage { make :something }
+  stage { make :create_notification! }
   
   private
   
-  def something
-    self.notification = Notification.create!
+  def create_notification!
+    self.notification = Notification.create!(user: inputs.user)
+  end
+end
+```
+
+### Internal attributes
+
+```ruby
+class NotificationService::Create < ApplicationService::Base
+  input :user, type: User
+
+  internal :inviter, type: User
+  
+  output :notification, type: Notification
+  
+  stage do
+    make :assign_inviter
+    make :create_notification!
+  end
+  
+  private
+  
+  def assign_inviter
+    self.inviter = user.inviter
+  end
+  
+  def create_notification!
+    self.notification = Notification.create!(user: inputs.user, inviter:)
   end
 end
 ```
+
+### Result
+
+All services have the result of their work. For example, in case of success this call:
+
+```ruby
+service_result = NotificationService::Create.call!(user: User.first)
+```
+
+Will return this:
+
+```ruby
+#<Servactory::Result:0x0000000112c00748 @notification=...>
+```
+
+And then you can work with this result, for example, in this way:
+
+```ruby
+Notification::SendJob.perform_later(service_result.notification.id)
+```

data/lib/servactory/context/dsl.rb

@@ -35,11 +35,16 @@ module Servactory
 
         attr_reader :context_store
 
-        def assign_data_with(arguments)
-          input_arguments_workbench.assign(context: context_store.context, arguments: arguments)  # 1
-          internal_arguments_workbench.assign(context: context_store.context)                     # 2
-          output_arguments_workbench.assign(context: context_store.context)                       # 3
-          stage_handyman&.assign(context: context_store.context)                                  # 4
+        def assign_data_with(arguments) # rubocop:disable Metrics/AbcSize
+          input_arguments_workbench.assign(
+            context: context_store.context,
+            arguments: arguments,
+            collection_of_input_options: collection_of_input_options
+          )
+
+          internal_arguments_workbench.assign(context: context_store.context)
+          output_arguments_workbench.assign(context: context_store.context)
+          stage_handyman&.assign(context: context_store.context)
         end
 
         def prepare_data

data/lib/servactory/input_arguments/checks/inclusion.rb

@@ -5,7 +5,7 @@ module Servactory
     module Checks
       class Inclusion < Base
         DEFAULT_MESSAGE = lambda do |service_class_name:, input:|
-          "[#{service_class_name}] Wrong value in `#{input.name}`, must be one of `#{input.inclusion}`"
+          "[#{service_class_name}] Wrong value in `#{input.name}`, must be one of `#{input.inclusion[:in]}`"
         end
 
         private_constant :DEFAULT_MESSAGE
@@ -31,7 +31,7 @@ module Servactory
         end
 
         def check
-          return if @input.inclusion.include?(@value)
+          return if @input.inclusion[:in].include?(@value)
 
           add_error(
             DEFAULT_MESSAGE,

data/lib/servactory/input_arguments/checks/must.rb

@@ -32,7 +32,7 @@ module Servactory
           @check_options = check_options
         end
 
-        def check
+        def check # rubocop:disable Metrics/MethodLength
           @check_options.each do |code, options|
             message = call_or_fetch_message_from(code, options)
 
@@ -57,10 +57,12 @@ module Servactory
           return if check.call(value: @value)
 
           message.presence || DEFAULT_MESSAGE
-        rescue StandardError => _e
+        rescue StandardError => e
           message_text =
             "[#{@context.class.name}] Syntax error inside `#{code}` of `#{@input.name}` input"
 
+          puts "#{message_text}: #{e}"
+
           add_error(
             message_text,
             service_class_name: @context.class.name,

data/lib/servactory/input_arguments/checks/type.rb

@@ -6,7 +6,15 @@ module Servactory
       class Type < Base
         DEFAULT_MESSAGE = lambda do |service_class_name:, input:, expected_type:, given_type:|
           if input.array?
-            "[#{service_class_name}] Wrong type in input array `#{input.name}`, expected `#{expected_type}`"
+            array_message = input.array[:message]
+
+            if array_message.is_a?(Proc)
+              array_message.call(input: input, expected_type: expected_type)
+            elsif array_message.is_a?(String) && array_message.present?
+              array_message
+            else
+              "[#{service_class_name}] Wrong type in input array `#{input.name}`, expected `#{expected_type}`"
+            end
           else
             "[#{service_class_name}] Wrong type of input `#{input.name}`, " \
               "expected `#{expected_type}`, " \

data/lib/servactory/input_arguments/dsl.rb

@@ -11,13 +11,21 @@ module Servactory
         private
 
         def input(name, **options)
-          collection_of_input_arguments << InputArgument.new(name, **options)
+          collection_of_input_arguments << InputArgument.new(
+            name,
+            collection_of_options: collection_of_input_options,
+            **options
+          )
         end
 
         def collection_of_input_arguments
           @collection_of_input_arguments ||= Collection.new
         end
 
+        def collection_of_input_options
+          @collection_of_input_options ||= OptionsCollection.new
+        end
+
         def input_arguments_workbench
           @input_arguments_workbench ||= Workbench.work_with(collection_of_input_arguments)
         end

data/lib/servactory/input_arguments/input_argument.rb

@@ -2,73 +2,187 @@
 
 module Servactory
   module InputArguments
-    class InputArgument
+    class InputArgument # rubocop:disable Metrics/ClassLength
+      ARRAY_DEFAULT_VALUE = ->(is: false, message: nil) { { is: is, message: message } }
+
       attr_reader :name,
-                  :types,
-                  :inclusion,
-                  :must,
-                  :array,
-                  :required,
-                  :internal,
-                  :default
-
-      def initialize(name, type:, **options)
+                  :collection_of_options,
+                  :types
+
+      def initialize(name, collection_of_options:, type:, **options)
         @name = name
+        @collection_of_options = collection_of_options
         @types = Array(type)
 
-        @inclusion = options.fetch(:inclusion, nil)
-        @must = options.fetch(:must, nil)
-        @array = options.fetch(:array, false)
-        @required = options.fetch(:required, true)
-        @internal = options.fetch(:internal, false)
-        @default = options.fetch(:default, nil)
+        add_basic_options_with(options)
+
+        @collection_of_options.each do |option|
+          self.class.attr_reader(:"#{option.name}")
+
+          instance_variable_set(:"@#{option.name}", option.value)
+        end
       end
 
-      def options_for_checks
-        {
-          types: types,
-          inclusion: inclusion,
-          must: must,
-          required: required,
-          # internal: internal,
-          default: default
-        }
+      def add_basic_options_with(options)
+        # Check Class: Servactory::InputArguments::Checks::Required
+        add_required_option_with(options)
+
+        # Check Class: Servactory::InputArguments::Checks::Type
+        add_array_option_with(options)
+        add_default_option_with(options)
+
+        # Check Class: Servactory::InputArguments::Checks::Inclusion
+        add_inclusion_option_with(options)
+
+        # Check Class: Servactory::InputArguments::Checks::Must
+        add_must_option_with(options)
+
+        # Check Class: nil
+        add_internal_option_with(options)
       end
 
-      def conflict_code
-        return :required_vs_default if required? && default_value_present?
-        return :array_vs_array if array? && types.include?(Array)
-        return :array_vs_inclusion if array? && inclusion_present?
+      def add_required_option_with(options) # rubocop:disable Metrics/MethodLength
+        collection_of_options << Option.new(
+          name: :required,
+          input: self,
+          check_class: Servactory::InputArguments::Checks::Required,
+          define_input_methods: lambda do
+            <<-RUBY
+              def required?
+                Servactory::Utils.boolean?(required[:is])
+              end
 
-        nil
+              def optional?
+                !required?
+              end
+            RUBY
+          end,
+          define_conflicts: lambda do
+            <<-RUBY
+              return :required_vs_default if required? && default_value_present?
+            RUBY
+          end,
+          need_for_checks: true,
+          value_key: :is,
+          value_fallback: true,
+          **options
+        )
       end
 
-      def inclusion_present?
-        inclusion.is_a?(Array) && inclusion.present?
+      def add_array_option_with(options) # rubocop:disable Metrics/MethodLength
+        collection_of_options << Option.new(
+          name: :array,
+          input: self,
+          check_class: Servactory::InputArguments::Checks::Type,
+          define_input_methods: lambda do
+            <<-RUBY
+              def array?
+                Servactory::Utils.boolean?(array[:is])
+              end
+            RUBY
+          end,
+          define_conflicts: lambda do
+            <<-RUBY
+              return :array_vs_array if array? && types.include?(Array)
+              return :array_vs_inclusion if array? && inclusion_present?
+            RUBY
+          end,
+          need_for_checks: false,
+          value_key: :is,
+          value_fallback: false,
+          **options
+        )
       end
 
-      def must_present?
-        must.present?
+      def add_default_option_with(options) # rubocop:disable Metrics/MethodLength
+        collection_of_options << Option.new(
+          name: :default,
+          input: self,
+          check_class: Servactory::InputArguments::Checks::Type,
+          define_input_methods: lambda do
+            <<-RUBY
+              def default_value_present?
+                !default.nil?
+              end
+            RUBY
+          end,
+          need_for_checks: true,
+          value_fallback: nil,
+          with_advanced_mode: false,
+          **options
+        )
       end
 
-      def array?
-        Servactory::Utils.boolean?(array)
+      def add_inclusion_option_with(options) # rubocop:disable Metrics/MethodLength
+        collection_of_options << Option.new(
+          name: :inclusion,
+          input: self,
+          check_class: Servactory::InputArguments::Checks::Inclusion,
+          define_input_methods: lambda do
+            <<-RUBY
+              def inclusion_present?
+                inclusion[:in].is_a?(Array) && inclusion[:in].present?
+              end
+            RUBY
+          end,
+          need_for_checks: true,
+          value_key: :in,
+          value_fallback: nil,
+          **options
+        )
       end
 
-      def required?
-        Servactory::Utils.boolean?(required)
+      def add_must_option_with(options) # rubocop:disable Metrics/MethodLength
+        collection_of_options << Option.new(
+          name: :must,
+          input: self,
+          check_class: Servactory::InputArguments::Checks::Must,
+          define_input_methods: lambda do
+            <<-RUBY
+              def must_present?
+                must.present?
+              end
+            RUBY
+          end,
+          need_for_checks: true,
+          value_key: :is,
+          value_fallback: nil,
+          with_advanced_mode: false,
+          **options
+        )
       end
 
-      def optional?
-        !required?
+      def add_internal_option_with(options) # rubocop:disable Metrics/MethodLength
+        collection_of_options << Option.new(
+          name: :internal,
+          input: self,
+          define_input_methods: lambda do
+            <<-RUBY
+              def internal?
+                Servactory::Utils.boolean?(internal[:is])
+              end
+            RUBY
+          end,
+          need_for_checks: false,
+          check_class: nil,
+          value_key: :is,
+          value_fallback: false,
+          **options
+        )
       end
 
-      def internal?
-        Servactory::Utils.boolean?(internal)
+      def options_for_checks
+        {
+          types: types
+        }.merge(
+          collection_of_options.options_for_checks
+        )
       end
 
-      def default_value_present?
-        !default.nil?
+      def conflict_code
+        instance_eval(collection_of_options.defined_conflicts)
+
+        nil
       end
 
       def with_conflicts?

data/lib/servactory/input_arguments/option.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    class Option
+      DEFAULT_VALUE = ->(key:, value:, message: nil) { { key => value, message: message } }
+
+      private_constant :DEFAULT_VALUE
+
+      attr_reader :name,
+                  :check_class,
+                  :define_conflicts,
+                  :need_for_checks,
+                  :value_key,
+                  :value
+
+      def initialize(
+        name:,
+        input:,
+        check_class:,
+        need_for_checks:,
+        value_fallback:,
+        value_key: nil,
+        define_input_methods: nil,
+        define_conflicts: nil,
+        with_advanced_mode: true,
+        **options
+      ) # do
+        @name = name.to_sym
+        @check_class = check_class
+        @define_conflicts = define_conflicts
+        @need_for_checks = need_for_checks
+        @value_key = value_key
+
+        @value = prepare_value_for(options, value_fallback: value_fallback, with_advanced_mode: with_advanced_mode)
+
+        input.instance_eval(define_input_methods.call) if define_input_methods.present?
+      end
+
+      def need_for_checks?
+        need_for_checks
+      end
+
+      private
+
+      def prepare_value_for(options, value_fallback:, with_advanced_mode:)
+        return options.fetch(@name, value_fallback) unless with_advanced_mode
+
+        prepare_advanced_for(
+          value: options.fetch(@name, DEFAULT_VALUE.call(key: value_key, value: value_fallback)),
+          value_fallback: value_fallback
+        )
+      end
+
+      def prepare_advanced_for(value:, value_fallback:)
+        if value.is_a?(Hash)
+          DEFAULT_VALUE.call(
+            key: value_key,
+            value: value.fetch(value_key, value_fallback),
+            message: value.fetch(:message, nil)
+          )
+        else
+          DEFAULT_VALUE.call(key: value_key, value: value)
+        end
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/options_collection.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Servactory
+  module InputArguments
+    class OptionsCollection
+      # NOTE: http://words.steveklabnik.com/beware-subclassing-ruby-core-classes
+      extend Forwardable
+      def_delegators :@collection, :<<, :each, :select, :map
+
+      def initialize(*)
+        @collection = []
+      end
+
+      def check_classes
+        select { |option| option.check_class.present? }.map(&:check_class).uniq
+      end
+
+      def options_for_checks
+        select(&:need_for_checks?).to_h do |option|
+          value = if option.value.is_a?(Hash)
+                    option.value.key?(:is) ? option.value.fetch(:is) : option.value
+                  else
+                    option.value
+                  end
+
+          [option.name, value]
+        end
+      end
+
+      def defined_conflicts
+        map { |option| option.define_conflicts&.call }.reject(&:blank?).uniq.join
+      end
+    end
+  end
+end

data/lib/servactory/input_arguments/tools/check.rb

@@ -8,10 +8,11 @@ module Servactory
           new(...).check!
         end
 
-        def initialize(context, incoming_arguments, collection_of_input_arguments)
+        def initialize(context, incoming_arguments, collection_of_input_arguments, collection_of_input_options)
           @context = context
           @incoming_arguments = incoming_arguments
           @collection_of_input_arguments = collection_of_input_arguments
+          @collection_of_input_options = collection_of_input_options
 
           @errors = []
         end
@@ -58,20 +59,15 @@ module Servactory
         ########################################################################
 
         def check_classes
-          [
-            Servactory::InputArguments::Checks::Required,
-            Servactory::InputArguments::Checks::Type,
-            Servactory::InputArguments::Checks::Inclusion,
-            Servactory::InputArguments::Checks::Must
-          ]
+          @collection_of_input_options.check_classes
         end
 
         ########################################################################
 
         def raise_errors
-          return if @errors.empty?
+          return if (tmp_errors = @errors.reject(&:blank?).uniq).empty?
 
-          raise Servactory.configuration.input_argument_error_class, @errors.first
+          raise Servactory.configuration.input_argument_error_class, tmp_errors.first
         end
       end
     end

data/lib/servactory/input_arguments/workbench.rb

@@ -11,9 +11,10 @@ module Servactory
         @collection_of_input_arguments = collection_of_input_arguments
       end
 
-      def assign(context:, arguments:)
+      def assign(context:, arguments:, collection_of_input_options:)
         @context = context
         @incoming_arguments = arguments
+        @collection_of_input_options = collection_of_input_options
       end
 
       def find_unnecessary!
@@ -29,12 +30,14 @@ module Servactory
       end
 
       def check!
-        Tools::Check.check!(context, @incoming_arguments, collection_of_input_arguments)
+        Tools::Check.check!(context, @incoming_arguments, collection_of_input_arguments, collection_of_input_options)
       end
 
       private
 
-      attr_reader :context, :collection_of_input_arguments
+      attr_reader :context,
+                  :collection_of_input_arguments,
+                  :collection_of_input_options
     end
   end
 end

data/lib/servactory/version.rb

@@ -3,7 +3,7 @@
 module Servactory
   module VERSION
     MAJOR = 1
-    MINOR = 2
+    MINOR = 4
     PATCH = 0
 
     STRING = [MAJOR, MINOR, PATCH].join(".")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: servactory
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Anton Sokolov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-05 00:00:00.000000000 Z
+date: 2023-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -178,6 +178,8 @@ files:
 - lib/servactory/input_arguments/collection.rb
 - lib/servactory/input_arguments/dsl.rb
 - lib/servactory/input_arguments/input_argument.rb
+- lib/servactory/input_arguments/option.rb
+- lib/servactory/input_arguments/options_collection.rb
 - lib/servactory/input_arguments/tools/check.rb
 - lib/servactory/input_arguments/tools/find_unnecessary.rb
 - lib/servactory/input_arguments/tools/prepare.rb