servactory 2.16.1 → 3.0.0.rc2

data/lib/servactory/actions/tools/runner.rb

@@ -3,16 +3,48 @@
 module Servactory
   module Actions
     module Tools
+      # Executes service actions within stages.
+      #
+      # ## Purpose
+      #
+      # Orchestrates the execution of service actions, handling stage wrappers,
+      # rollbacks, and conditional execution (only_if/only_unless). Provides
+      # the core execution engine for Servactory services.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # Runner.run!(context, collection_of_stages)
+      # ```
+      #
+      # ## Integration
+      #
+      # Called by Servactory::Context::Callable to execute all actions
+      # defined in a service. Works with Stages::Collection and Actions::Collection.
       class Runner
+        # Runs the service actions.
+        #
+        # @param context [Object] The service context
+        # @param collection_of_stages [Stages::Collection] The stages to execute
+        # @return [void]
         def self.run!(...)
           new(...).run!
         end
 
+        # Creates a new runner instance.
+        #
+        # @param context [Object] The service context with inputs/internals/outputs
+        # @param collection_of_stages [Stages::Collection] Collection of stages to execute
         def initialize(context, collection_of_stages)
           @context = context
           @collection_of_stages = collection_of_stages
         end
 
+        # Executes all stages in position order.
+        #
+        # Falls back to calling the service's `call` method if no stages defined.
+        #
+        # @return [void]
         def run!
           return use_call if @collection_of_stages.empty?
 
@@ -23,24 +55,42 @@ module Servactory
 
         private
 
+        # Falls back to the service's call method when no stages defined.
+        #
+        # @return [void]
         def use_call
           @context.send(:call)
         end
 
+        # Executes a single stage with its actions.
+        #
+        # Handles wrapper execution, rollbacks, and conditional skipping.
+        #
+        # @param stage [Stages::Stage] The stage to execute
+        # @return [void]
         def call_stage(stage)
-          return if unnecessary_for_stage?(stage)
+          return if should_skip?(stage)
 
-          wrapper = stage.wrapper
-          rollback = stage.rollback
           actions = stage.actions.sorted_by_position
 
-          if wrapper.is_a?(Proc)
-            call_wrapper_with_actions(wrapper, rollback, actions)
+          if stage.wrapper.is_a?(Proc)
+            call_wrapper_with_actions(stage.wrapper, stage.rollback, actions)
+          elsif stage.rollback.present?
+            call_actions_with_rollback(stage.rollback, actions)
           else
             call_actions(actions)
           end
         end
 
+        # Executes actions within a wrapper proc.
+        #
+        # Handles exceptions by calling rollback if defined,
+        # otherwise fails the service with the exception details.
+        #
+        # @param wrapper [Proc] The wrapper proc (e.g., transaction block)
+        # @param rollback [Symbol, nil] Optional rollback method name
+        # @param actions [Collection] Actions to execute within wrapper
+        # @return [void]
         def call_wrapper_with_actions(wrapper, rollback, actions) # rubocop:disable Metrics/MethodLength
           wrapper.call(methods: -> { call_actions(actions) }, context: @context)
         rescue StandardError => e
@@ -56,47 +106,80 @@ module Servactory
           end
         end
 
+        # Executes actions with rollback support but no wrapper.
+        #
+        # If an exception occurs, calls the rollback method with the exception.
+        #
+        # @param rollback [Symbol] The rollback method name
+        # @param actions [Collection] Actions to execute
+        # @return [void]
+        def call_actions_with_rollback(rollback, actions)
+          call_actions(actions)
+        rescue StandardError => e
+          @context.send(rollback, e)
+        end
+
+        # Executes a collection of actions in order.
+        #
+        # @param actions [Collection] Actions to execute
+        # @return [void]
         def call_actions(actions)
           actions.each do |action|
-            next if unnecessary_for_make?(action)
+            next if should_skip?(action)
 
             call_action(action)
           end
         end
 
+        # Executes a single action by name.
+        #
+        # @param action [Action] The action to execute
+        # @return [void]
+        # @raise [StandardError] Re-raises unless handled by rescue handler
         def call_action(action)
           @context.send(action.name)
         rescue StandardError => e
           rescue_with_handler(e) || raise
         end
 
