interactor-validation 0.3.7 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6d255c1cdb4048fbd485a9bc8b95096d521e592e6babe4ea7961ec429312386
-  data.tar.gz: a9bc28cb3c10f5f2415da43c3a63b8c774436e13d27e2e6facaaa0cbcbeb19b9
+  metadata.gz: f9c7888fc968eb40b00dbb2225455cd34f60444dfa710eb2d2e3ca991178a572
+  data.tar.gz: 2ff3d6b998b0bc1ec4112c888c7169842335f4829fd215b40e08b98e7e6a38a6
 SHA512:
-  metadata.gz: f5e73c0e35a659668dd31783d5fbea0869f54efe3db2d1033320c66d90fe9fb7997a2fc7079b602608ac6aa1bec60467588ba4b6fdea6bdd3b890cd24ea55bf5
-  data.tar.gz: 7da53549b4bd1ef65065b9480dca243f1a78922045f096281025f7e35a034c8418ce88c90cac698fd6dd8816a9c434e23050b88a42701d96803e2bcf73d8f78a
+  metadata.gz: 622c1af2f52477ccef49d4fea329a2d27d34b4a9cf30387a5c213ad58c7ae0ee8f645a942cde0dc12e2605128c607a204a1d44d7c54004c4205f27a6a3745107
+  data.tar.gz: 57adf88f0a34b152a3af76afdcce71b183dc0e5ef4d79b4bf2ccde88c4dc5cbc15173a2c1e5a257674487b0367ce29261cd721e483a333ac255ca31e5604db59

data/README.md

@@ -213,19 +213,49 @@ validates :terms_accepted, boolean: true
 
 ### Nested Validation
 
-Validate nested hashes and arrays.
+Validate nested hashes and arrays with support for both optional and required parameters.
 
-**Hash Validation:**
+**Optional Nested Validation (parameter can be nil):**
+
+```ruby
+params :filters
+validates :filters do
+  attribute :type, presence: true
+  attribute :value
+end
+
+# When filters is nil or missing - succeeds
+result = SearchItems.call(filters: nil)
+result.success? # => true
+
+# When filters is present - validates nested attributes
+result = SearchItems.call(filters: { type: "category" })
+result.success? # => true
+
+# When filters is present but invalid - fails
+result = SearchItems.call(filters: { value: "test" })
+result.errors # => [{ attribute: "filters.type", type: :blank, message: "Filters.type can't be blank" }]
+```
+
+**Required Nested Validation (parameter must be present):**
 
 ```ruby
 params :user
-validates :user do
+validates :user, presence: true do
   attribute :name, presence: true
   attribute :email, format: { with: /@/ }
   attribute :age, numericality: { greater_than: 0 }
 end
 
-# Usage
+# When user is nil - fails with presence error
+result = CreateUser.call(user: nil)
+result.errors # => [{ attribute: :user, type: :blank, message: "User can't be blank" }]
+
+# When user is empty hash - fails with presence error (empty hashes are not .present?)
+result = CreateUser.call(user: {})
+result.errors # => [{ attribute: :user, type: :blank, message: "User can't be blank" }]
+
+# When user is present - validates nested attributes
 result = CreateUser.call(user: { name: "", email: "bad", age: -1 })
 result.errors # => [
               #      { attribute: "user.name", type: :blank, message: "User.name can't be blank" },
@@ -252,6 +282,18 @@ result.errors # => [
               #      { attribute: "items[1].name", type: :blank, message: "Items[1].name can't be blank" },
               #      { attribute: "items[1].price", type: :greater_than, message: "Items[1].price must be greater than 0" }
               #    ]
+
+# Optional array (can be nil)
+result = ProcessItems.call(items: nil)
+result.success? # => true
+
+# Required array (must be present)
+validates :items, presence: true do
+  attribute :name, presence: true
+end
+
+result = ProcessItems.call(items: nil)
+result.errors # => [{ attribute: :items, type: :blank, message: "Items can't be blank" }]
 ```
 
 ---
@@ -323,6 +365,9 @@ Interactor::Validation.configure do |config|
   # Stop at first error for better performance
   config.halt = false  # Set to true to stop on first validation error
 
+  # Skip custom validate! hook when parameter validation fails
+  config.skip_validate = true  # Set to false to always run validate! hook
+
   # Security settings
   config.regex_timeout = 0.1        # Regex timeout in seconds (ReDoS protection)
   config.max_array_size = 1000      # Max array size for nested validation
@@ -434,6 +479,75 @@ end
 - Improve API response times by failing fast
 - Provide cleaner error messages (only the most relevant error)
 
