servactory 2.16.0 → 3.0.0.rc1

data/lib/servactory/tool_kit/dynamic_options/multiple_of.rb

@@ -3,31 +3,154 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Validates that numeric value is a multiple of a specified number.
+      #
+      # ## Purpose
+      #
+      # MultipleOf ensures that numeric values are evenly divisible by
+      # a specified divisor. This is useful for validating quantities,
+      # prices, or any values that must conform to specific increments.
+      #
+      # ## Usage
+      #
+      # This option is **NOT included by default**. Register it for each
+      # attribute type where you want to use it:
+      #
+      # ```ruby
+      # configuration do
+      #   input_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::MultipleOf.use
+      #   ])
+      #
+      #   internal_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::MultipleOf.use
+      #   ])
+      #
+      #   output_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::MultipleOf.use
+      #   ])
+      # end
+      # ```
+      #
+      # Use in your service definition:
+      #
+      # ```ruby
+      # class ProcessOrderService < ApplicationService::Base
+      #   input :quantity, type: Integer, multiple_of: 5
+      #   input :price, type: Float, multiple_of: 0.25
+      #   input :batch_size, type: Integer, multiple_of: 100
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Specify divisor directly:
+      #
+      # ```ruby
+      # class ProcessOrderService < ApplicationService::Base
+      #   input :quantity, type: Integer, multiple_of: 5
+      #   input :price, type: Float, multiple_of: 0.25
+      #   input :batch_size, type: Integer, multiple_of: 100
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify divisor with custom error message using a hash:
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :quantity, type: Integer, multiple_of: {
+      #   is: 5,
+      #   message: "Input `quantity` must be a multiple of 5"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :quantity, type: Integer, multiple_of: {
+      #   is: 5,
+      #   message: lambda do |input:, value:, option_value:, **|
+      #     "Input `#{input.name}` must be divisible by #{option_value}, got #{value}"
+      #   end
+      # }
+      # ```
+      #
+      # Lambda receives the following parameters:
+      # - For inputs: `input:, option_value:, value:, **`
+      # - For internals: `internal:, option_value:, value:, **`
+      # - For outputs: `output:, option_value:, value:, **`
+      #
+      # ## Supported Types
+      #
+      # - Integer
+      # - Float
+      # - Rational
+      # - BigDecimal
+      #
+      # ## Important Notes
+      #
+      # - Divisor must be a non-zero Numeric
+      # - Uses epsilon comparison for floating point precision
+      # - Returns false for non-numeric values
+      # - Provides specific error messages for blank and zero divisors
       class MultipleOf < Must
+        # Creates a MultipleOf validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :multiple_of)
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def self.use(option_name = :multiple_of)
           new(option_name).must(:be_multiple_of)
         end
 
+        # Validates multiple_of condition for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Multiple of configuration
+        # @return [Boolean] true if valid
         def condition_for_input_with(...)
           common_condition_with(...)
         end
 
+        # Validates multiple_of condition for internal attribute.
+        #
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Multiple of configuration
+        # @return [Boolean] true if valid
         def condition_for_internal_with(...)
           common_condition_with(...)
         end
 
+        # Validates multiple_of condition for output attribute.
+        #
+        # @param output [Object] Output attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Multiple of configuration
+        # @return [Boolean] true if valid
         def condition_for_output_with(...)
           common_condition_with(...)
         end
 
+        # Common validation logic for all attribute types.
+        #
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Multiple of configuration
+        # @return [Boolean] true if value is multiple of divisor
         def common_condition_with(value:, option:, **) # rubocop:disable Naming/PredicateMethod
           case value
           when Integer, Float, Rational, BigDecimal
+            # Validate divisor is present and valid.
             return false if option.value.blank?
-            return false unless [Numeric, Float, Rational, BigDecimal].any? { |c| option.value.is_a?(c) }
+            return false unless option.value.is_a?(Numeric)
             return false if option.value.zero?
 
-            (value % option.value).zero?
+            # Calculate remainder with epsilon tolerance for floats.
+            remainder = value % option.value
+            remainder.zero? || remainder.abs < Float::EPSILON * [value.abs, option.value.abs].max
           else
             false
           end
@@ -35,13 +158,25 @@ module Servactory
 
         ########################################################################
 
+        # Generates error message for input validation failure.
+        #
+        # Selects appropriate message based on divisor state:
+        # - blank: divisor is nil or empty
+        # - divided_by_0: divisor is zero
+        # - default: standard not-multiple-of message
+        #
+        # @param service [Object] Service context
+        # @param input [Object] Input attribute
+        # @param value [Object] Failed value
+        # @param option_name [Symbol] Option name
+        # @param option_value [Object] Divisor value
+        # @return [String] Localized error message
         def message_for_input_with(service:, input:, value:, option_name:, option_value:, **) # rubocop:disable Metrics/MethodLength
           i18n_key = "inputs.validations.must.dynamic_options.multiple_of"
 
           i18n_key += if option_value.blank?
                         ".blank"
-                      elsif [Numeric, Float, Rational, BigDecimal].any? { |c| option_value.is_a?(c) } &&
-                            option_value.zero?
+                      elsif option_value.is_a?(Numeric) && option_value.zero?
                         ".divided_by_0"
                       else
                         ".default"
@@ -56,13 +191,20 @@ module Servactory
           )
         end
 