-        def unnecessary_for_stage?(stage)
-          condition = stage.condition
-          is_condition_opposite = stage.is_condition_opposite
-
-          result = checks_passed_for?(condition)
-
-          is_condition_opposite ? !result : result
-        end
-
-        def unnecessary_for_make?(make_action)
-          condition = make_action.condition
-          is_condition_opposite = make_action.is_condition_opposite
-
-          result = checks_passed_for?(condition)
-
-          is_condition_opposite ? !result : result
+        # Determines if an entity (stage or action) should be skipped.
+        #
+        # Uses the entity's condition and is_condition_opposite flag:
+        # - only_if: skips if condition is NOT met
+        # - only_unless: skips if condition IS met
+        #
+        # @param entity [Stages::Stage, Action] The entity to check
+        # @return [Boolean] true if entity should be skipped
+        def should_skip?(entity)
+          condition_result = condition_met?(entity.condition)
+
+          # only_if (is_condition_opposite = false): skip if condition is NOT met
+          # only_unless (is_condition_opposite = true): skip if condition IS met
+          entity.is_condition_opposite ? condition_result : !condition_result
         end
 
-        def checks_passed_for?(condition)
-          return false if condition.nil?
-          return !Servactory::Utils.true?(condition) unless condition.is_a?(Proc)
-
-          !condition.call(context: @context)
+        # Evaluates a condition value.
+        #
+        # Handles nil (always true), boolean, and Proc conditions.
+        #
+        # @param condition [Proc, Boolean, nil] The condition to evaluate
+        # @return [Boolean] true if condition is met
+        def condition_met?(condition)
+          return true if condition.nil?
+
+          if condition.is_a?(Proc)
+            condition.call(context: @context)
+          else
+            Servactory::Utils.true?(condition)
+          end
         end
 
+        # Attempts to handle an exception with configured rescue handlers.
+        #
+        # @param exception [Exception] The exception to handle
+        # @return [Exception, nil] The exception if handled, nil otherwise
         def rescue_with_handler(exception) # rubocop:disable Metrics/MethodLength
-          _, handler = @context.class.config.action_rescue_handlers.reverse_each.detect do |class_or_name, _|
+          _, handler = @context.config.action_rescue_handlers.reverse_each.detect do |class_or_name, _|
             if (detected_exception = Servactory::Utils.constantize_class(class_or_name))
               detected_exception === exception # rubocop:disable Style/CaseEquality
             end

data/lib/servactory/base.rb

@@ -2,13 +2,7 @@
 
 module Servactory
   class Base
-    include Configuration::DSL
-    include Info::DSL
-    include Context::DSL
-    include Inputs::DSL
-    include Internals::DSL
-    include Outputs::DSL
-    include Actions::DSL
+    include Servactory::DSL
 
     private_class_method :new
   end

data/lib/servactory/configuration/actions/aliases/collection.rb

@@ -12,6 +12,11 @@ module Servactory
           def initialize(*)
             @collection = Set.new
           end
+
+          def initialize_dup(original)
+            super
+            @collection = original.instance_variable_get(:@collection).dup
+          end
         end
       end
     end

data/lib/servactory/configuration/actions/rescue_handlers/collection.rb

@@ -12,6 +12,11 @@ module Servactory
           def initialize(*)
             @collection = Set.new
           end
+
+          def initialize_dup(original)
+            super
+            @collection = original.instance_variable_get(:@collection).dup
+          end
         end
       end
     end

data/lib/servactory/configuration/actions/shortcuts/collection.rb

@@ -13,6 +13,11 @@ module Servactory
             @collection = {}
           end
 
+          def initialize_dup(original)
+            super
+            @collection = original.instance_variable_get(:@collection).dup
+          end
+
           alias merge merge!
 
           def shortcuts

data/lib/servactory/configuration/collection_mode/class_names_collection.rb

@@ -11,6 +11,11 @@ module Servactory
         def initialize(collection)
           @collection = collection
         end
+
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+        end
       end
     end
   end

