cmdx 0.5.0 → 1.0.0

data/lib/cmdx/validators/format.rb

@@ -2,19 +2,113 @@
 
 module CMDx
   module Validators
+    # Format validator for parameter validation using regular expressions.
+    #
+    # The Format validator validates parameter values against regular expression
+    # patterns. It supports both positive matching (with) and negative matching
+    # (without) patterns, and can combine both for complex format validation.
+    #
+    # @example Basic format validation with positive pattern
+    #   class ProcessUserTask < CMDx::Task
+    #     required :email, format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }
+    #     required :phone, format: { with: /\A\d{3}-\d{3}-\d{4}\z/ }
+    #   end
+    #
+    # @example Format validation with negative pattern
+    #   class ProcessContentTask < CMDx::Task
+    #     required :username, format: { without: /\A(admin|root|system)\z/i }
+    #     required :content, format: { without: /spam|viagra/i }
+    #   end
+    #
+    # @example Combined positive and negative patterns
+    #   class ProcessUserTask < CMDx::Task
+    #     required :password, format: {
+    #       with: /\A(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}\z/,  # Strong password
+    #       without: /password|123456/i  # Common weak patterns
+    #     }
+    #   end
+    #
+    # @example Custom error message
+    #   class ProcessUserTask < CMDx::Task
+    #     required :email, format: {
+    #       with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
+    #       message: "must be a valid email address"
+    #     }
+    #   end
+    #
+    # @example Format validation behavior
+    #   # Positive pattern matching
+    #   Format.call("user@example.com", format: { with: /@/ })     # passes
+    #   Format.call("invalid-email", format: { with: /@/ })        # raises ValidationError
+    #
+    #   # Negative pattern matching
+    #   Format.call("username", format: { without: /admin/ })      # passes
+    #   Format.call("admin", format: { without: /admin/ })         # raises ValidationError
+    #
+    # @see CMDx::Parameter Parameter validation integration
+    # @see CMDx::ValidationError Raised when validation fails
     module Format
 
       module_function
 
+      # Validates that a parameter value matches the specified format patterns.
+      #
+      # Validates the value against the provided regular expression patterns.
+      # Supports positive matching (with), negative matching (without), or both.
+      # The value must match all specified conditions to pass validation.
+      #
+      # @param value [String] The parameter value to validate
+      # @param options [Hash] Validation configuration options
+      # @option options [Hash] :format Format validation configuration
+      # @option options [Regexp] :format.with Pattern the value must match
+      # @option options [Regexp] :format.without Pattern the value must not match
+      # @option options [String] :format.message Custom error message
+      #
+      # @return [void]
+      # @raise [ValidationError] If value doesn't match the format requirements
+      #
+      # @example Successful positive pattern validation
+      #   Format.call("user@example.com", format: { with: /@/ })
+      #   # => passes without error
+      #
+      # @example Failed positive pattern validation
+      #   Format.call("invalid-email", format: { with: /@/ })
+      #   # => raises ValidationError: "is an invalid format"
+      #
+      # @example Successful negative pattern validation
+      #   Format.call("username", format: { without: /admin/ })
+      #   # => passes without error
+      #
+      # @example Failed negative pattern validation
+      #   Format.call("admin", format: { without: /admin/ })
+      #   # => raises ValidationError: "is an invalid format"
+      #
+      # @example Combined pattern validation
+      #   Format.call("StrongPass123", format: {
+      #     with: /\A(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}\z/,
+      #     without: /password/i
+      #   })
+      #   # => passes without error
+      #
+      # @example Custom error message
+      #   Format.call("weak", format: {
+      #     with: /\A.{8,}\z/,
+      #     message: "must be at least 8 characters"
+      #   })
+      #   # => raises ValidationError: "must be at least 8 characters"
       def call(value, options = {})