+### Skip Custom Validations on Parameter Errors
+
+Control whether custom `validate!` hooks run when parameter validation fails:
+
+```ruby
+# Default behavior (skip_validate = true)
+class CreateUser
+  include Interactor
+  include Interactor::Validation
+
+  configure_validation do |config|
+    config.skip_validate = true  # Default
+  end
+
+  params :username, :email
+
+  validates :username, presence: true
+  validates :email, presence: true
+
+  def validate!
+    # This will NOT run if username or email validation fails
+    # Improves performance by skipping expensive checks
+    user_exists = User.exists?(username: username)
+    errors.add(:username, "already taken") if user_exists
+  end
+
+  def call
+    User.create!(username: username, email: email)
+  end
+end
+
+# With skip_validate = false, always run validate!
+class CreateUserAlwaysValidate
+  include Interactor
+  include Interactor::Validation
+
+  configure_validation do |config|
+    config.skip_validate = false  # Run validate! even with param errors
+  end
+
+  params :username, :email
+
+  validates :username, presence: true
+  validates :email, presence: true
+
+  def validate!
+    # This WILL run even if username or email is missing
+    # Useful when you need to collect all possible errors
+    user_exists = User.exists?(username: username) if username.present?
+    errors.add(:username, "already taken") if user_exists
+  end
+
+  def call
+    User.create!(username: username, email: email)
+  end
+end
+```
+
+**When to use skip_validate = true (default):**
+- Skip expensive database lookups when basic params are invalid
+- Avoid unnecessary API calls when required fields are missing
+- Improve performance in high-traffic endpoints
+- Fail fast with only parameter validation errors
+
+**When to use skip_validate = false:**
+- Collect all possible validation errors in a single request
+- Always run business logic validations regardless of param state
+- Provide comprehensive error feedback to users
+
 ### ActiveModel Integration
 
 Use ActiveModel's custom validation callbacks:
@@ -1059,14 +1173,45 @@ end
 ### Nested Validation Examples
 
 ```ruby
-# Hash validation
+# Optional hash validation (parameter can be nil)
+class SearchWithFilters
+  include Interactor
+  include Interactor::Validation
+
+  params :filters
+
+  validates :filters do
+    attribute :category, presence: true
+    attribute :min_price, numericality: { greater_than_or_equal_to: 0 }
+    attribute :max_price, numericality: { greater_than_or_equal_to: 0 }
+  end
+
+  def call
+    # filters is optional - if nil, skip filtering
+    results = filters ? apply_filters(Product.all) : Product.all
+    context.results = results
+  end
+end
+
+# When filters is nil - succeeds
+result = SearchWithFilters.call(filters: nil)
+result.success? # => true
+
+# When filters is present but invalid - fails
+result = SearchWithFilters.call(filters: { min_price: -10 })
+result.errors # => [
+              #      { attribute: "filters.category", type: :blank, message: "Filters.category can't be blank" },
+              #      { attribute: "filters.min_price", type: :greater_than_or_equal_to, message: "..." }
+              #    ]
+
+# Required hash validation (parameter must be present)
 class CreateUserWithProfile
   include Interactor
   include Interactor::Validation
 
   params :user
 
-  validates :user do
+  validates :user, presence: true do
     attribute :name, presence: true
     attribute :email, format: { with: /@/ }
     attribute :age, numericality: { greater_than: 0 }
@@ -1078,7 +1223,14 @@ class CreateUserWithProfile
   end
 end
 
-# Usage
+# When user is nil or empty - fails with presence error
+result = CreateUserWithProfile.call(user: nil)
+result.errors # => [{ attribute: :user, type: :blank, message: "User can't be blank" }]
+
+result = CreateUserWithProfile.call(user: {})
+result.errors # => [{ attribute: :user, type: :blank, message: "User can't be blank" }]
+
+# When user is present but invalid - validates nested attributes
 result = CreateUserWithProfile.call(
   user: {
     name: "",
@@ -1094,7 +1246,7 @@ result.errors # => [
               #      { attribute: "user.bio", type: :too_long, message: "User.bio is too long (maximum is 500 characters)" }
               #    ]
 
-# Array validation
+# Array validation (optional)
 class BulkCreateItems
   include Interactor
   include Interactor::Validation
@@ -1108,11 +1260,16 @@ class BulkCreateItems
   end
 
   def call
+    return if items.nil?  # Optional - handle nil gracefully
     items.each { |item| Item.create!(item) }
   end
 end
 
-# Usage
+# When items is nil - succeeds
+result = BulkCreateItems.call(items: nil)
+result.success? # => true
+
+# When items is present - validates each item
 result = BulkCreateItems.call(
   items: [
     { name: "Widget", price: 10, quantity: 5 },
@@ -1124,6 +1281,30 @@ result.errors # => [
               #      { attribute: "items[1].price", type: :greater_than, message: "Items[1].price must be greater than 0" },
               #      { attribute: "items[1].quantity", type: :greater_than_or_equal_to, message: "Items[1].quantity must be greater than or equal to 1" }
               #    ]
+
+# Required array validation
+class BulkCreateRequiredItems
+  include Interactor
+  include Interactor::Validation
+
+  params :items
+
+  validates :items, presence: true do
+    attribute :name, presence: true
+    attribute :price, numericality: { greater_than: 0 }
+  end
+
+  def call
+    items.each { |item| Item.create!(item) }
+  end
+end
+
+# When items is nil or empty - fails with presence error
+result = BulkCreateRequiredItems.call(items: nil)
+result.errors # => [{ attribute: :items, type: :blank, message: "Items can't be blank" }]
+
+result = BulkCreateRequiredItems.call(items: [])
+result.errors # => [{ attribute: :items, type: :blank, message: "Items can't be blank" }]
 ```
 
 ### ActiveModel Integration