data/lib/servactory/configuration/config.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Configuration
+    class Config
+      attr_accessor :input_exception_class,
+                    :internal_exception_class,
+                    :output_exception_class,
+                    :failure_class,
+                    :success_class,
+                    :result_class,
+                    :action_shortcuts,
+                    :action_aliases,
+                    :input_option_helpers,
+                    :internal_option_helpers,
+                    :output_option_helpers,
+                    :collection_mode_class_names,
+                    :hash_mode_class_names,
+                    :action_rescue_handlers,
+                    :i18n_root_key,
+                    :predicate_methods_enabled
+
+      def initialize_dup(original) # rubocop:disable Metrics/AbcSize
+        super
+        @action_shortcuts = original.action_shortcuts.dup
+        @action_aliases = original.action_aliases.dup
+        @input_option_helpers = original.input_option_helpers.dup
+        @internal_option_helpers = original.internal_option_helpers.dup
+        @output_option_helpers = original.output_option_helpers.dup
+        @collection_mode_class_names = original.collection_mode_class_names.dup
+        @hash_mode_class_names = original.hash_mode_class_names.dup
+        @action_rescue_handlers = original.action_rescue_handlers.dup
+      end
+    end
+  end
+end

data/lib/servactory/configuration/configurable.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Configuration
+    module Configurable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def self.extended(base)
+          base.instance_variable_set(:@config, base.send(:build_default_config))
+        end
+
+        attr_reader :config
+
+        private
+
+        def build_default_config # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          Config.new.tap do |config|
+            # NOTE: Internal (MUST be first - used by option_helpers)
+            config.collection_mode_class_names =
+              CollectionMode::ClassNamesCollection.new(default_collection_mode_class_names)
+            config.hash_mode_class_names =
+              HashMode::ClassNamesCollection.new(default_hash_mode_class_names)
+
+            # NOTE: Exception classes
+            config.input_exception_class = Servactory::Exceptions::Input
+            config.internal_exception_class = Servactory::Exceptions::Internal
+            config.output_exception_class = Servactory::Exceptions::Output
+            config.failure_class = Servactory::Exceptions::Failure
+            config.success_class = Servactory::Exceptions::Success
+
+            # NOTE: Result
+            config.result_class = Servactory::Result
+
+            # NOTE: Actions
+            config.action_shortcuts = Actions::Shortcuts::Collection.new
+            config.action_aliases = Actions::Aliases::Collection.new
+
+            # NOTE: Option helpers (uses collection_mode_class_names)
+            config.input_option_helpers =
+              OptionHelpers::OptionHelpersCollection.new(default_input_option_helpers(config))
+            config.internal_option_helpers =
+              OptionHelpers::OptionHelpersCollection.new(default_internal_option_helpers(config))
+            config.output_option_helpers =
+              OptionHelpers::OptionHelpersCollection.new(default_output_option_helpers(config))
+
+            # NOTE: Other
+            config.action_rescue_handlers = Actions::RescueHandlers::Collection.new
+            config.i18n_root_key = "servactory"
+            config.predicate_methods_enabled = true
+          end
+        end
+
+        def default_collection_mode_class_names
+          Set[Array, Set]
+        end
+
+        def default_hash_mode_class_names
+          Set[Hash]
+        end
+
+        def default_input_option_helpers(config)
+          Set[
+            Servactory::Maintenance::Attributes::OptionHelper
+            .new(name: :optional, equivalent: { required: false }),
+            Servactory::ToolKit::DynamicOptions::ConsistsOf
+              .use(collection_mode_class_names: config.collection_mode_class_names),
+            Servactory::ToolKit::DynamicOptions::Schema.use(default_hash_mode_class_names:),
+            Servactory::ToolKit::DynamicOptions::Inclusion.use
+          ]
+        end
+
+        def default_internal_option_helpers(config)
+          Set[
+            Servactory::ToolKit::DynamicOptions::ConsistsOf
+            .use(collection_mode_class_names: config.collection_mode_class_names),
+            Servactory::ToolKit::DynamicOptions::Schema.use(default_hash_mode_class_names:),
+            Servactory::ToolKit::DynamicOptions::Inclusion.use
+          ]
+        end
+
+        def default_output_option_helpers(config)
+          Set[
+            Servactory::ToolKit::DynamicOptions::ConsistsOf
+            .use(collection_mode_class_names: config.collection_mode_class_names),
+            Servactory::ToolKit::DynamicOptions::Schema.use(default_hash_mode_class_names:),
+            Servactory::ToolKit::DynamicOptions::Inclusion.use
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/servactory/configuration/dsl.rb

@@ -5,38 +5,14 @@ module Servactory
     module DSL
       def self.included(base)
         base.extend(ClassMethods)
+        base.include(Configurable)
       end
 
       module ClassMethods
-        def inherited(child) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def inherited(child)
           super
 
-          child.config.input_exception_class = config.input_exception_class
-          child.config.internal_exception_class = config.internal_exception_class
-          child.config.output_exception_class = config.output_exception_class
-
-          child.config.success_class = config.success_class
-          child.config.failure_class = config.failure_class
-
-          child.config.result_class = config.result_class
-
-          child.config.collection_mode_class_names = config.collection_mode_class_names
-
-          child.config.input_option_helpers = config.input_option_helpers
-          child.config.internal_option_helpers = config.internal_option_helpers
-          child.config.output_option_helpers = config.output_option_helpers
-
-          child.config.action_aliases = config.action_aliases
-          child.config.action_shortcuts = config.action_shortcuts
-          child.config.action_rescue_handlers = config.action_rescue_handlers
-
-          child.config.i18n_root_key = config.i18n_root_key
-
-          child.config.predicate_methods_enabled = config.predicate_methods_enabled
-        end
-
-        def config
-          @config ||= Servactory::Configuration::Setup.new
+          child.instance_variable_set(:@config, config.dup)
         end
 
         private

data/lib/servactory/configuration/factory.rb

@@ -39,12 +39,24 @@ module Servactory
         raise_error_about_wrong_result_class_with(:result_class, result_class)
       end
 
-      def collection_mode_class_names(collection_mode_class_names)
-        @config.collection_mode_class_names.merge(collection_mode_class_names)
+      def action_shortcuts(array, hash = {}) # rubocop:disable Metrics/MethodLength
+        prepared = array.to_h do |action_shortcut|
+          [
+            action_shortcut,
+            {
+              prefix: action_shortcut,
+              suffix: nil
+            }
+          ]
+        end
+
+        prepared = prepared.merge(hash)
+
+        @config.action_shortcuts.merge(prepared)
       end
 
-      def hash_mode_class_names(hash_mode_class_names)
-        @config.hash_mode_class_names.merge(hash_mode_class_names)
+      def action_aliases(action_aliases)
+        @config.action_aliases.merge(action_aliases)
       end
 
       def input_option_helpers(input_option_helpers)
@@ -59,24 +71,12 @@ module Servactory
         @config.output_option_helpers.merge(output_option_helpers)
       end
 
-      def action_aliases(action_aliases)
-        @config.action_aliases.merge(action_aliases)
+      def collection_mode_class_names(collection_mode_class_names)
+        @config.collection_mode_class_names.merge(collection_mode_class_names)
       end
 
-      def action_shortcuts(array, hash = {}) # rubocop:disable Metrics/MethodLength
-        prepared = array.to_h do |action_shortcut|
-          [
-            action_shortcut,
-            {
-              prefix: action_shortcut,
-              suffix: nil
-            }
-          ]
-        end
-
-        prepared = prepared.merge(hash)
-
-        @config.action_shortcuts.merge(prepared)
+      def hash_mode_class_names(hash_mode_class_names)
+        @config.hash_mode_class_names.merge(hash_mode_class_names)
       end
 
       def i18n_root_key(value)

data/lib/servactory/configuration/hash_mode/class_names_collection.rb

@@ -11,6 +11,11 @@ module Servactory
         def initialize(collection)
           @collection = collection
         end
+
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+        end
       end
     end
   end

data/lib/servactory/configuration/option_helpers/option_helpers_collection.rb

@@ -12,6 +12,11 @@ module Servactory
           @collection = collection
         end
 
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+        end
+
         def dynamic_options
           OptionHelpersCollection.new(filter(&:dynamic_option?))
         end

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

@@ -21,11 +21,11 @@ module Servactory
         ##########################################################################
 
         def method_missing(name, *_args)
-          input_name = @context.class.config.predicate_methods_enabled? ? name.to_s.chomp("?").to_sym : name
+          input_name = @context.config.predicate_methods_enabled ? name.to_s.chomp("?").to_sym : name
 
           input_value = @arguments.fetch(input_name) { raise_error_for(input_name) }
 
-          if name.to_s.end_with?("?") && @context.class.config.predicate_methods_enabled?
+          if name.to_s.end_with?("?") && @context.config.predicate_methods_enabled
             Servactory::Utils.query_attribute(input_value)
           else
             input_value

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

@@ -39,7 +39,7 @@ module Servactory
 
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Lint/UnusedMethodArgument
         def fetch_with(name:, &block)
-          input_name = @context.class.config.predicate_methods_enabled? ? name.to_s.chomp("?").to_sym : name
+          input_name = @context.config.predicate_methods_enabled ? name.to_s.chomp("?").to_sym : name
 
           input = @collection_of_inputs.find_by(name: input_name)
 
@@ -54,7 +54,7 @@ module Servactory
           input_prepare = input.prepare.fetch(:in, nil)
           input_value = input_prepare.call(value: input_value) if input_prepare.present?
 
-          if name.to_s.end_with?("?") && @context.class.config.predicate_methods_enabled?
+          if name.to_s.end_with?("?") && @context.config.predicate_methods_enabled
             Servactory::Utils.query_attribute(input_value)
           else
             input_value

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

@@ -54,7 +54,7 @@ module Servactory
         end
 
         def fetch_with(name:, &block) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Lint/UnusedMethodArgument
-          internal_name = @context.class.config.predicate_methods_enabled? ? name.to_s.chomp("?").to_sym : name
+          internal_name = @context.config.predicate_methods_enabled ? name.to_s.chomp("?").to_sym : name
           internal = @collection_of_internals.find_by(name: internal_name)
 
           return yield if internal.nil?
@@ -67,7 +67,7 @@ module Servactory
             value: internal_value
           )
 
