servactory 2.16.0 → 3.0.0.rc1

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

@@ -3,45 +3,172 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Validates that collection elements are of specified types.
+      #
+      # ## Purpose
+      #
+      # ConsistsOf ensures that all elements within an Array or collection
+      # attribute match one of the specified types. This is essential for
+      # validating homogeneous collections where each element must conform
+      # to expected types.
+      #
+      # ## Usage
+      #
+      # This option is **included by default** for inputs, internals, and outputs.
+      # No registration required for basic usage.
+      #
+      # To extend supported collection types (e.g., add `ActiveRecord::Relation`),
+      # use the `collection_mode_class_names` configuration:
+      #
+      # ```ruby
+      # configuration do
+      #   collection_mode_class_names([ActiveRecord::Relation])
+      # end
+      # ```
+      #
+      # ## Simple Mode
+      #
+      # Specify type directly as the option value:
+      #
+      # ```ruby
+      # class ProcessUsersService < ApplicationService::Base
+      #   input :user_ids, type: Array, consists_of: Integer
+      #   input :tags, type: Array, consists_of: [String, Symbol]
+      #   input :scores, type: Array, consists_of: Float
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify type with custom error message using a hash.
+      # Note: Advanced mode uses `:type` key (not `:is` like other options).
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :ids, type: Array, consists_of: {
+      #   type: String,
+      #   message: "Input `ids` must be an array of `String`"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :ids, type: Array, consists_of: {
+      #   type: String,
+      #   message: lambda do |input:, option_value:, **|
+      #     "Input `#{input.name}` must be an array of `#{Array(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
+      #
+      # - Collection must be of a registered collection type (Array, Set, etc.)
+      # - All elements are flattened before validation (nested arrays supported)
+      # - Empty collections pass validation for optional input attributes only
+      # - For internal/output attributes, presence check is always performed
+      # - For optional inputs with non-empty collections, presence check is performed
+      # - Multiple types can be specified as an array
+      #
+      # ## Important Notes
+      #
+      # - Use `consists_of: false` to disable validation
+      # - NilClass in types allows nil elements in the collection
+      # - Nested arrays are automatically flattened for validation
+      # - Advanced mode uses `:type` key (not `:is` like other options)
+      # - Numeric types use exact class matching (Integer != Float)
       class ConsistsOf < Must
+        # Creates a ConsistsOf validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :consists_of)
+        # @param collection_mode_class_names [Array<Class>] Valid collection types
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def self.use(option_name = :consists_of, collection_mode_class_names:)
           instance = new(option_name, :type, false)
           instance.assign(collection_mode_class_names)
           instance.must(:consists_of)
         end
 
+        # Assigns the list of valid collection class names.
+        #
+        # @param collection_mode_class_names [Array<Class>] Collection types to accept
+        # @return [void]
         def assign(collection_mode_class_names)
           @collection_mode_class_names = collection_mode_class_names
         end
 
+        # Validates element types for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] Collection value to validate
+        # @param option [WorkOption] Type configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def condition_for_input_with(input:, value:, option:)
           common_condition_with(attribute: input, value:, option:)
         end
 
+        # Validates element types for internal attribute.
+        #
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] Collection value to validate
+        # @param option [WorkOption] Type configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def condition_for_internal_with(internal:, value:, option:)
           common_condition_with(attribute: internal, value:, option:)
         end
 
+        # Validates element types for output attribute.
+        #
+        # @param output [Object] Output attribute object
+        # @param value [Object] Collection value to validate
+        # @param option [WorkOption] Type configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def condition_for_output_with(output:, value:, option:)
           common_condition_with(attribute: output, value:, option:)
         end
 
+        # Common validation logic for all attribute types.
+        #
+        # @param attribute [Object] The attribute being validated
+        # @param value [Object] Collection value to validate
+        # @param option [WorkOption] Type configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def common_condition_with(attribute:, value:, option:)
+          # Validation disabled.
           return true if option.value == false
+
+          # Attribute must be a collection type.
           return [false, :wrong_type] unless @collection_mode_class_names.intersect?(attribute.types)
 
+          # Flatten nested arrays for uniform validation.
           values = value.respond_to?(:flatten) ? value&.flatten : value
 
           validate_for!(attribute:, values:, option:)
         end
 
+        # Validates all elements against allowed types.
+        #
+        # @param attribute [Object] The attribute being validated
+        # @param values [Array] Flattened collection elements
+        # @param option [WorkOption] Type configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def validate_for!(attribute:, values:, option:)
           consists_of_types = Array(option.value).uniq
 
+          # Check presence requirements.
           return [false, :required] if fails_presence_validation?(attribute:, values:, consists_of_types:)
 
+          # Empty optional collections are valid.
           return true if values.blank? && attribute.input? && attribute.optional?
 
+          # Verify each element matches allowed types.
           return true if values.all? do |value|
             consists_of_types.include?(value.class)
           end
@@ -49,7 +176,14 @@ module Servactory
           [false, :wrong_element_type]
         end
 