data/lib/interactor/validation/configuration.rb

@@ -5,7 +5,8 @@ module Interactor
     # Configuration class for interactor validation behavior
     class Configuration
       attr_accessor :halt, :regex_timeout, :max_array_size,
-                    :enable_instrumentation, :cache_regex_patterns
+                    :enable_instrumentation, :cache_regex_patterns,
+                    :skip_validate
       attr_reader :error_mode
 
       # Backward compatibility alias for halt_on_first_error
@@ -22,6 +23,7 @@ module Interactor
         @max_array_size = 1000 # Maximum array size for nested validation (memory protection)
         @enable_instrumentation = false # ActiveSupport::Notifications instrumentation
         @cache_regex_patterns = true # Cache compiled regex patterns for performance
+        @skip_validate = true # Skip validate! hook if validate_params! has errors
       end
 
       def error_mode=(mode)

data/lib/interactor/validation/validates.rb

@@ -46,8 +46,9 @@ module Interactor
               nested_rules = build_nested_rules(&)
               current_validations = _param_validations.dup
               existing_rules = current_validations[param_name] || {}
+              # Merge both the validation rules (like presence: true) AND the nested rules
               self._param_validations = current_validations.merge(
-                param_name => existing_rules.merge(_nested: nested_rules)
+                param_name => existing_rules.merge(rules).merge(_nested: nested_rules)
               )
               return
             end
@@ -145,8 +146,11 @@ module Interactor
             { attribute: error.attribute, type: :invalid, options: {} }
           end
 
-          # Skip custom validations if halt was requested
-          unless @halt_validation
+          # Skip custom validations if configured to skip when param errors exist
+          skip_custom_validation = current_config.skip_validate && existing_error_details.any?
+
+          # Skip custom validations if halt was requested or if configured to skip on param errors
+          unless @halt_validation || skip_custom_validation
             # Call super to allow class's validate! to run and add custom errors
             # Rescue exceptions that might be raised
             begin
@@ -244,7 +248,14 @@ module Interactor
       # Get the current configuration (instance config overrides global config)
       # @return [Configuration] the active configuration
       def current_config
-        @current_config || self.class.validation_config || Interactor::Validation.configuration
+        return @current_config if @current_config
+
+        # Try to get class-level config if available
+        if self.class.respond_to?(:validation_config)
+          self.class.validation_config || Interactor::Validation.configuration
+        else
+          Interactor::Validation.configuration
+        end
       end
 
       # Instrument a block of code if instrumentation is enabled
@@ -260,14 +271,23 @@ module Interactor
       end
 
       # Validates a single parameter with the given rules
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def validate_param(param_name, value, rules)
         # Skip validation if explicitly marked
         return if rules[:_skip]
 
         # Handle nested validation (hash or array)
         if rules[:_nested]
-          validate_nested(param_name, value, rules[:_nested])
+          # Run presence validation first if it exists
+          # This allows optional vs required nested validation
+          validate_presence(param_name, value, rules)
+          return if @halt_validation || (@current_config.halt && errors.any?)
+
+          # Only run nested validation if value is present (not nil and not empty)
+          # If parent has no presence requirement, treat empty hash/array as "not provided"
+          # If parent has presence: true, empty hash/array already failed presence check above
+          should_validate_nested = value.present? || value == false
+          validate_nested(param_name, value, rules[:_nested]) if should_validate_nested
           return
         end
 
@@ -289,10 +309,13 @@ module Interactor
 
         validate_numericality(param_name, value, rules)
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       # Validates nested attributes in a hash or array
       def validate_nested(param_name, value, nested_rules)
+        # Return early if value is nil - presence validation handles this if required
+        return if value.nil?
+
         if value.is_a?(Array)
           validate_array_of_hashes(param_name, value, nested_rules)
         elsif value.is_a?(Hash)
@@ -501,7 +524,7 @@ module Interactor
           errors.add(attribute_path, error_type, halt: halt, **interpolations)
         end
 
-        # Note: halt flag is set by ErrorsWrapper.add() if halt: true
+        # NOTE: halt flag is set by ErrorsWrapper.add() if halt: true
       end
       # rubocop:enable Metrics/ParameterLists
 
@@ -708,7 +731,7 @@ module Interactor
           errors.add(param_name, error_type, halt: halt, **interpolations)
         end
 
-        # Note: halt flag is set by ErrorsWrapper.add() if halt: true
+        # NOTE: halt flag is set by ErrorsWrapper.add() if halt: true
       end
 
       # Generate error code for :code mode using constants

data/lib/interactor/validation/version.rb

@@ -2,6 +2,6 @@
 
 module Interactor
   module Validation
-    VERSION = "0.3.7"
+    VERSION = "0.3.9"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interactor-validation
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.3.9
 platform: ruby
 authors:
 - Wilson Anciro