servactory 3.1.0.rc2 → 3.1.0.rc4

data/lib/servactory/maintenance/options/collection.rb

@@ -28,18 +28,16 @@ module Servactory
       # ## Performance
       #
       # The collection uses memoization for frequently accessed data:
-      # - `validation_classes` - cached list of unique validation classes
-      # - `options_for_checks` - cached hash for validation pipeline
+      # - `validations_for_checks` - cached tuples for validation pipeline
       # - `options_index` - cached hash for O(1) lookups by name
       #
       class Collection
         extend Forwardable
 
         def_delegators :@collection,
-                       :<<,
                        :filter,
-                       :each_with_object,
-                       :map, :flat_map,
+                       :each, :each_with_object,
+                       :map,
                        :size,
                        :empty?
 
@@ -50,6 +48,26 @@ module Servactory
           @collection = Set.new
         end
 
+        # Duplicates the collection, resetting memoized caches.
+        #
+        # @param original [Collection] the collection being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+          reset_memoized_caches
+        end
+
+        # Adds an option to the collection, invalidating memoized caches.
+        #
+        # @param option [Option] the option to add
+        # @return [Collection] self
+        def <<(option)
+          @collection << option
+          reset_memoized_caches
+          self
+        end
+
         # Returns all option names in the collection.
         #
         # @return [Array<Symbol>] list of option names
@@ -57,32 +75,51 @@ module Servactory
           map(&:name)
         end
 
-        # Returns unique validation classes from all options.
+        # @deprecated Use {#validations_for_checks} instead.
         #
         # @return [Array<Class>] deduplicated list of validation classes
         def validation_classes
-          @validation_classes ||=
-            filter { |option| option.validation_class.present? }
-            .map(&:validation_class)
-            .uniq
+          warn "[DEPRECATION] Servactory::Maintenance::Options::Collection#validation_classes is deprecated. " \
+               "Use #validations_for_checks instead."
+          validations_for_checks.map(&:last).uniq
         end
 
-        # Returns options that need validation checks as a hash.
+        # @deprecated Use {#validations_for_checks} instead.
         #
         # @return [Hash{Symbol => Object}] option names mapped to normalized bodies
         def options_for_checks
-          @options_for_checks ||= filter(&:need_for_checks?).to_h do |option|
-            [option.name, extract_normalized_body_from(option:)]
+          warn "[DEPRECATION] Servactory::Maintenance::Options::Collection#options_for_checks is deprecated. " \
+               "Use #validations_for_checks instead."
+          check_options_by_key
+        end
+
+        # Returns options that need validation checks as an array of tuples.
+        # Each tuple contains [check_key, check_options, validation_class],
+        # enabling direct dispatch without nested iteration.
+        #
+        # @return [Array<Array(Symbol, Object, Class)>] tuples for direct validation dispatch
+        def validations_for_checks
+          @validations_for_checks ||= filter(&:need_for_checks?).filter_map do |option|
+            next if option.validation_class.nil?
+
+            [option.name, extract_normalized_body_from(option:), option.validation_class]
           end
         end
 
         # Returns the first conflict code found among options.
         #
-        # @return [Object, nil] conflict code or nil if no conflicts
+        # @return [Symbol, nil] conflict code or nil if no conflicts
         def defined_conflict_code
-          flat_map { |option| resolve_conflicts_from(option:) }
-            .reject(&:blank?)
-            .first
+          each do |option|
+            next unless option.define_conflicts
+
+            option.define_conflicts.each do |conflict|
+              code = conflict.content.call
+              return code if code.present?
+            end
+          end
+
+          nil
         end
 
         # Finds an option by its name using indexed lookup.
@@ -95,13 +132,27 @@ module Servactory
 
         private
 
+        # Builds the result of the deprecated `options_for_checks` methods
+        # without emitting a deprecation warning.
+        #
+        # @return [Hash{Symbol => Object}] option names mapped to normalized bodies
+        def check_options_by_key
+          validations_for_checks.to_h { |check_key, check_options, _| [check_key, check_options] }
+        end
+
+        # Resets memoized data derived from the collection contents.
+        #
+        # @return [void]
+        def reset_memoized_caches
+          @validations_for_checks = nil
+          @options_index = nil
+        end
+
         # Builds and caches a hash index for O(1) option lookups.
         #
         # @return [Hash{Symbol => Option}] option names mapped to Option instances
         def options_index
-          @options_index ||= each_with_object({}) do |option, index|
-            index[option.name] = option
-          end
+          @options_index ||= @collection.to_h { |option| [option.name, option] }
         end
 
         # Extracts the normalized body value from an option.
@@ -111,16 +162,6 @@ module Servactory
         def extract_normalized_body_from(option:)
           option.value
         end