-        return if case options[:format]
-                  in { with: with, without: without }
-                    value.match?(with) && !value.match?(without)
-                  in { with: with }
-                    value.match?(with)
-                  in { without: without }
-                    !value.match?(without)
-                  end
+        valid = case options[:format]
+                in { with: with, without: without }
+                  value.match?(with) && !value.match?(without)
+                in { with: with }
+                  value.match?(with)
+                in { without: without }
+                  !value.match?(without)
+                else
+                  false
+                end
+
+        return if valid
 
         raise ValidationError, options.dig(:format, :message) || I18n.t(
           "cmdx.validators.format",

data/lib/cmdx/validators/inclusion.rb

@@ -2,10 +2,103 @@
 
 module CMDx
   module Validators
+    # Inclusion validator for parameter validation against allowed values.
+    #
+    # The Inclusion validator ensures that parameter values ARE within a
+    # specified set of allowed values. It supports both array-based inclusion
+    # (specific values) and range-based inclusion (value ranges).
+    #
+    # @example Basic inclusion validation with array
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :status, inclusion: { in: ['pending', 'processing', 'completed'] }
+    #     required :priority, inclusion: { in: [1, 2, 3, 4, 5] }
+    #   end
+    #
+    # @example Range-based inclusion
+    #   class ProcessUserTask < CMDx::Task
+    #     required :age, inclusion: { in: 18..120 }  # Valid age range
+    #     required :score, inclusion: { within: 0..100 }  # Percentage score
+    #   end
+    #
+    # @example Custom error messages
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :status, inclusion: {
+    #       in: ['pending', 'processing', 'completed'],
+    #       of_message: "must be a valid order status"
+    #     }
+    #     required :age, inclusion: {
+    #       in: 18..120,
+    #       in_message: "must be between %{min} and %{max} years old"
+    #     }
+    #   end
+    #
+    # @example Boolean field validation
+    #   class ProcessUserTask < CMDx::Task
+    #     required :active, inclusion: { in: [true, false] }  # Proper boolean validation
+    #     required :role, inclusion: { in: ['admin', 'user', 'guest'] }
+    #   end
+    #
+    # @example Inclusion validation behavior
+    #   # Array inclusion
+    #   Inclusion.call("pending", inclusion: { in: ['pending', 'active'] })     # passes
+    #   Inclusion.call("cancelled", inclusion: { in: ['pending', 'active'] })   # raises ValidationError
+    #
+    #   # Range inclusion
+    #   Inclusion.call(25, inclusion: { in: 18..65 })  # passes
+    #   Inclusion.call(15, inclusion: { in: 18..65 })  # raises ValidationError
+    #
+    # @see CMDx::Validators::Exclusion For validating values must not be in a set
+    # @see CMDx::Parameter Parameter validation integration
+    # @see CMDx::ValidationError Raised when validation fails
     module Inclusion
 
       extend self
 
+      # Validates that a parameter value is in the allowed set.
+      #
+      # Checks that the value is present in the specified array or range
+      # of allowed values. Raises ValidationError if the value is not found
+      # in the inclusion set.
+      #
+      # @param value [Object] The parameter value to validate
+      # @param options [Hash] Validation configuration options
+      # @option options [Hash] :inclusion Inclusion validation configuration
+      # @option options [Array, Range] :inclusion.in Values/range to include
+      # @option options [Array, Range] :inclusion.within Alias for :in
+      # @option options [String] :inclusion.of_message Error message for array inclusion
+      # @option options [String] :inclusion.in_message Error message for range inclusion
+      # @option options [String] :inclusion.within_message Alias for :in_message
+      # @option options [String] :inclusion.message General error message override
+      #
+      # @return [void]
+      # @raise [ValidationError] If value is not found in the inclusion set
+      #
+      # @example Array inclusion validation
+      #   Inclusion.call("active", inclusion: { in: ['active', 'pending'] })
+      #   # => passes without error
+      #
+      # @example Failed array inclusion
+      #   Inclusion.call("cancelled", inclusion: { in: ['active', 'pending'] })
+      #   # => raises ValidationError: "must be one of: \"active\", \"pending\""
+      #
+      # @example Range inclusion validation
+      #   Inclusion.call(25, inclusion: { in: 18..65 })
+      #   # => passes without error
+      #
+      # @example Failed range inclusion
+      #   Inclusion.call(15, inclusion: { in: 18..65 })
+      #   # => raises ValidationError: "must be within 18 and 65"
+      #
+      # @example Boolean validation
+      #   Inclusion.call(true, inclusion: { in: [true, false] })
+      #   # => passes without error
+      #
+      # @example Custom error messages
+      #   Inclusion.call("invalid", inclusion: {
+      #     in: ['valid', 'pending'],
+      #     of_message: "status must be valid or pending"
+      #   })
+      #   # => raises ValidationError: "status must be valid or pending"
       def call(value, options = {})
         values = options.dig(:inclusion, :in) ||
                  options.dig(:inclusion, :within)
@@ -19,6 +112,11 @@ module CMDx
 
       private
 
+      # Raises validation error for array-based inclusion violations.
+      #
+      # @param values [Array] The allowed values array
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_of_validation_error!(values, options)
         values  = values.map(&:inspect).join(", ")
         message = options.dig(:inclusion, :of_message) ||
@@ -32,6 +130,12 @@ module CMDx
         )
       end
 
+      # Raises validation error for range-based inclusion violations.
+      #
+      # @param min [Object] Range minimum value
+      # @param max [Object] Range maximum value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_within_validation_error!(min, max, options)
         message = options.dig(:inclusion, :in_message) ||
                   options.dig(:inclusion, :within_message) ||

data/lib/cmdx/validators/length.rb

@@ -2,10 +2,106 @@
 
 module CMDx
   module Validators
+    # Length validator for parameter validation based on size constraints.
+    #
+    # The Length validator validates the length/size of parameter values such as
+    # strings, arrays, and other objects that respond to #length. It supports
+    # various constraint types including ranges, boundaries, and exact lengths.
+    #
+    # @example Range-based length validation
+    #   class ProcessUserTask < CMDx::Task
+    #     required :username, length: { within: 3..20 }
+    #     required :password, length: { in: 8..128 }
+    #     required :bio, length: { not_within: 500..1000 }  # Avoid medium length
+    #   end
+    #
+    # @example Boundary length validation
+    #   class ProcessContentTask < CMDx::Task
+    #     required :title, length: { min: 5 }
+    #     required :description, length: { max: 500 }
+    #     required :slug, length: { min: 3, max: 50 }  # Combined min/max
+    #   end
+    #
+    # @example Exact length validation
+    #   class ProcessCodeTask < CMDx::Task
+    #     required :country_code, length: { is: 2 }  # ISO country codes
+    #     required :postal_code, length: { is_not: 4 }  # Avoid 4-digit codes
+    #   end
+    #
+    # @example Custom error messages
+    #   class ProcessUserTask < CMDx::Task
+    #     required :username, length: {
+    #       within: 3..20,
+    #       within_message: "must be between %{min} and %{max} characters"
+    #     }
+    #     required :password, length: {
+    #       min: 8,
+    #       min_message: "must be at least %{min} characters for security"
+    #     }
+    #   end
+    #
+    # @example Length validation behavior
+    #   # String length validation
+    #   Length.call("hello", length: { min: 3 })      # passes (length: 5)
+    #   Length.call("hi", length: { min: 3 })         # raises ValidationError
+    #
+    #   # Array length validation
+    #   Length.call([1, 2, 3], length: { is: 3 })     # passes
+    #   Length.call([1, 2], length: { is: 3 })        # raises ValidationError
+    #
+    # @see CMDx::Validators::Numeric For numeric value validation
+    # @see CMDx::Parameter Parameter validation integration
+    # @see CMDx::ValidationError Raised when validation fails
     module Length
 
       extend self
 
+      # Validates that a parameter value meets the specified length constraints.
+      #
+      # Validates the length of the value using the specified constraint type.
+      # Only one constraint option can be used at a time, except for :min and :max
+      # which can be combined together.
+      #
+      # @param value [#length] The parameter value to validate (must respond to #length)
+      # @param options [Hash] Validation configuration options
+      # @option options [Hash] :length Length validation configuration
+      # @option options [Range] :length.within Allowed length range
+      # @option options [Range] :length.not_within Forbidden length range
+      # @option options [Range] :length.in Alias for :within
+      # @option options [Range] :length.not_in Alias for :not_within
+      # @option options [Integer] :length.min Minimum allowed length
+      # @option options [Integer] :length.max Maximum allowed length
+      # @option options [Integer] :length.is Exact required length
+      # @option options [Integer] :length.is_not Forbidden exact length
+      # @option options [String] :length.*_message Custom error messages for each constraint
+      #
+      # @return [void]
+      # @raise [ValidationError] If value doesn't meet the length constraints
+      # @raise [ArgumentError] If no valid length constraint options are provided
+      #
+      # @example Range validation
+      #   Length.call("hello", length: { within: 3..10 })
+      #   # => passes without error
+      #
+      # @example Failed range validation
+      #   Length.call("hi", length: { within: 3..10 })
+      #   # => raises ValidationError: "length must be within 3 and 10"
+      #
+      # @example Minimum length validation
+      #   Length.call("password123", length: { min: 8 })
+      #   # => passes without error
+      #
+      # @example Combined min/max validation
+      #   Length.call("username", length: { min: 3, max: 20 })
+      #   # => passes without error
+      #
+      # @example Exact length validation
+      #   Length.call("US", length: { is: 2 })
+      #   # => passes without error (country code)
+      #
+      # @example Array length validation
+      #   Length.call([1, 2, 3, 4], length: { max: 5 })
+      #   # => passes without error
       def call(value, options = {})
         case options[:length]
         in { within: within }
@@ -33,6 +129,12 @@ module CMDx
 
       private
 
+      # Raises validation error for range-based length violations.
+      #
+      # @param min [Integer] Range minimum length
+      # @param max [Integer] Range maximum length
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_within_validation_error!(min, max, options)
         message = options.dig(:length, :within_message) ||
                   options.dig(:length, :in_message) ||
@@ -47,6 +149,12 @@ module CMDx
         )
       end
 