-          if name.to_s.end_with?("?") && @context.class.config.predicate_methods_enabled?
+          if name.to_s.end_with?("?") && @context.config.predicate_methods_enabled
             Servactory::Utils.query_attribute(internal_value)
           else
             internal_value

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

@@ -54,14 +54,14 @@ module Servactory
         end
 
         def fetch_with(name:, &block) # rubocop:disable Metrics/AbcSize, Lint/UnusedMethodArgument
-          output_name = @context.class.config.predicate_methods_enabled? ? name.to_s.chomp("?").to_sym : name
+          output_name = @context.config.predicate_methods_enabled ? name.to_s.chomp("?").to_sym : name
           output = @collection_of_outputs.find_by(name: output_name)
 
           return yield if output.nil?
 
           output_value = @context.send(:servactory_service_warehouse).fetch_output(output.name)
 
-          if name.to_s.end_with?("?") && @context.class.config.predicate_methods_enabled?
+          if name.to_s.end_with?("?") && @context.config.predicate_methods_enabled
             Servactory::Utils.query_attribute(output_value)
           else
             output_value

data/lib/servactory/context/workspace.rb

@@ -8,7 +8,7 @@ module Servactory
 
         def initialize(context)
           @class_name = context.class.name
-          @i18n_root_key = context.class.config.i18n_root_key
+          @i18n_root_key = context.config.i18n_root_key
         end
 
         def translate(key, **options)