-
-        # Resolves conflict codes from an option's define_conflicts.
-        #
-        # @param option [Option] the option to check for conflicts
-        # @return [Array<Object>] array of conflict codes (may contain nils/blanks)
-        def resolve_conflicts_from(option:)
-          return [] unless option.define_conflicts
-
-          option.define_conflicts.map { |conflict| conflict.content.call }
-        end
       end
     end
   end

data/lib/servactory/maintenance/options/option.rb

@@ -17,7 +17,7 @@ module Servactory
                     :body_key,
                     :return_value_on_access
 
-        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
         def initialize(
           name:,
           attribute:,
@@ -54,7 +54,6 @@ module Servactory
 
           apply_dynamic_methods_to(attribute:)
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
         def value
           return body unless body.is_a?(Hash)
@@ -72,7 +71,7 @@ module Servactory
 
         private
 
-        # rubocop:disable Metrics/MethodLength
+        # rubocop:disable-next Metrics/MethodLength
         def construct_body(
           original_value:,
           options:,
@@ -81,9 +80,7 @@ module Servactory
           body_fallback:,
           detect_advanced_mode:
         )
-          return wrap_and_normalize(original_value) if original_value.present?
-
-          raw_value = options.fetch(@name, body_fallback)
+          raw_value = original_value.nil? ? options.fetch(@name, body_fallback) : original_value
 
           result = if detect_advanced_mode
                      use_advanced_mode(
@@ -98,12 +95,6 @@ module Servactory
 
           apply_normalizer(result)
         end
-        # rubocop:enable Metrics/MethodLength
-
-        def wrap_and_normalize(value)
-          result = wrap_value(value)
-          apply_normalizer(result)
-        end
 
         def apply_normalizer(body)
           return body unless @normalizer && body.is_a?(Hash)

data/lib/servactory/maintenance/options/registrar.rb

@@ -78,9 +78,10 @@ module Servactory
           create_option(
             name: :types,
             validation_class:,
-            original_value: extract_types_value,
+            original_value: @options[:type],
             need_for_checks: true,
             body_key: :is,
+            body_value: nil,
             body_fallback: nil,
             detect_advanced_mode: true,
             return_value_on_access: true,
@@ -98,7 +99,7 @@ module Servactory
                 content: ->(option:) { !option[:is].nil? }
               )
             ],
-            need_for_checks: true,
+            need_for_checks: false,
             body_key: :is,
             body_fallback: nil,
             detect_advanced_mode: false,
@@ -142,17 +143,6 @@ module Servactory
           )
         end
 
-        def extract_types_value
-          type_option = @options[:type]
-          return nil if type_option.nil?
-
-          # Advanced Mode: type: { is: String, message: "..." }
-          return nil if type_option.is_a?(Hash) && type_option.key?(:is)
-
-          # Simple Mode: type: String or type: [String, Integer]
-          Array(type_option).uniq
-        end
-
         ########################################################################
 
         def required_define_methods

data/lib/servactory/maintenance/validations/checkers/type.rb

@@ -21,11 +21,19 @@ module Servactory
         #   input :id, type: Integer
         #   input :data, type: [Hash, Array]  # union type
         #   input :status, type: String, required: false
+        #   input :email, type: { is: String, message: "Email must be a String" }
         #
         #   internal :result, type: CustomType
         #   output :response, type: Hash
         # end
         # ```
+        #
+        # ## Custom Message
+        #
+        # Advanced mode `type: { is:, message: }` replaces the default error
+        # message for every type failure of the attribute. A Proc message
+        # receives `service:`, `input:`/`internal:`/`output:`, `value:`,
+        # `expected_type:` and `given_type:`.
         class Type
           extend Concerns::ErrorBuilder
 
@@ -51,7 +59,7 @@ module Servactory
 
             return if error_data.nil?
 
-            build_error_message(error_data)
+            build_error_message(attribute:, error_data:)
           end
 
           # Determines if type validation should run for given attribute.
@@ -67,7 +75,7 @@ module Servactory
           # @param value [Object] Current value (for optional input check)
           # @param check_key [Symbol] Current validation check key
           # @return [Boolean] true if type validation should run
-          # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          # rubocop:disable-next Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           def self.should_be_checked_for?(attribute, value, check_key)
             check_key == :types && (
               (
@@ -81,7 +89,6 @@ module Servactory
               ) || attribute.internal? || attribute.output?
             )
           end
-          # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           private_class_method :should_be_checked_for?
 
           # Computes prepared value with default substitution for optional inputs.
@@ -100,10 +107,21 @@ module Servactory
 
           # Builds error message from validation error data.
           #