+        # Checks if collection fails presence validation.
+        #
+        # @param attribute [Object] The attribute being validated
+        # @param values [Array] Collection elements
+        # @param consists_of_types [Array<Class>] Allowed types
+        # @return [Boolean] true if validation fails
         def fails_presence_validation?(attribute:, values:, consists_of_types:)
+          # NilClass in types allows nil elements.
           return false if consists_of_types.include?(NilClass)
 
           check_present = proc { _1 && !values.all?(&:present?) }
@@ -63,6 +197,15 @@ 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] Expected types
+        # @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.consists_of"
           i18n_key += reason.present? ? ".#{reason}" : ".default"
@@ -77,6 +220,15 @@ 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] Expected types
+        # @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.consists_of"
           i18n_key += reason.present? ? ".#{reason}" : ".default"
@@ -91,6 +243,15 @@ 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] Expected types
+        # @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.consists_of"
           i18n_key += reason.present? ? ".#{reason}" : ".default"
@@ -105,6 +266,11 @@ module Servactory
           )
         end
 
+        # Extracts type names of elements that don't match expected types.
+        #
+        # @param values [Array, nil] Collection elements
+        # @param option_value [Object] Expected types
+        # @return [String] Comma-separated list of unexpected type names
         def given_type_for(values:, option_value:)
           return "NilClass" if values.nil?
 

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

@@ -3,10 +3,125 @@
 module Servactory
   module ToolKit
     module DynamicOptions
+      # Validates string values against predefined or custom format patterns.
+      #
+      # ## Purpose
+      #
+      # Format provides pattern-based validation for string attributes using
+      # regular expressions and custom validators. It includes built-in formats
+      # for common use cases (UUID, email, date, etc.) and supports custom
+      # format definitions.
+      #
+      # ## 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::Format.use
+      #   ])
+      #
+      #   internal_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Format.use
+      #   ])
+      #
+      #   output_option_helpers([
+      #     Servactory::ToolKit::DynamicOptions::Format.use
+      #   ])
+      # end
+      # ```
+      #
+      # Use built-in formats in your service:
+      #
+      # ```ruby
+      # class MyService < ApplicationService::Base
+      #   input :user_id, type: String, format: :uuid
+      #   input :email, type: String, format: :email
+      #   input :birth_date, type: String, format: :date
+      # end
+      # ```
+      #
+      # Add custom formats:
+      #
+      # ```ruby
+      # Format.use(formats: {
+      #   phone: {
+      #     pattern: /\A\+?[1-9]\d{6,14}\z/,
+      #     validator: ->(value:) { value.present? }
+      #   }
+      # })
+      # ```
+      #
+      # ## Supported Formats
+      #
+      # | Format | Description |
+      # |--------|-------------|
+      # | `:uuid` | Standard UUID format (8-4-4-4-12 hex digits) |
+      # | `:email` | Email address per RFC 2822 |
+      # | `:password` | 8-16 chars with digit, lowercase, uppercase |
+      # | `:duration` | ISO 8601 duration (e.g., "PT1H30M") |
+      # | `:date` | Parseable date string |
+      # | `:datetime` | Parseable datetime string |
+      # | `:time` | Parseable time string |
+      # | `:boolean` | Truthy boolean string ("true" or "1") |
+      #
+      # ## Simple Mode
+      #
+      # Specify format directly as the option value:
+      #
+      # ```ruby
+      # class ValidateUserService < ApplicationService::Base
+      #   input :uuid, type: String, format: :uuid
+      #   input :email, type: String, format: :email
+      #   input :password, type: String, format: :password
+      # end
+      # ```
+      #
+      # ## Advanced Mode
+      #
+      # Specify format with custom error message using a hash:
+      #
+      # With static message:
+      #
+      # ```ruby
+      # input :email, type: String, format: {
+      #   is: :email,
+      #   message: "Input `email` must be a valid email address"
+      # }
+      # ```
+      #
+      # With dynamic lambda message:
+      #
+      # ```ruby
+      # input :email, type: String, format: {
+      #   is: :email,
+      #   message: lambda do |input:, value:, option_value:, **|
+      #     "Input `#{input.name}` with value `#{value}` does not match `#{option_value}` format"
+      #   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:, **`
+      #
+      # ## Important Notes
+      #
+      # - Optional inputs with blank values skip validation
+      # - Custom patterns can be strings or Regexp objects
+      # - Validators receive `value:` keyword argument
+      # - Unknown format names return `:unknown` error
+      # - Format validation is two-phase: pattern check (if defined), then validator callback
+      # - The `:boolean` format pattern matches "true", "false", "0", "1", but validator
+      #   only passes for truthy values ("true", "1"); "false" and "0" will fail validation
       class Format < Must # rubocop:disable Metrics/ClassLength