+        # Generates error message for internal validation failure.
+        #
+        # @param service [Object] Service context
+        # @param internal [Object] Internal attribute
+        # @param value [Object] Failed value
+        # @param option_name [Symbol] Option name
+        # @param option_value [Object] Divisor value
+        # @return [String] Localized error message
         def message_for_internal_with(service:, internal:, value:, option_name:, option_value:, **) # rubocop:disable Metrics/MethodLength
           i18n_key = "internals.validations.must.dynamic_options.multiple_of"
 
           i18n_key += if option_value.blank?
                         ".blank"
-                      elsif [Numeric, Float, Rational, BigDecimal].any? { |c| option_value.is_a?(c) } &&
-                            option_value.zero?
+                      elsif option_value.is_a?(Numeric) && option_value.zero?
                         ".divided_by_0"
                       else
                         ".default"
@@ -77,13 +219,20 @@ module Servactory
           )
         end
 
+        # Generates error message for output validation failure.
+        #
+        # @param service [Object] Service context
+        # @param output [Object] Output attribute
+        # @param value [Object] Failed value
+        # @param option_name [Symbol] Option name
+        # @param option_value [Object] Divisor value
+        # @return [String] Localized error message
         def message_for_output_with(service:, output:, value:, option_name:, option_value:, **) # rubocop:disable Metrics/MethodLength
           i18n_key = "outputs.validations.must.dynamic_options.multiple_of"
 
           i18n_key += if option_value.blank?
                         ".blank"
-                      elsif [Numeric, Float, Rational, BigDecimal].any? { |c| option_value.is_a?(c) } &&
-                            option_value.zero?
+                      elsif option_value.is_a?(Numeric) && option_value.zero?
                         ".divided_by_0"
                       else
                         ".default"

data/lib/servactory/tool_kit/dynamic_options/must.rb

