servactory 2.16.0 → 3.0.0.rc1

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

@@ -3,60 +3,262 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Validates that attribute value is included in a specified set.
+      #
+      # ## Purpose
+      #
+      # Inclusion provides set membership validation for attributes.
+      # It ensures that the value is present within a predefined list
+      # of acceptable values. This is similar to ActiveModel's inclusion
+      # validation and is useful for enum-like constraints.
+      #
+      # ## Usage
+      #
+      # This option is **included by default** for inputs, internals, and outputs.
+      # No registration required.
+      #
+      # Use in your service definition:
+      #
+      # ```ruby
+      # class CreateUserService < ApplicationService::Base
+      #   input :role, type: String, inclusion: { in: %w[admin user guest] }
+      #   input :status, type: Symbol, inclusion: { in: [:active, :inactive] }
+      #   input :level, type: Integer, inclusion: { in: [1, 2, 3, 4, 5] }
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Specify inclusion values directly:
+      #
+      # ```ruby
+      # class CreateUserService < ApplicationService::Base
+      #   input :role, type: String, inclusion: %w[admin user guest]
+      #   input :status, type: Symbol, inclusion: [:active, :inactive]
+      #   input :level, type: Integer, inclusion: 1..10
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify inclusion with custom error message using a hash.
+      # Note: Advanced mode uses `:in` key (not `:is`).
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :role, type: String, inclusion: {
+      #   in: %w[admin user guest],
+      #   message: "Input `role` must be one of: admin, user, guest"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :role, type: String, inclusion: {
+      #   in: %w[admin user guest],
+      #   message: lambda do |input:, value:, option_value:, **|
+      #     "Input `#{input.name}` has invalid value `#{value}`, allowed: #{option_value.join(', ')}"
+      #   end
+      # }
+      # ```
+      #
+      # Lambda receives the following parameters:
+      # - For inputs: `input:, value:, option_value:, reason:, **`
+      # - For internals: `internal:, value:, option_value:, reason:, **`
+      # - For outputs: `output:, value:, option_value:, reason:, **`
+      #
+      # ## Validation Rules
+      #
+      # - Value must be present in the inclusion list
+      # - Supports arrays as inclusion sets
+      # - Optional inputs with nil value validate against default
+      # - Returns `:invalid_option` error if inclusion set is nil
+      #
+      # ## Important Notes
+      #
+      # - Use `inclusion: { in: [...] }` syntax for specifying allowed values
+      # - Single values are automatically wrapped in an array
+      # - For optional inputs with nil value, validates default if present
+      # - Range objects ARE supported natively: `(1..10)`, `(1..)`, `(..100)`
+      # - Mixed syntax supported: `[1..5, 10, 15..20]` checks value against all elements
       class Inclusion < Must
+        # Creates an Inclusion validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :inclusion)
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def self.use(option_name = :inclusion)
           instance = new(option_name, :in)
           instance.must(:be_inclusion)
         end
 
-        def condition_for_input_with(input:, value:, option:) # rubocop:disable Naming/PredicateMethod
+        # Validates inclusion condition for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Inclusion configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
+        def condition_for_input_with(input:, value:, option:) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+          return [false, :invalid_option] if option.value.nil?
+
+          inclusion_values = normalize_inclusion_values(option.value)
+
+          # Required inputs or optional with non-nil value.
           if input.required? || (input.optional? && !value.nil?) # rubocop:disable Style/IfUnlessModifier
-            return option.value.include?(value)
+            return value_in_inclusion?(inclusion_values, value)
           end
 
-          if input.optional? && value.nil? && !input.default.nil? # rubocop:disable Style/IfUnlessModifier
-            return option.value.include?(input.default)
+          # Optional with nil value but has default.
+          if input.optional? && value.nil? && !input.default.nil?
+            return value_in_inclusion?(inclusion_values, input.default)
           end
 
           true
         end
 
-        def condition_for_internal_with(value:, option:, **) # rubocop:disable Naming/PredicateMethod
-          option.value.include?(value)
+        # Validates inclusion condition for internal attribute.
+        #
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Inclusion configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
+        def condition_for_internal_with(value:, option:, **)
+          return [false, :invalid_option] if option.value.nil?
+
+          inclusion_values = normalize_inclusion_values(option.value)
+          value_in_inclusion?(inclusion_values, value)
         end
 
-        def condition_for_output_with(value:, option:, **) # rubocop:disable Naming/PredicateMethod
-          option.value.include?(value)
+        # Validates inclusion condition for output attribute.
+        #
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Inclusion configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
+        def condition_for_output_with(value:, option:, **)
+          return [false, :invalid_option] if option.value.nil?
+
+          inclusion_values = normalize_inclusion_values(option.value)
+          value_in_inclusion?(inclusion_values, value)
         end
 
         ########################################################################
 
-        def message_for_input_with(service:, input:, value:, option_value:, **)
+        # Generates error message for input validation failure.
+        #
+        # @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] Allowed values
+        # @param reason [Symbol] Failure reason
+        # @return [String] Localized error message
+        def message_for_input_with(service:, input:, value:, option_name:, option_value:, reason:, **)
+          i18n_key = "inputs.validations.must.dynamic_options.inclusion"
+          i18n_key += reason.present? ? ".#{reason}" : ".default"
+
           service.translate(
-            "inputs.validations.must.dynamic_options.inclusion.default",
+            i18n_key,
             input_name: input.name,
             value: value.inspect,
-            input_inclusion: option_value.inspect
+            input_inclusion: option_value.inspect,
+            option_name:
           )
         end
 
-        def message_for_internal_with(service:, internal:, value:, option_value:, **)
+        # 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] Allowed values
+        # @param reason [Symbol] Failure reason
+        # @return [String] Localized error message
+        def message_for_internal_with(service:, internal:, value:, option_name:, option_value:, reason:, **)
+          i18n_key = "internals.validations.must.dynamic_options.inclusion"
+          i18n_key += reason.present? ? ".#{reason}" : ".default"
+
           service.translate(
-            "internals.validations.must.dynamic_options.inclusion.default",
+            i18n_key,
             internal_name: internal.name,
             value: value.inspect,
-            internal_inclusion: option_value.inspect
+            internal_inclusion: option_value.inspect,
+            option_name:
           )
         end
 
-        def message_for_output_with(service:, output:, value:, option_value:, **)
+        # 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] Allowed values
+        # @param reason [Symbol] Failure reason
+        # @return [String] Localized error message
+        def message_for_output_with(service:, output:, value:, option_name:, option_value:, reason:, **)
+          i18n_key = "outputs.validations.must.dynamic_options.inclusion"
+          i18n_key += reason.present? ? ".#{reason}" : ".default"
+
           service.translate(
-            "outputs.validations.must.dynamic_options.inclusion.default",
+            i18n_key,
             output_name: output.name,
             value: value.inspect,
-            output_inclusion: option_value.inspect
+            output_inclusion: option_value.inspect,
+            option_name:
           )
         end
+
+        private
+
+        # Normalizes inclusion values, preserving Range objects.
+        #
+        # @param option_value [Range, Array, Object] Inclusion value(s)
+        # @return [Range, Array] Range preserved as-is, others normalized to array
+        def normalize_inclusion_values(option_value)
+          case option_value
+          when Range, Array then option_value
+          else [option_value]
+          end
+        end
+
+        # Checks if value is included in the normalized inclusion values.
+        #
+        # @param inclusion_values [Range, Array] Normalized inclusion set
+        # @param value [Object] Value to check
+        # @return [Boolean] true if value is in inclusion set
+        def value_in_inclusion?(inclusion_values, value)
+          case inclusion_values
+          when Range
+            range_covers?(inclusion_values, value)
+          when Array
+            inclusion_values.any? { |element| element_matches?(element, value) }
+          else
+            inclusion_values == value
+          end
+        end
+
+        # Checks if value matches a single element (Range or scalar).
+        #
+        # @param element [Range, Object] Element to match against
+        # @param value [Object] Value to check
+        # @return [Boolean] true if matches
+        def element_matches?(element, value)
+          element.is_a?(Range) ? range_covers?(element, value) : element == value
+        end
+
+        # Safely checks if Range covers the value.
+        #
+        # @param range [Range] Range to check against
+        # @param value [Object] Value to check
+        # @return [Boolean] true if range covers value, false on type errors
+        def range_covers?(range, value)
+          return false if value.nil?
+
+          range.cover?(value)
+        rescue ArgumentError, TypeError
+          false
+        end
       end
     end
   end

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

@@ -3,28 +3,147 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Validates that attribute value does not exceed a maximum limit.
+      #
+      # ## Purpose
+      #
+      # Max provides upper bound validation for numeric values and
+      # size-based validation for collections and strings. It ensures
+      # that values stay within acceptable limits.
+      #
+      # ## 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::Max.use
+      #   ])
+      #
+      #   internal_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Max.use
+      #   ])
+      #
+      #   output_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Max.use
+      #   ])
+      # end
+      # ```
+      #
+      # Use in your service definition:
+      #
+      # ```ruby
+      # class ProcessDataService < ApplicationService::Base
+      #   input :count, type: Integer, max: 100
+      #   input :name, type: String, max: 255
+      #   input :items, type: Array, max: 50
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Specify maximum value directly:
+      #
+      # ```ruby
+      # class ProcessDataService < ApplicationService::Base
+      #   input :count, type: Integer, max: 100
+      #   input :name, type: String, max: 255
+      #   input :items, type: Array, max: 50
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify maximum with custom error message using a hash:
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :count, type: Integer, max: {
+      #   is: 100,
+      #   message: "Input `count` must not exceed 100"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :count, type: Integer, max: {
+      #   is: 100,
+      #   message: lambda do |input:, value:, option_value:, **|
+      #     "Input `#{input.name}` must be <= #{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:, **`
+      #
+      # ## Validation Rules
+      #
+      # - For Integer: value must be <= max
+      # - For String/Array/Hash: size must be <= max
+      # - Objects must respond to `:size` method for size-based validation
+      #
+      # ## Important Notes
+      #
+      # - Returns false if value doesn't support size comparison
+      # - Combines well with `:min` for range validation
       class Max < Must
+        # Creates a Max validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :max)
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def self.use(option_name = :max)
           new(option_name).must(:be_less_than_or_equal_to)
         end
 
+        # Validates max condition for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Max configuration
+        # @return [Boolean] true if valid
         def condition_for_input_with(...)
           common_condition_with(...)
         end
 
+        # Validates max condition for internal attribute.
+        #
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Max configuration
+        # @return [Boolean] true if valid
         def condition_for_internal_with(...)
           common_condition_with(...)
         end
 
+        # Validates max condition for output attribute.
+        #
+        # @param output [Object] Output attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Max 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] Max configuration
+        # @return [Boolean] true if value <= max
         def common_condition_with(value:, option:, **) # rubocop:disable Naming/PredicateMethod
           case value
           when Integer
+            # Direct numeric comparison.
             value <= option.value
           else
+            # Size-based comparison for collections and strings.
             return false unless value.respond_to?(:size)
 
             value.size <= option.value
@@ -33,6 +152,14 @@ module Servactory
 
         ########################################################################
 
+        # Generates error message for input validation failure.
+        #
+        # @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] Maximum limit
+        # @return [String] Localized error message
         def message_for_input_with(service:, input:, value:, option_name:, option_value:, **)
           service.translate(
             "inputs.validations.must.dynamic_options.max.default",
@@ -43,6 +170,14 @@ 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] Maximum limit
+        # @return [String] Localized error message
         def message_for_internal_with(service:, internal:, value:, option_name:, option_value:, **)
           service.translate(
             "internals.validations.must.dynamic_options.max.default",
@@ -53,6 +188,14 @@ 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] Maximum limit
+        # @return [String] Localized error message
         def message_for_output_with(service:, output:, value:, option_name:, option_value:, **)
           service.translate(
             "outputs.validations.must.dynamic_options.max.default",

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

@@ -3,28 +3,147 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Validates that attribute value meets a minimum threshold.
+      #
+      # ## Purpose
+      #
+      # Min provides lower bound validation for numeric values and
+      # size-based validation for collections and strings. It ensures
+      # that values meet minimum requirements.
+      #
+      # ## 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::Min.use
+      #   ])
+      #
+      #   internal_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Min.use
+      #   ])
+      #
+      #   output_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Min.use
+      #   ])
+      # end
+      # ```
+      #
+      # Use in your service definition:
+      #
+      # ```ruby
+      # class ProcessDataService < ApplicationService::Base
+      #   input :age, type: Integer, min: 18
+      #   input :password, type: String, min: 8
+      #   input :tags, type: Array, min: 1
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Specify minimum value directly:
+      #
+      # ```ruby
+      # class ProcessDataService < ApplicationService::Base
+      #   input :age, type: Integer, min: 18
+      #   input :password, type: String, min: 8
+      #   input :tags, type: Array, min: 1
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify minimum with custom error message using a hash:
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :age, type: Integer, min: {
+      #   is: 18,
+      #   message: "Input `age` must be at least 18"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :age, type: Integer, min: {
+      #   is: 18,
+      #   message: lambda do |input:, value:, option_value:, **|
+      #     "Input `#{input.name}` must be >= #{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:, **`
+      #
+      # ## Validation Rules
+      #
+      # - For Integer: value must be >= min
+      # - For String/Array/Hash: size must be >= min
+      # - Objects must respond to `:size` method for size-based validation
+      #
+      # ## Important Notes
+      #
+      # - Returns false if value doesn't support size comparison
+      # - Combines well with `:max` for range validation
       class Min < Must
+        # Creates a Min validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :min)
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def self.use(option_name = :min)
           new(option_name).must(:be_greater_than_or_equal_to)
         end
 
+        # Validates min condition for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Min configuration
+        # @return [Boolean] true if valid
         def condition_for_input_with(...)
           common_condition_with(...)
         end
 
+        # Validates min condition for internal attribute.
+        #
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Min configuration
+        # @return [Boolean] true if valid
         def condition_for_internal_with(...)
           common_condition_with(...)
         end
 
+        # Validates min condition for output attribute.
+        #
+        # @param output [Object] Output attribute object
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Min 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] Min configuration
+        # @return [Boolean] true if value >= min
         def common_condition_with(value:, option:, **) # rubocop:disable Naming/PredicateMethod
           case value
           when Integer
+            # Direct numeric comparison.
             value >= option.value
           else
+            # Size-based comparison for collections and strings.
             return false unless value.respond_to?(:size)
 
             value.size >= option.value
@@ -33,6 +152,14 @@ module Servactory
 
         ########################################################################
 
+        # Generates error message for input validation failure.
+        #
+        # @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] Minimum limit
+        # @return [String] Localized error message
         def message_for_input_with(service:, input:, value:, option_name:, option_value:, **)
           service.translate(
             "inputs.validations.must.dynamic_options.min.default",
@@ -43,6 +170,14 @@ 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] Minimum limit
+        # @return [String] Localized error message
         def message_for_internal_with(service:, internal:, value:, option_name:, option_value:, **)
           service.translate(
             "internals.validations.must.dynamic_options.min.default",
@@ -53,6 +188,14 @@ 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] Minimum limit
+        # @return [String] Localized error message
         def message_for_output_with(service:, output:, value:, option_name:, option_value:, **)
           service.translate(
             "outputs.validations.must.dynamic_options.min.default",