+          # Uses the custom message from `type: { is:, message: }` if provided,
+          # otherwise falls back to the default message.
+          #
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Failed attribute
           # @param error_data [Hash] Error data from TypeValidator.validate
           # @return [String] Processed error message
-          def self.build_error_message(error_data)
-            process_message(error_data[:message], **error_data)
+          def self.build_error_message(attribute:, error_data:)
+            message = attribute.collection_of_options.find_by(name: :types).body[:message]
+            return process_message(error_data[:message], **error_data) if message.blank?
+
+            process_message(
+              message,
+              **attribute.typed_actor_kwargs,
+              **error_data.slice(:service, :value, :expected_type, :given_type)
+            )
           end
           private_class_method :build_error_message
         end

data/lib/servactory/maintenance/validations/performer.rb

@@ -19,14 +19,11 @@ module Servactory
 
         private
 
-        def process(context:, attribute:, value:) # rubocop:disable Metrics/MethodLength
-          attribute.options_for_checks.each do |check_key, check_options|
+        def process(context:, attribute:, value:)
+          attribute.collection_of_options.validations_for_checks.each do |check_key, check_options, validation_class|
             error = process_option(
-              context:,
-              attribute:,
-              value:,
-              check_key:,
-              check_options:
+              context:, attribute:, value:,
+              check_key:, check_options:, validation_class:
             )
             return error if error.present?
           end
@@ -34,22 +31,14 @@ module Servactory
           nil
         end
 
-        def process_option(context:, attribute:, value:, check_key:, check_options:) # rubocop:disable Metrics/MethodLength
-          validation_classes = attribute.collection_of_options.validation_classes
-          return if validation_classes.empty?
-
-          validation_classes.each do |validation_class|
-            error_message = validation_class.check(
-              context:,
-              attribute:,
-              value:,
-              check_key:,
-              check_options:
-            )
-            return error_message if error_message.present?
-          end
-
-          nil
+        def process_option(context:, attribute:, value:, check_key:, check_options:, validation_class:)
+          validation_class.check(
+            context:,
+            attribute:,
+            value:,
+            check_key:,
+            check_options:
+          )
         end
       end
     end

data/lib/servactory/outputs/dsl.rb

@@ -17,12 +17,18 @@ module Servactory
         private
 
         def output(name, *helpers, **options)