@@ -3,16 +3,129 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Base class for creating custom dynamic validation options.
+      #
+      # ## Purpose
+      #
+      # Must provides a foundation for implementing custom validation rules
+      # that can be applied to service inputs, internals, and outputs.
+      # It handles the complexity of option parsing, condition evaluation,
+      # and error message generation, allowing subclasses to focus on
+      # validation logic.
+      #
+      # ## Usage
+      #
+      # Create a custom validator by inheriting from Must:
+      #
+      # ```ruby
+      # class MyValidator < Servactory::ToolKit::DynamicOptions::Must
+      #   def self.use(option_name = :my_option)
+      #     new(option_name).must(:my_validation)
+      #   end
+      #
+      #   def condition_for_input_with(input:, value:, option:)
+      #     # Return true if valid, false otherwise
+      #     value.meets_criteria?(option.value)
+      #   end
+      #
+      #   def message_for_input_with(input:, value:, option_name:, option_value:, **)
+      #     "Input `#{input.name}` must satisfy #{option_name}"
+      #   end
+      #
+      #   # Implement similar methods for internal and output...
+      # end
+      # ```
+      #
+      # Register in service configuration:
+      #
+      # ```ruby
+      # configuration do
+      #   input_option_helpers([
+      #     MyValidator.use
+      #   ])
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Custom validators support simple mode with direct value:
+      #
+      # ```ruby
+      # input :value, type: Integer, my_option: 10
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Custom validators support advanced mode with custom messages:
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :value, type: Integer, my_option: {
+      #   is: 10,
+      #   message: "Custom validation failed"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :value, type: Integer, my_option: {
+      #   is: 10,
+      #   message: lambda do |input:, value:, option_value:, **|
+      #     "Input `#{input.name}` failed validation with value `#{value}`"
+      #   end
+      # }
+      # ```
+      #
+      # Lambda receives the following parameters:
+      # - For inputs: `input:, option_value:, value:, **`
+      # - For internals: `internal:, option_value:, value:, **`
+      # - For outputs: `output:, option_value:, value:, **`
+      #
+      # ## Architecture
+      #
+      # The class uses a two-phase validation approach:
+      # 1. **Condition phase**: `condition_for_*` methods return boolean
+      # 2. **Message phase**: `message_for_*` methods generate error text
+      #
+      # ## Important Notes
+      #
+      # - Subclasses must implement all six abstract methods
+      # - Option values support both simple mode (`option: value`) and
+      #   advanced mode (`option: { is: value, message: "..." }`)
+      # - Custom messages can be strings or Procs for dynamic generation
       class Must # rubocop:disable Metrics/ClassLength
+        # Value object representing a parsed validation option.
+        #
+        # ## Purpose
+        #
+        # WorkOption normalizes the various ways an option can be specified
+        # (simple value, hash with `:is` key, hash with custom message)
+        # into a consistent interface for validators.
+        #
+        # ## Attributes
+        #
+        # - `name` - The option name symbol (e.g., `:min`, `:max`)
+        # - `value` - The actual validation value (e.g., `10` for `min: 10`)
+        # - `message` - Custom error message (String or Proc), or nil
+        # - `properties` - Additional hash properties passed with the option
         class WorkOption
           attr_reader :name,
                       :value,
                       :message,
                       :properties
 
+          # Creates a new WorkOption by parsing option data.
+          #
+          # @param name [Symbol] The option name
+          # @param data [Object] Raw option value (can be scalar, Hash, etc.)
+          # @param body_key [Symbol] Key to extract value from Hash (default: :is)
+          # @param body_fallback [Object] Default value if data is empty
           def initialize(name, data, body_key:, body_fallback:)
             @name = name
 
+            # Extract the primary value from data.
             @value =
               if data.is_a?(Hash) && data.key?(body_key)
                 data.delete(body_key)
@@ -20,17 +133,29 @@ module Servactory
                 data.presence || body_fallback
               end
 
+            # Extract custom message if provided.
             @message = (data.is_a?(Hash) && data.key?(:message) ? data.delete(:message) : nil)
+
+            # Remaining hash properties become additional configuration.
             @properties = data.is_a?(Hash) ? data : {}
           end
         end
 
+        # Creates a new Must instance.
+        #
+        # @param option_name [Symbol] Name of the option (e.g., :min, :max)
+        # @param body_key [Symbol] Key for extracting value in advanced mode
+        # @param body_fallback [Object] Default value when none provided
         def initialize(option_name, body_key = :is, body_fallback = nil)
           @option_name = option_name
           @body_key = body_key
           @body_fallback = body_fallback
         end
 
+        # Creates an OptionHelper for registration with Servactory.
+        #
+        # @param name [Symbol] Internal validation name
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def must(name)
           Servactory::Maintenance::Attributes::OptionHelper.new(
             name: @option_name,
@@ -42,6 +167,10 @@ module Servactory
           )
         end
 
+        # Builds the equivalence lambda for option transformation.
+        #
+        # @param name [Symbol] Validation name
+        # @return [Proc] Lambda that transforms option data to must format
         def equivalent_with(name)
           lambda do |data|
             option = WorkOption.new(@option_name, data, body_key: @body_key, body_fallback: @body_fallback)
@@ -54,6 +183,10 @@ module Servactory
           end
         end
 
+        # Constructs the must content hash with value and message lambdas.
+        #
+        # @param option [WorkOption] Parsed option data
+        # @return [Hash] Hash with :is and :message keys
         def must_content_with(option)
           {
             is: must_content_value_with(option),
@@ -63,6 +196,10 @@ module Servactory
 
         ########################################################################
 
+        # Builds the validation condition lambda.
+        #
+        # @param option [WorkOption] Parsed option data
+        # @return [Proc] Lambda that evaluates validation condition
         def must_content_value_with(option)
           lambda do |value:, input: nil, internal: nil, output: nil|
             if input.present? && input.input?
@@ -75,6 +212,15 @@ module Servactory
           end
         end
 
+        # Builds the error message lambda.
+        #
+        # Handles three message sources:
+        # 1. Custom Proc message (called with context)
+        # 2. Custom String message (returned as-is)
+        # 3. Default message from subclass implementation
+        #
+        # @param option [WorkOption] Parsed option data
+        # @return [Proc] Lambda that generates error message
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def must_content_message_with(option)
           is_option_message_present = option.message.present?
@@ -132,26 +278,74 @@ module Servactory
 
         ########################################################################
 
+        # Validates condition for input attribute.
+        #
+        # @abstract Subclasses must implement this method
+        # @param input [Object] Input attribute object
+        # @param value [Object] Current value being validated
+        # @param option [WorkOption] Validation option configuration
+        # @return [Boolean] true if valid, false otherwise
+        # @raise [RuntimeError] If not implemented in subclass
         def condition_for_input_with(**)
           raise "Need to implement `condition_for_input_with(**attributes)` method"
         end
 
+        # Validates condition for internal attribute.
+        #
+        # @abstract Subclasses must implement this method
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] Current value being validated
+        # @param option [WorkOption] Validation option configuration
+        # @return [Boolean] true if valid, false otherwise
+        # @raise [RuntimeError] If not implemented in subclass
         def condition_for_internal_with(**)
           raise "Need to implement `condition_for_internal_with(**attributes)` method"
         end
 
+        # Validates condition for output attribute.
+        #
+        # @abstract Subclasses must implement this method
+        # @param output [Object] Output attribute object
+        # @param value [Object] Current value being validated
+        # @param option [WorkOption] Validation option configuration
+        # @return [Boolean] true if valid, false otherwise
+        # @raise [RuntimeError] If not implemented in subclass
         def condition_for_output_with(**)
           raise "Need to implement `condition_for_output_with(**attributes)` method"
         end
 
+        # Generates error message for input validation failure.
+        #
+        # @abstract Subclasses must implement this method
+        # @param input [Object] Input attribute object
+        # @param option_name [Symbol] Name of the failed option
+        # @param option_value [Object] Expected value
+        # @return [String] Human-readable error message
+        # @raise [RuntimeError] If not implemented in subclass
         def message_for_input_with(**)
           raise "Need to implement `message_for_input_with(**attributes)` method"
         end
 
+        # Generates error message for internal validation failure.
+        #
+        # @abstract Subclasses must implement this method
+        # @param internal [Object] Internal attribute object
+        # @param option_name [Symbol] Name of the failed option
+        # @param option_value [Object] Expected value
+        # @return [String] Human-readable error message
+        # @raise [RuntimeError] If not implemented in subclass
         def message_for_internal_with(**)
           raise "Need to implement `message_for_internal_with(**attributes)` method"
         end
 
+        # Generates error message for output validation failure.
+        #
+        # @abstract Subclasses must implement this method
+        # @param output [Object] Output attribute object
+        # @param option_name [Symbol] Name of the failed option
+        # @param option_value [Object] Expected value
+        # @return [String] Human-readable error message
+        # @raise [RuntimeError] If not implemented in subclass
         def message_for_output_with(**)
           raise "Need to implement `message_for_output_with(**attributes)` method"
         end