@@ -42,11 +42,11 @@ module Servactory
       end
 
       def success!
-        raise self.class.config.success_class.new(context: self)
+        raise config.success_class.new(context: self)
       end
 
       def fail_input!(input_name, message:, meta: nil)
-        raise self.class.config.input_exception_class.new(
+        raise config.input_exception_class.new(
           context: self,
           input_name:,
           message:,
@@ -55,7 +55,7 @@ module Servactory
       end
 
       def fail_internal!(internal_name, message:, meta: nil)
-        raise self.class.config.internal_exception_class.new(
+        raise config.internal_exception_class.new(
           context: self,
           internal_name:,
           message:,
@@ -64,7 +64,7 @@ module Servactory
       end
 
       def fail_output!(output_name, message:, meta: nil)
-        raise self.class.config.output_exception_class.new(
+        raise config.output_exception_class.new(
           context: self,
           output_name:,
           message:,
@@ -73,13 +73,17 @@ module Servactory
       end
 
       def fail!(type = :base, message:, meta: nil)
-        raise self.class.config.failure_class.new(type:, message:, meta:)
+        raise config.failure_class.new(type:, message:, meta:)
       end
 
       def fail_result!(service_result)
         fail!(service_result.error.type, message: service_result.error.message, meta: service_result.error.meta)
       end
 
+      def config
+        self.class.config
+      end
+
       private
 
       attr_reader :collection_of_inputs,
@@ -114,7 +118,7 @@ module Servactory
       end
 
       def call
-        raise self.class.config.failure_class.new(
+        raise config.failure_class.new(
           type: :base,
           message: servactory_service_info.translate(
             "methods.call.not_used"