+      # Raises validation error for forbidden range violations.
+      #
+      # @param min [Integer] Range minimum length
+      # @param max [Integer] Range maximum length
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_not_within_validation_error!(min, max, options)
         message = options.dig(:length, :not_within_message) ||
                   options.dig(:length, :not_in_message) ||
@@ -61,6 +169,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for minimum length violations.
+      #
+      # @param min [Integer] Minimum required length
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_min_validation_error!(min, options)
         message = options.dig(:length, :min_message) ||
                   options.dig(:length, :message)
@@ -73,6 +186,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for maximum length violations.
+      #
+      # @param max [Integer] Maximum allowed length
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_max_validation_error!(max, options)
         message = options.dig(:length, :max_message) ||
                   options.dig(:length, :message)
@@ -85,6 +203,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for exact length violations.
+      #
+      # @param is [Integer] Required exact length
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_is_validation_error!(is, options)
         message = options.dig(:length, :is_message) ||
                   options.dig(:length, :message)
@@ -97,6 +220,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for forbidden exact length violations.
+      #
+      # @param is_not [Integer] Forbidden exact length
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_is_not_validation_error!(is_not, options)
         message = options.dig(:length, :is_not_message) ||
                   options.dig(:length, :message)

data/lib/cmdx/validators/numeric.rb

