servactory 3.0.0.rc3 → 3.0.0.rc4

data/lib/servactory/maintenance/attributes/tools/validation.rb

@@ -13,6 +13,7 @@ module Servactory
             @context = context
             @attribute = attribute
             @value = value
+            @first_error = nil
           end
 
           def validate!
@@ -26,22 +27,24 @@ module Servactory
           def process
             @attribute.options_for_checks.each do |check_key, check_options|
               process_option(check_key, check_options)
+              break if @first_error.present?
             end
           end
 
-          def process_option(check_key, check_options)
+          def process_option(check_key, check_options) # rubocop:disable Metrics/MethodLength
             return if validation_classes.empty?
 
             validation_classes.each do |validation_class|
-              errors_from_checks = process_validation_class(
+              error_message = process_validation_class(
                 validation_class:,
                 check_key:,
                 check_options:
               )
 
-              next if errors_from_checks.nil? || errors_from_checks.empty?
+              next if error_message.blank?
 
-              errors.merge(errors_from_checks.to_a)
+              @first_error = error_message
+              break
             end
           end
 
@@ -67,16 +70,12 @@ module Servactory
 
           ########################################################################
 
-          def errors
-            @errors ||= Servactory::Maintenance::Attributes::Tools::CheckErrors.new
-          end
-
           def raise_errors
-            return if (tmp_errors = errors.not_blank).empty?
+            return if @first_error.nil?
 
             raise @context.config
                           .public_send(:"#{@attribute.system_name}_exception_class")
-                          .new(context: @context, message: tmp_errors.first)
+                          .new(context: @context, message: @first_error)
           end
         end
       end

data/lib/servactory/maintenance/attributes/validations/concerns/error_builder.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Maintenance
+    module Attributes
+      module Validations
+        module Concerns
+          # Concern providing error message processing for validators.
+          #
+          # ## Purpose
+          #
+          # ErrorBuilder provides shared logic for processing error messages that
+          # can be either static strings or dynamic Procs. This allows validators
+          # to support both simple error messages and context-aware messages.
+          #
+          # ## Usage
+          #
+          # Extend in validator classes:
+          #
+          # ```ruby
+          # class MyValidator
+          #   extend Concerns::ErrorBuilder
+          #
+          #   def self.build_error(...)
+          #     process_message(message, **context)
+          #   end
+          # end
+          # ```
+          #
+          # ## Methods Provided
+          #
+          # - `process_message` - converts String or Proc message to String
+          module ErrorBuilder
+            # Processes a message that may be a String or Proc.
+            #
+            # If message is a Proc, calls it with the provided attributes.
+            # If message is a String, returns it unchanged.
+            #
+            # @param message [String, Proc] The message to process
+            # @param attributes [Hash] Attributes to pass to Proc if message is callable
+            # @return [String] The processed message string
+            def process_message(message, **attributes)
+              return message unless message.is_a?(Proc)
+
+              message.call(**attributes)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/maintenance/attributes/validations/must.rb

@@ -4,87 +4,194 @@ module Servactory
   module Maintenance
     module Attributes
       module Validations
-        class Must < Base
+        # Validates custom conditions defined with `must` option.
+        #
+        # ## Purpose
+        #
+        # Must validator executes user-defined validation lambdas against attribute
+        # values. It supports multiple named conditions per attribute and provides
+        # rich error context including custom messages, reason codes, and metadata.
+        #
+        # ## Usage
+        #
+        # Define must conditions on any attribute (input, internal, output):
+        #
+        # ```ruby
+        # class MyService < ApplicationService::Base
+        #   input :age,
+        #         type: Integer,
+        #         must: {
+        #           be_adult: {
+        #             is: ->(value:) { value >= 18 },
+        #             message: "Must be 18 or older"
+        #           }
+        #         }
+        #
+        #   internal :discount,
+        #            type: Float,
+        #            must: {
+        #              be_percentage: {
+        #                is: ->(value:) { value.between?(0, 100) }
+        #              }
+        #            }
+        # end
+        # ```
+        class Must
+          extend Concerns::ErrorBuilder
+
+          # Validates all must conditions for an attribute.
+          #
+          # Iterates through check_options and validates each condition.
+          # Returns on first failure (early return pattern).
+          #
+          # @param context [Object] Service context for error message formatting
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute to validate
+          # @param value [Object] Value to validate against conditions
+          # @param check_key [Symbol] Must be :must to trigger validation
+          # @param check_options [Hash{Symbol => Hash}] Named conditions with :is and :message
+          # @return [String, nil] Error message on first failure, nil if all pass
           def self.check(context:, attribute:, value:, check_key:, check_options:)
             return unless should_be_checked_for?(attribute, check_key)
 
-            new(context:, attribute:, value:, check_options:).check
+            check_options.each do |code, options|
+              error_message = validate_condition(context:, attribute:, value:, code:, options:)
+              return error_message if error_message.present?
+            end
+
+            nil
           end
 
+          # Determines if validation should run for given attribute and check key.
+          #
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute to check
+          # @param check_key [Symbol] Current validation check key
+          # @return [Boolean] true if this validator should run
           def self.should_be_checked_for?(attribute, check_key)
             check_key == :must && attribute.must_present?
           end
-
-          ##########################################################################
-
-          def initialize(context:, attribute:, value:, check_options:)
-            super()
-
-            @context = context
-            @attribute = attribute
-            @value = value
-            @check_options = check_options
-          end
-
-          def check
-            @check_options.each do |code, options|
-              message, reason, meta = call_or_fetch_message_from(code, options)
-
-              next if message.blank?
-
-              add_error_with(message, code, reason, meta)
-            end
-
-            errors
-          end
-
-          private
-
-          def call_or_fetch_message_from(code, options) # rubocop:disable Metrics/MethodLength
+          private_class_method :should_be_checked_for?
+
+          # Validates a single must condition by executing its check lambda.
+          #
+          # Executes the check lambda and handles three outcomes:
+          # - Lambda returns true: validation passes (returns nil)
+          # - Lambda returns [false, reason, meta]: validation fails with context
+          # - Lambda raises exception: returns syntax error message
+          #
+          # @param context [Object] Service context for error formatting
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute being validated
+          # @param value [Object] Value to pass to check lambda
+          # @param code [Symbol] Condition identifier (e.g., :be_adult)
+          # @param options [Hash] Condition options with :is (lambda) and :message
+          # @return [String, nil] Error message on failure, nil on success
+          def self.validate_condition(context:, attribute:, value:, code:, options:) # rubocop:disable Metrics/MethodLength
             check, message = options.values_at(:is, :message)
 
-            check_result, check_result_code, meta =
-              check.call(value: @value, **Servactory::Utils.fetch_hash_with_desired_attribute(@attribute))
+            check_result, check_result_code, meta = call_check(
+              context:,
+              attribute:,
+              value:,
+              check:,
+              code:
+            )
 
-            return if check_result
+            # check_result is :syntax_error when syntax error occurred
+            return check_result_code if check_result == :syntax_error
+            return if check_result == true
 
-            [
-              message.presence || Servactory::Maintenance::Attributes::Translator::Must.default_message,
-              check_result_code,
-              meta
-            ]
+            build_error_message(
+              context:,
+              attribute:,
+              value:,
+              code:,
+              reason: check_result_code,
+              meta:,
+              message:
+            )
+          end
+          private_class_method :validate_condition
+
+          # Executes the check lambda with exception handling.
+          #
+          # Catches any StandardError from the lambda and converts it to a
+          # formatted syntax error message for better debugging experience.
+          #
+          # @param context [Object] Service context for error formatting
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute being validated
+          # @param value [Object] Value to pass to lambda
+          # @param check [Proc] The validation lambda to execute
+          # @param code [Symbol] Condition identifier for error messages
+          # @return [Array] On success: [result, reason_code, meta_hash]
+          # @return [Array] On exception: [:syntax_error, error_message_string, nil]
+          def self.call_check(context:, attribute:, value:, check:, code:)
+            check.call(value:, **Servactory::Utils.fetch_hash_with_desired_attribute(attribute))
           rescue StandardError => e
-            add_syntax_error_with(
-              Servactory::Maintenance::Attributes::Translator::Must.syntax_error_message,
-              code,
-              e.message
+            # Return formatted syntax error message
+            syntax_error_message = build_syntax_error_message(
+              context:,
+              attribute:,
+              value:,
+              code:,
+              exception_message: e.message
             )
+            [:syntax_error, syntax_error_message, nil]
           end
-
-          ########################################################################
-
-          def add_error_with(message, code, reason, meta = {})
-            add_error(
-              message:,
-              service: @context.send(:servactory_service_info),
-              **Servactory::Utils.fetch_hash_with_desired_attribute(@attribute),
-              value: @value,
+          private_class_method :call_check
+
+          # Builds error message from validation failure.
+          #
+          # Uses custom message if provided, otherwise falls back to default.
+          # Message can be a String or Proc for dynamic formatting.
+          #
+          # NOTE: Errors from message.call are NOT caught - they propagate to caller.
+          #
+          # @param context [Object] Service context for message formatting
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Failed attribute
+          # @param value [Object] The invalid value
+          # @param code [Symbol] Condition identifier
+          # @param reason [Symbol, nil] Failure reason from check lambda
+          # @param meta [Hash, nil] Additional metadata from check lambda
+          # @param message [String, Proc, nil] Custom error message
+          # @return [String] Processed error message
+          def self.build_error_message(context:, attribute:, value:, code:, reason:, meta:, message:)
+            message = message.presence || Servactory::Maintenance::Attributes::Translator::Must.default_message
+
+            process_message(
+              message,
+              service: context.send(:servactory_service_info),
+              **Servactory::Utils.fetch_hash_with_desired_attribute(attribute),
+              value:,
               code:,
               reason:,
               meta:
             )
           end
-
-          def add_syntax_error_with(message, code, exception_message)
-            add_error(
-              message:,
-              service: @context.send(:servactory_service_info),
-              **Servactory::Utils.fetch_hash_with_desired_attribute(@attribute),
-              value: @value,
+          private_class_method :build_error_message
+
+          # Builds error message for exceptions raised in check lambdas.
+          #
+          # Formats the exception message with context for debugging,
+          # including the condition code and original exception text.
+          #
+          # @param context [Object] Service context for message formatting
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute being validated
+          # @param value [Object] Value that caused the exception
+          # @param code [Symbol] Condition identifier where error occurred
+          # @param exception_message [String] Original exception message
+          # @return [String] Formatted syntax error message
+          def self.build_syntax_error_message(context:, attribute:, value:, code:, exception_message:)
+            message = Servactory::Maintenance::Attributes::Translator::Must.syntax_error_message
+
+            process_message(
+              message,
+              service: context.send(:servactory_service_info),
+              **Servactory::Utils.fetch_hash_with_desired_attribute(attribute),
+              value:,
               code:,
               exception_message:
             )
           end
+          private_class_method :build_syntax_error_message
         end
       end
     end

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

@@ -4,13 +4,68 @@ module Servactory
   module Maintenance
     module Attributes
       module Validations
-        class Type < Base
+        # Validates that attribute values match their declared types.
+        #
+        # ## Purpose
+        #
+        # Type validator ensures attribute values conform to declared type
+        # constraints. It supports single types, union types (arrays), and
+        # custom type definitions. Works with inputs, internals, and outputs.
+        #
+        # ## Usage
+        #
+        # Type validation is automatic based on the `type` option:
+        #
+        # ```ruby
+        # class MyService < ApplicationService::Base
+        #   input :id, type: Integer
+        #   input :data, type: [Hash, Array]  # union type
+        #   input :status, type: String, required: false
+        #
+        #   internal :result, type: CustomType
+        #   output :response, type: Hash
+        # end
+        # ```
+        class Type
+          extend Concerns::ErrorBuilder
+
+          # Validates that a value matches the declared attribute types.
+          #
+          # @param context [Object] Service context for error formatting
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute to validate
+          # @param value [Object] Value to check against declared types
+          # @param check_key [Symbol] Must be :types to trigger validation
+          # @return [String, nil] Error message on type mismatch, nil on success
           def self.check(context:, attribute:, value:, check_key:, **)
             return unless should_be_checked_for?(attribute, value, check_key)
 
-            new(context:, attribute:, value:).check
+            prepared_value = compute_prepared_value(attribute, value)
+
+            error_data = Servactory::Maintenance::Validations::Types.validate(
+              context:,
+              attribute:,
+              types: attribute.types,
+              value: prepared_value
+            )
+
+            return if error_data.nil?
+
+            build_error_message(error_data)
           end
 
+          # Determines if type validation should run for given attribute.
+          #
+          # Type validation runs when:
+          # - check_key is :types AND one of:
+          #   - Input is required
+          #   - Input is optional with non-nil default
+          #   - Input is optional with non-nil value
+          #   - Attribute is internal or output (always validated)
+          #
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute to check
+          # @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
           def self.should_be_checked_for?(attribute, value, check_key)
             check_key == :types && (
@@ -26,35 +81,30 @@ module Servactory
             )
           end
           # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          private_class_method :should_be_checked_for?
 
-          def initialize(context:, attribute:, value:)
-            super()
-
-            @context = context
-            @attribute = attribute
-            @value = value
+          # Computes prepared value with default substitution for optional inputs.
+          #
+          # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute
+          # @param value [Object] Original value
+          # @return [Object] Prepared value (default or original)
+          def self.compute_prepared_value(attribute, value)
+            if attribute.input? && attribute.optional? && !attribute.default.nil? && value.blank?
+              attribute.default
+            else
+              value
+            end
           end
+          private_class_method :compute_prepared_value
 
-          def check
-            Servactory::Maintenance::Validations::Types.validate!(
-              context: @context,
-              attribute: @attribute,
-              types: @attribute.types,
-              value: prepared_value,
-              error_callback: ->(**args) { add_error(**args) }
-            )
-          end
-
-          private
-
-          def prepared_value
-            @prepared_value ||=
-              if @attribute.input? && @attribute.optional? && !@attribute.default.nil? && @value.blank?
-                @attribute.default
-              else
-                @value
-              end
+          # Builds error message from validation error data.
+          #
+          # @param error_data [Hash] Error data from Types.validate
+          # @return [String] Processed error message
+          def self.build_error_message(error_data)
+            process_message(error_data[:message], **error_data)
           end
+          private_class_method :build_error_message
         end
       end
     end

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

@@ -4,44 +4,29 @@ module Servactory
   module Maintenance
     module Validations
       class Types
-        def self.validate!(...)
-          new(...).validate!
-        end
-
-        def initialize(context:, attribute:, types:, value:, error_callback:)
-          @context = context
-          @attribute = attribute
-          @types = types
-          @value = value
-          @error_callback = error_callback
-        end
+        # Validates value against expected types.
+        #
+        # Returns nil on success, error data Hash on failure.
+        #
+        # @param context [Object] Service context for error info
+        # @param attribute [Inputs::Input, Internals::Internal, Outputs::Output] Attribute being validated
+        # @param types [Array<Class, String, Symbol>] Expected type classes
+        # @param value [Object] Value to validate
+        # @return [Hash, nil] nil on success, error data Hash on failure
+        def self.validate(context:, attribute:, types:, value:) # rubocop:disable Metrics/MethodLength
+          prepared_types = types.map { |type| Servactory::Utils.constantize_class(type) }
 
-        def validate! # rubocop:disable Metrics/MethodLength
-          return if prepared_types.any? do |type|
-            @value.is_a?(type)
-          end
+          return if prepared_types.any? { |type| value.is_a?(type) }
 
-          @error_callback.call(
+          {
             message: Servactory::Maintenance::Attributes::Translator::Type.default_message,
-            service: @context.send(:servactory_service_info),
-            attribute: @attribute,
-            value: @value,
+            service: context.send(:servactory_service_info),
+            attribute:,
+            value:,
             key_name: nil,
             expected_type: prepared_types.join(", "),
-            given_type: @value.class.name
-          )
-        end
-
-        private
-
-        def prepared_types
-          @prepared_types ||= prepared_types_from(@types)
-        end
-
-        def prepared_types_from(types)
-          types.map do |type|
-            Servactory::Utils.constantize_class(type)
-          end
+            given_type: value.class.name
+          }
         end
       end
     end

data/lib/servactory/outputs/output.rb

@@ -12,24 +12,29 @@ module Servactory
           @name = output.name
           @types = output.types
           @options = output.options
+          @attribute = output
+        end
+
+        def system_name
+          @attribute.system_name
+        end
 
-          define_identity_methods(output)
+        def i18n_name
+          @attribute.i18n_name
         end
 
-        private
+        # The methods below are required to support the internal work.
 
-        def define_identity_methods(output)
-          methods_map = {
-            system_name: -> { output.system_name },
-            i18n_name: -> { output.i18n_name },
-            input?: -> { false },
-            internal?: -> { false },
-            output?: -> { true }
-          }
+        def input?
+          false
+        end
+
+        def internal?
+          false
+        end
 
-          methods_map.each do |method_name, implementation|
-            define_singleton_method(method_name, &implementation)
-          end
+        def output?
+          true
         end
       end