-          collection_of_outputs << Output.new(
+          output = Output.new(
             name,
             *helpers,
             option_helpers: config.output_option_helpers,
             **options
           )
+
+          if output.types.empty?
+            raise ArgumentError, "[#{self.name}] Output attribute `#{name}` must have the `type` option"
+          end
+
+          collection_of_outputs << output
         end
 
         def collection_of_outputs

data/lib/servactory/result.rb

@@ -41,7 +41,7 @@ module Servactory
   # ```ruby
   # result.active?  # Equivalent to Utils.query_attribute(result.active)
   # ```
-  class Result
+  class Result # rubocop:disable Metrics/ClassLength
     # Internal container for service output values.
     #
     # Provides dynamic method access to output values.
@@ -120,6 +120,10 @@ module Servactory
 
     private_constant :Outputs
 
+    # Result state keys exposed by {#deconstruct_keys}.
+    STATE_KEYS = %i[success failure error].freeze
+    private_constant :STATE_KEYS
+
     ############################################################################
 
     # Creates a success result for the given context.
@@ -198,20 +202,27 @@ module Servactory
 
     # Converts outputs to hash.
     #
-    # Excludes predicate methods from the result hash.
+    # Returns only outputs that were assigned during the call, including
+    # outputs explicitly assigned nil. Declared outputs that were never
+    # assigned are absent. Excludes predicate methods from the result hash.
     #
-    # @return [Hash<Symbol, Object>] Output name-value pairs
+    # @return [Hash<Symbol, Object>] Assigned output name-value pairs
     #
     # @example
-    #   result.to_h # => { user: #<User>, token: "abc123" }
+    #   result.to_h # => { user: #<User>, token: nil }
     def to_h
-      outputs.send(:output_names).to_h { |key| [key, outputs.public_send(key)] }.compact
+      hash = {}
+      outputs.send(:output_names).each { |key| hash[key] = outputs.public_send(key) }
+      hash
     end
 
     # Pattern matching support.
     #
     # Returns hash of result state and output values for use with case/in.
-    # State keys (:success, :failure, :error) take priority over output names.
+    # Output keys match {#to_h}: only assigned outputs are present.
+    # State keys (:success, :failure, :error) take priority over output names:
+    # outputs with these names are not included, and :error is present only
+    # for failures.
     #
     # @param keys [Array<Symbol>, nil] Keys to include, or nil for all
     # @return [Hash<Symbol, Object>] Hash of state and outputs for pattern matching
@@ -234,6 +245,8 @@ module Servactory
       available[:error] = error if failure?
 
       outputs.send(:output_names).each do |name|
+        next if STATE_KEYS.include?(name)
+
         available[name] = outputs.public_send(name)
       end
 
@@ -347,7 +360,7 @@ module Servactory
       Outputs.new(
         outputs: build_outputs_hash,
         predicate_methods_enabled:
-          @context.is_a?(Servactory::TestKit::Result) || @context.config.predicate_methods_enabled
+          @context.is_a?(Servactory::TestKit::Result) || @context.class.config.predicate_methods_enabled
       )
     end
 
@@ -374,7 +387,7 @@ module Servactory
     def rescue_no_method_error_with(exception:) # rubocop:disable Metrics/MethodLength
       raise exception if @context.blank? || @context.instance_of?(Servactory::TestKit::Result)
 
-      raise @context.config.failure_class.new(
+      raise @context.class.config.failure_class.new(
         type: :base,
         message: @context.send(:servactory_service_info).translate(
           "common.undefined_method.missing_name",

data/lib/servactory/test_kit/rspec/helpers/exception_validator.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Helpers
+        # Validates the exception of a mock configuration.
+        #
+        # ## Purpose
+        #
+        # Ensures that failure mocks have an exception and that the exception
+        # type matches the service configuration. Called automatically by
+        # MockExecutor for every config before stubbing.
+        #
+        # ## Usage
+        #
+        # ```ruby
+        # ExceptionValidator.validate!(config)
+        # ```
+        #
+        # ## Validation Strategy
+        #
+        # - `.call` - accepts any Servactory::Exceptions::Failure subclass
+        # - `.call!` - requires the service's configured failure_class or its subclass
+        class ExceptionValidator
+          include Concerns::ErrorMessages
+
+          class << self
+            # Validates a config and raises on failure.
+            #
+            # @param config [ServiceMockConfig] The config to validate
+            # @return [void]
+            # @raise [ArgumentError] If config is invalid
+            def validate!(config)
+              new(config).validate!
+            end
+          end
+
+          # Creates a new validator instance.
+          #
+          # @param config [ServiceMockConfig] The config to validate
+          # @return [ExceptionValidator] New validator
+          def initialize(config)
+            @config = config
+          end
+
+          # Validates a single configuration.
+          #
+          # @return [void]
+          # @raise [ArgumentError] If config is invalid
+          def validate!
+            validate_failure_has_exception!
+            validate_exception_type!
+          end
+
+          private
+
+          # Validates that failure configs have an exception.
+          #
+          # @return [void]
+          # @raise [ArgumentError] If failure config is missing exception
+          def validate_failure_has_exception!
+            return unless @config.failure? && @config.exception.nil?
+
+            raise ArgumentError, missing_exception_for_failure_message(@config.service_class)
+          end
+
+          # Validates that exception is the correct type for the service.
+          #
+          # @return [void]
+          # @raise [ArgumentError] If exception type is wrong
+          def validate_exception_type!
+            return if @config.exception.nil?
+            return if valid_exception_type?
+
+            raise ArgumentError, invalid_exception_type_message(
+              service_class: @config.service_class,
+              expected_class: failure_class,
+              actual_class: @config.exception.class
+            )
+          end
+
+          # Checks if exception is the correct type.
+          #
+          # Uses different validation strategies based on method type:
+          # - For `.call` (non-bang): Relaxed validation - accepts any Servactory::Exceptions::Failure subclass
+          #   because the exception is wrapped in Result and never raised, so type doesn't matter.
+          # - For `.call!` (bang): Strict validation - requires the service's configured failure_class
+          #   because the exception IS raised and type matters for rescue clauses.
+          #
+          # @return [Boolean] True if exception is valid type
+          def valid_exception_type?
+            if @config.bang_method?
+              # Strict validation for call! - exception will be raised
+              @config.exception.is_a?(failure_class)
+            else
+              # Relaxed validation for call - exception is only wrapped in Result
+              @config.exception.is_a?(Servactory::Exceptions::Failure)
+            end
+          end
+
+          # Returns the expected failure class for the service.
+          #
+          # @return [Class] The service's failure class
+          def failure_class
+            @config.service_class.config.failure_class
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/helpers/input_validator.rb

@@ -133,7 +133,9 @@ module Servactory
           # @raise [ValidationError] If service has required inputs
           # @return [void]
           def validate_service_has_no_required_inputs!
-            required_inputs = @service_class.info.inputs.reject { |_, v| v[:required] == false }.keys
+            required_inputs = @service_class.info.inputs.filter_map do |input_name, input|
+              input_name if input.fetch(:actor).required?
+            end
 
             return if required_inputs.empty?