@@ -2,10 +2,106 @@
 
 module CMDx
   module Validators
+    # Numeric validator for parameter validation based on numeric value constraints.
+    #
+    # The Numeric validator validates numeric parameter values against various
+    # constraints including ranges, boundaries, and exact values. It works with
+    # any numeric type including integers, floats, decimals, and other numeric objects.
+    #
+    # @example Range-based numeric validation
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :quantity, numeric: { within: 1..100 }
+    #     required :price, numeric: { in: 0.01..999.99 }
+    #     required :discount, numeric: { not_within: 90..100 }  # Avoid excessive discounts
+    #   end
+    #
+    # @example Boundary numeric validation
+    #   class ProcessUserTask < CMDx::Task
+    #     required :age, numeric: { min: 18 }
+    #     required :score, numeric: { max: 100 }
+    #     required :rating, numeric: { min: 1, max: 5 }  # Combined min/max
+    #   end
+    #
+    # @example Exact numeric validation
+    #   class ProcessConfigTask < CMDx::Task
+    #     required :version, numeric: { is: 2 }  # Specific version required
+    #     required :legacy_flag, numeric: { is_not: 0 }  # Must not be zero
+    #   end
+    #
+    # @example Custom error messages
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :quantity, numeric: {
+    #       within: 1..100,
+    #       within_message: "must be between %{min} and %{max} items"
+    #     }
+    #     required :age, numeric: {
+    #       min: 18,
+    #       min_message: "must be at least %{min} years old"
+    #     }
+    #   end
+    #
+    # @example Numeric validation behavior
+    #   # Integer validation
+    #   Numeric.call(25, numeric: { min: 18 })         # passes
+    #   Numeric.call(15, numeric: { min: 18 })         # raises ValidationError
+    #
+    #   # Float validation
+    #   Numeric.call(99.99, numeric: { max: 100.0 })   # passes
+    #   Numeric.call(101.5, numeric: { max: 100.0 })   # raises ValidationError
+    #
+    # @see CMDx::Validators::Length For length/size validation
+    # @see CMDx::Parameter Parameter validation integration
+    # @see CMDx::ValidationError Raised when validation fails
     module Numeric
 
       extend self
 
+      # Validates that a parameter value meets the specified numeric constraints.
+      #
+      # Validates the numeric value using the specified constraint type.
+      # Only one constraint option can be used at a time, except for :min and :max
+      # which can be combined together.
+      #
+      # @param value [Numeric] The parameter value to validate (must be numeric)
+      # @param options [Hash] Validation configuration options
+      # @option options [Hash] :numeric Numeric validation configuration
+      # @option options [Range] :numeric.within Allowed value range
+      # @option options [Range] :numeric.not_within Forbidden value range
+      # @option options [Range] :numeric.in Alias for :within
+      # @option options [Range] :numeric.not_in Alias for :not_within
+      # @option options [Numeric] :numeric.min Minimum allowed value
+      # @option options [Numeric] :numeric.max Maximum allowed value
+      # @option options [Numeric] :numeric.is Exact required value
+      # @option options [Numeric] :numeric.is_not Forbidden exact value
+      # @option options [String] :numeric.*_message Custom error messages for each constraint
+      #
+      # @return [void]
+      # @raise [ValidationError] If value doesn't meet the numeric constraints
+      # @raise [ArgumentError] If no valid numeric constraint options are provided
+      #
+      # @example Range validation
+      #   Numeric.call(50, numeric: { within: 1..100 })
+      #   # => passes without error
+      #
+      # @example Failed range validation
+      #   Numeric.call(150, numeric: { within: 1..100 })
+      #   # => raises ValidationError: "must be within 1 and 100"
+      #
+      # @example Minimum value validation
+      #   Numeric.call(25, numeric: { min: 18 })
+      #   # => passes without error
+      #
+      # @example Combined min/max validation
+      #   Numeric.call(3.5, numeric: { min: 1.0, max: 5.0 })
+      #   # => passes without error
+      #
+      # @example Exact value validation
+      #   Numeric.call(42, numeric: { is: 42 })
+      #   # => passes without error
+      #
+      # @example Float validation
+      #   Numeric.call(19.99, numeric: { max: 20.0 })
+      #   # => passes without error
       def call(value, options = {})
         case options[:numeric]
         in { within: within }
@@ -33,6 +129,12 @@ module CMDx
 
       private
 
+      # Raises validation error for range-based numeric violations.
+      #
+      # @param min [Numeric] Range minimum value
+      # @param max [Numeric] Range maximum value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_within_validation_error!(min, max, options)
         message = options.dig(:numeric, :within_message) ||
                   options.dig(:numeric, :in_message) ||
@@ -47,6 +149,12 @@ module CMDx
         )
       end
 