+        # Built-in format definitions with patterns and validators.
         DEFAULT_FORMATS = {
           uuid: {
-            pattern: /^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/,
+            pattern: /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/,
             validator: ->(value:) { value.present? }
           },
           email: {
@@ -14,11 +129,11 @@ module Servactory
             validator: ->(value:) { value.present? }
           },
           password: {
-            # NOTE: Pattern 4 » https://dev.to/rasaf_ibrahim/write-regex-password-validation-like-a-pro-5175
-            #       Password must contain one digit from 1 to 9, one lowercase letter, one
-            #       uppercase letter, and one underscore, and it must be 8-16 characters long.
-            #       Usage of any other special character and usage of space is optional.
-            pattern: /^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{8,16}$/,
+            # Password must contain one digit from 1 to 9, one lowercase letter, one
+            # uppercase letter, and it must be 8-16 characters long.
+            # Usage of any other special character and space is optional.
+            # Reference: https://dev.to/rasaf_ibrahim/write-regex-password-validation-like-a-pro-5175
+            pattern: /\A(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{8,16}\z/,
             validator: ->(value:) { value.present? }
           },
           duration: {
@@ -54,42 +169,79 @@ module Servactory
             end
           },
           boolean: {
-            pattern: /^(true|false|0|1)$/i,
+            pattern: /\A(true|false|0|1)\z/i,
             validator: ->(value:) { %w[true 1].include?(value&.downcase) }
           }
         }.freeze
         private_constant :DEFAULT_FORMATS
 
+        # Creates a Format validator instance.
+        #
+        # @param option_name [Symbol] The option name (default: :format)
+        # @param formats [Hash] Custom format definitions to merge with defaults
+        # @return [Servactory::Maintenance::Attributes::OptionHelper]
         def self.use(option_name = :format, formats: {})
           instance = new(option_name)
           instance.assign(formats)
           instance.must(:be_in_format)
         end
 
+        # Assigns format definitions, merging with defaults.
+        #
+        # @param formats [Hash] Custom formats to add
+        # @return [void]
         def assign(formats = {})
           @formats = formats.is_a?(Hash) ? DEFAULT_FORMATS.merge(formats) : DEFAULT_FORMATS
         end
 
+        # Validates format condition for input attribute.
+        #
+        # @param input [Object] Input attribute object
+        # @param value [Object] String value to validate
+        # @param option [WorkOption] Format configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def condition_for_input_with(...)
           common_condition_with(...)
         end
 
+        # Validates format condition for internal attribute.
+        #
+        # @param internal [Object] Internal attribute object
+        # @param value [Object] String value to validate
+        # @param option [WorkOption] Format configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def condition_for_internal_with(...)
           common_condition_with(...)
         end
 
+        # Validates format condition for output attribute.
+        #
+        # @param output [Object] Output attribute object
+        # @param value [Object] String value to validate
+        # @param option [WorkOption] Format configuration
+        # @return [Boolean, Array] true if valid, or [false, reason]
         def condition_for_output_with(...)
           common_condition_with(...)
         end
 
+        # Common format validation logic.
+        #
+        # @param value [Object] Value to validate
+        # @param option [WorkOption] Format configuration
+        # @param input [Object, nil] Input attribute if applicable
+        # @param internal [Object, nil] Internal attribute if applicable
+        # @param output [Object, nil] Output attribute if applicable
+        # @return [Boolean, Array] true if valid, or [false, reason]
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def common_condition_with(value:, option:, input: nil, internal: nil, output: nil)
           option_value = option.value&.to_sym
 
+          # Check if format exists.
           return [false, :unknown] unless @formats.key?(option_value)
 
           attribute = Utils.define_attribute_with(input:, internal:, output:)
 
+          # Skip validation for blank optional values.
           if value.blank? &&
              (
                (attribute.input? && attribute.optional?) ||
@@ -103,16 +255,33 @@ module Servactory
 
           format_options = @formats.fetch(option_value)
 
+          # Get pattern from option properties or format definition.
           format_pattern = option.properties.fetch(:pattern, format_options.fetch(:pattern))
 
-          return [false, :wrong_pattern] if format_pattern.present? && !value.match?(Regexp.compile(format_pattern))
+          # Validate against pattern if defined.
+          if format_pattern.present?
+            return [false, :wrong_type] unless value.respond_to?(:match?)
 
+            compiled_pattern = format_pattern.is_a?(Regexp) ? format_pattern : Regexp.compile(format_pattern)
+            return [false, :wrong_pattern] unless value.match?(compiled_pattern)
+          end
+
+          # Run validator callback.
           option.properties.fetch(:validator, format_options.fetch(:validator)).call(value:)
         end
         # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         ########################################################################
 
+        # 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 [Symbol] Format name
+        # @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.format"
           i18n_key += reason.present? ? ".#{reason}" : ".default"
@@ -126,6 +295,15 @@ 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 [Symbol] Format name
+        # @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.format"
           i18n_key += reason.present? ? ".#{reason}" : ".default"
@@ -139,6 +317,15 @@ 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 [Symbol] Format name
+        # @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.format"
           i18n_key += reason.present? ? ".#{reason}" : ".default"