+      # Raises validation error for forbidden range violations.
+      #
+      # @param min [Numeric] Range minimum value
+      # @param max [Numeric] Range maximum value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_not_within_validation_error!(min, max, options)
         message = options.dig(:numeric, :not_within_message) ||
                   options.dig(:numeric, :not_in_message) ||
@@ -61,6 +169,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for minimum value violations.
+      #
+      # @param min [Numeric] Minimum required value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_min_validation_error!(min, options)
         message = options.dig(:numeric, :min_message) ||
                   options.dig(:numeric, :message)
@@ -73,6 +186,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for maximum value violations.
+      #
+      # @param max [Numeric] Maximum allowed value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_max_validation_error!(max, options)
         message = options.dig(:numeric, :max_message) ||
                   options.dig(:numeric, :message)
@@ -85,6 +203,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for exact value violations.
+      #
+      # @param is [Numeric] Required exact value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_is_validation_error!(is, options)
         message = options.dig(:numeric, :is_message) ||
                   options.dig(:numeric, :message)
@@ -97,6 +220,11 @@ module CMDx
         )
       end
 
+      # Raises validation error for forbidden exact value violations.
+      #
+      # @param is_not [Numeric] Forbidden exact value
+      # @param options [Hash] Validation options containing error messages
+      # @raise [ValidationError] With formatted error message
       def raise_is_not_validation_error!(is_not, options)
         message = options.dig(:numeric, :is_not_message) ||
                   options.dig(:numeric, :message)