interactor-validation 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc137c0e8cdc24b828f1e2e1369f4527908b48d328df61e994e64ad736dbf59e
-  data.tar.gz: b5c1bddd3dd946662b1394bbd5126aa8361798b59743f9f0da661bcf37166f37
+  metadata.gz: b8c04f34a47f6d887079d08a07958d91c19932a1b3c190faaa0ba4f1a85dbbf2
+  data.tar.gz: 167cbca80c87fe0519f3bab2a1e36c4d753366126e5587d3559907473d558812
 SHA512:
-  metadata.gz: be6bb4b7fe4580208395dd82989f00de651b08bb90a5de35197307d2c9e4f2caff0b41b508a2b3ed973919fdf7bc03aa0c8a953cba9ea86dacc17ea5885cbb4e
-  data.tar.gz: 14128318e687a03b13dc1bd0c3144f2db560ec2f2ed039289ee3c87d4726f5784720a72184d7693cbf55180b43782e405a7282f52e1b4a8f4311048991993bcf
+  metadata.gz: 03a955748e4429b6e141a17292484ec49bf52c5a8af056c7436270f91a9a536c1e782a6ca7d3af38b4437736dd960491735eb233c4abe3599d96a604d9297966
+  data.tar.gz: 0ba87d4e8591ff0ba7cb260d10bda55c8d0526bb8de75cc66a7c81b0addf2d5355d4f9da9919e3ad76fe3052e43868d7af39eb5d57729319ed92500ad12c5e61

data/README.md

@@ -1,6 +1,6 @@
 # Interactor::Validation
 
-Add Rails-style parameter validation to your [Interactor](https://github.com/collectiveidea/interactor) service objects with simple, declarative syntax.
+Add declarative parameter validation to your [Interactor](https://github.com/collectiveidea/interactor) service objects with Rails-style syntax.
 
 ## Installation
 
@@ -27,136 +27,165 @@ class CreateUser
   end
 end
 
-# Success
-result = CreateUser.call(email: "dev@example.com", username: "developer", age: 25)
-result.success? # => true
-result.user     # => #<User...>
-
-# Failure - automatic validation
+# Validation runs automatically before call
 result = CreateUser.call(email: "", username: "ab", age: -5)
 result.failure? # => true
 result.errors   # => [
-                #      { code: "EMAIL_IS_REQUIRED" },
-                #      { code: "USERNAME_BELOW_MIN_LENGTH_3" },
-                #      { code: "AGE_MUST_BE_GREATER_THAN_0" }
+                #      { attribute: :email, type: :blank, message: "Email can't be blank" },
+                #      { attribute: :username, type: :too_short, message: "Username is too short (minimum is 3 characters)" },
+                #      { attribute: :age, type: :greater_than, message: "Age must be greater than 0" }
                 #    ]
 ```
 
-## Features
-
-### Parameter Declaration
-
-Use `params` to declare expected parameters - they're automatically delegated to context:
-
-```ruby
-params :user_id, :action
-
-def call
-  # Access directly instead of context.user_id
-  user = User.find(user_id)
-  user.perform(action)
-end
-```
-
-### Validation Rules
+## Validation Types
 
-All validations run **before** your `call` method. If validation fails, the interactor stops and returns structured errors.
+### Presence
 
-**Presence**
 ```ruby
 validates :name, presence: true
-# Error: { code: "NAME_IS_REQUIRED" }
+# Error: { attribute: :name, type: :blank, message: "Name can't be blank" }
 ```
 
-**Format (Regex)**
+### Format (Regex)
+
 ```ruby
 validates :email, format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }
-# Error: { code: "EMAIL_INVALID_FORMAT" }
+# Error: { attribute: :email, type: :invalid, message: "Email is invalid" }
 ```
 
-**Length**
+### Length
+
 ```ruby
 validates :password, length: { minimum: 8, maximum: 128 }
 validates :code, length: { is: 6 }
-# Errors: { code: "PASSWORD_BELOW_MIN_LENGTH_8" }
-#         { code: "CODE_INVALID_LENGTH_6" }
+# Errors: { attribute: :password, type: :too_short, message: "Password is too short (minimum is 8 characters)" }
+#         { attribute: :code, type: :wrong_length, message: "Code is the wrong length (should be 6 characters)" }
 ```
 
-**Inclusion**
+### Inclusion
+
 ```ruby
 validates :status, inclusion: { in: %w[active pending inactive] }
-# Error: { code: "STATUS_NOT_IN_LIST" }
+# Error: { attribute: :status, type: :inclusion, message: "Status is not included in the list" }
 ```
 
-**Numericality**
+### Numericality
+
 ```ruby
 validates :price, numericality: { greater_than_or_equal_to: 0 }
 validates :quantity, numericality: { greater_than: 0, less_than_or_equal_to: 100 }
-# Errors: { code: "PRICE_MUST_BE_GREATER_THAN_OR_EQUAL_TO_0" }
+validates :count, numericality: true  # Just check if numeric
+
+# Available constraints:
+# - greater_than, greater_than_or_equal_to
+# - less_than, less_than_or_equal_to
+# - equal_to
+```
+
+### Boolean
+
+```ruby
+validates :is_active, boolean: true
+# Ensures value is true or false (not truthy/falsy)
+```
+
+### Nested Validation
+
+Validate nested hashes and arrays:
+
+```ruby
+# Hash validation
+params :user
+validates :user do
+  attribute :name, presence: true
+  attribute :email, format: { with: /@/ }
+  attribute :age, numericality: { greater_than: 0 }
+end
+
+# Array validation
+params :items
+validates :items do
+  attribute :name, presence: true
+  attribute :price, numericality: { greater_than: 0 }
+end
 ```
 
-### Error Formats
+## Error Formats
 
-The gem supports two error formatting modes:
+Choose between two error format modes:
 
-#### Code Mode (Default)
+### Default Mode (ActiveModel-style)
 
-Returns structured error codes ideal for APIs and i18n:
+Human-readable errors with full context - ideal for forms and user-facing applications:
 
 ```ruby
+# This is the default, no configuration needed
 result.errors # => [
-              #      { code: "EMAIL_IS_REQUIRED" },
-              #      { code: "USERNAME_BELOW_MIN_LENGTH_3" }
+              #      { attribute: :email, type: :blank, message: "Email can't be blank" },
+              #      { attribute: :username, type: :too_short, message: "Username is too short" }
               #    ]
 ```
 
-#### Default Mode
+### Code Mode
 
-Returns ActiveModel-style errors with human-readable messages:
+Structured error codes - ideal for APIs and internationalization:
 
 ```ruby
-Interactor::Validation.configure do |config|
-  config.error_mode = :default
+configure_validation do |config|
+  config.error_mode = :code
 end
 
 result.errors # => [
-              #      { attribute: :email, type: :blank, message: "Email can't be blank" },
-              #      { attribute: :username, type: :too_short, message: "Username is too short (minimum is 3 characters)" }
+              #      { code: "EMAIL_IS_REQUIRED" },
+              #      { code: "USERNAME_BELOW_MIN_LENGTH_3" }
               #    ]
 ```
 
+### Custom Messages
+
+Provide custom error messages for any validation:
+
+```ruby
+# Works with both modes
+validates :username, presence: { message: "Username is required" }
+validates :email, format: { with: /@/, message: "Invalid email format" }
+
+# In :code mode, custom messages become part of the code
+configure_validation { |c| c.error_mode = :code }
+validates :age, numericality: { greater_than: 0, message: "INVALID_AGE" }
+# => { code: "AGE_INVALID_AGE" }
+```
+
 ## Configuration
 
 ### Global Configuration
 
-Configure validation behavior for all interactors:
+Configure behavior for all interactors:
 
 ```ruby
 # config/initializers/interactor_validation.rb
 Interactor::Validation.configure do |config|
-  # Error format mode: :code (default) or :default
-  config.error_mode = :code
+  # Error format: :default (ActiveModel-style) or :code (structured codes)
+  config.error_mode = :default
 
-  # Stop validation at first error (default: false)
+  # Stop at first error for better performance
   config.halt_on_first_error = false
 
-  # Security: Regex timeout in seconds (default: 0.1)
-  config.regex_timeout = 0.1
-
-  # Security: Maximum array size for nested validation (default: 1000)
-  config.max_array_size = 1000
+  # Security settings
+  config.regex_timeout = 0.1        # Regex timeout in seconds (ReDoS protection)
+  config.max_array_size = 1000      # Max array size for nested validation
 
-  # Performance: Cache compiled regex patterns (default: true)
+  # Performance settings
   config.cache_regex_patterns = true
 
-  # Monitoring: Enable ActiveSupport::Notifications (default: false)
+  # Monitoring
   config.enable_instrumentation = false
 end
 ```
 
 ### Per-Interactor Configuration
 
-Override global settings for specific interactors:
+Override settings for specific interactors:
 
 ```ruby
 class CreateUser
@@ -164,7 +193,7 @@ class CreateUser
   include Interactor::Validation
 
   configure_validation do |config|
-    config.error_mode = :default
+    config.error_mode = :code
     config.halt_on_first_error = true
   end
 
@@ -173,47 +202,37 @@ class CreateUser
 end
 ```
 
-### Custom Error Messages
+## Advanced Features
 
-Provide custom error messages for any validation:
+### Parameter Declaration
 
-```ruby
-# With :code mode
-configure_validation do |config|
-  config.error_mode = :code
-end
+Declare parameters for automatic delegation to context:
 
-validates :username, presence: { message: "CUSTOM_REQUIRED_ERROR" }
-validates :email, format: { with: /@/, message: "CUSTOM_FORMAT_ERROR" }
-# => { code: "USERNAME_CUSTOM_REQUIRED_ERROR" }
-# => { code: "EMAIL_CUSTOM_FORMAT_ERROR" }
+```ruby
+params :user_id, :action
 
-# With :default mode
-configure_validation do |config|
-  config.error_mode = :default
+def call
+  # Access directly instead of context.user_id
+  user = User.find(user_id)
+  user.perform(action)
 end
-
-validates :bio, length: { maximum: 500, message: "is too long (max 500 chars)" }
-# => { attribute: :bio, type: :too_long, message: "is too long (max 500 chars)" }
 ```
 
-### Advanced Usage
-
-#### Halt on First Error
+### Halt on First Error
 
-Improve performance by stopping validation at the first failure:
+Improve performance by stopping validation early:
 
 ```ruby
 configure_validation do |config|
-  config.halt_on_first_error = true  # Stop at first error
+  config.halt_on_first_error = true
 end
 
 validates :field1, presence: true
 validates :field2, presence: true  # Won't run if field1 fails
-validates :field3, presence: true  # Won't run if field1 or field2 fails
+validates :field3, presence: true  # Won't run if earlier fields fail
 ```
 
-#### Integration with ActiveModel Validations
+### ActiveModel Integration
 
 Use ActiveModel's custom validation callbacks:
 
@@ -224,88 +243,90 @@ class CreateUser
 
   params :user_data
 
-  validate :check_user_data_structure
+  validate :check_custom_logic
   validates :username, presence: true
 
-  def check_user_data_structure
-    errors.add(:user_data, "must be a Hash") unless user_data.is_a?(Hash)
+  private
+
+  def check_custom_logic
+    errors.add(:base, "Custom validation failed") unless custom_condition?
   end
 end
 ```
 
-## Security
+### Performance Monitoring
 
-This gem includes built-in protection against common security vulnerabilities:
-
-### ReDoS Protection (v0.2.0+)
-
-Regular Expression Denial of Service attacks are prevented with automatic timeouts:
+Track validation performance in production:
 
 ```ruby
-config.regex_timeout = 0.1 # 100ms default timeout
-```
-
-If a regex takes longer than the configured timeout, validation will fail safely instead of hanging.
-
-### Memory Protection (v0.2.0+)
-
-Array validation includes automatic size limits to prevent memory exhaustion:
+config.enable_instrumentation = true
 
-```ruby
-config.max_array_size = 1000 # Default limit
+ActiveSupport::Notifications.subscribe('validate_params.interactor_validation') do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info "Validation: #{event.duration}ms (#{event.payload[:interactor]})"
+end
 ```
 
-### Thread Safety (v0.2.0+)
+## Security
 
-Validation rule registration is thread-safe and can be used safely in multi-threaded environments (Puma, Sidekiq).
+Built-in protection against common vulnerabilities:
 
-### Best Practices
+### ReDoS Protection
 
-1. **Use simple regex patterns** - Avoid nested quantifiers that can cause backtracking
-2. **Sanitize outputs** - Always escape error messages when rendering in HTML
-3. **Set appropriate limits** - Configure `max_array_size` based on your application needs
-4. **Monitor performance** - Enable instrumentation in production to detect slow validations
+Automatic timeouts prevent Regular Expression Denial of Service attacks:
 
-For detailed security information, see [SECURITY.md](SECURITY.md).
+```ruby
+config.regex_timeout = 0.1  # 100ms default
+```
 
-## Performance
+If a regex exceeds the timeout, validation fails safely instead of hanging.
 
-### Benchmarking
+### Memory Protection
 
-Run the included benchmark suite to measure performance:
+Array size limits prevent memory exhaustion:
 
-```bash
-bundle exec ruby benchmark/validation_benchmark.rb
+```ruby
+config.max_array_size = 1000  # Default limit
 ```
 
-### Monitoring
+### Thread Safety
 
-Enable instrumentation to track validation performance in production:
+All validation operations are thread-safe for use with Puma, Sidekiq, etc.
 
-```ruby
-config.enable_instrumentation = true
+### Best Practices
 
-ActiveSupport::Notifications.subscribe('validate_params.interactor_validation') do |*args|
-  event = ActiveSupport::Notifications::Event.new(*args)
-  Rails.logger.info "Validation took #{event.duration}ms for #{event.payload[:interactor]}"
-end
-```
+- Use simple regex patterns (avoid nested quantifiers)
+- Sanitize error messages before displaying in HTML
+- Set appropriate `max_array_size` limits for your use case
+- Enable instrumentation to monitor performance
+- Review [SECURITY.md](SECURITY.md) for detailed information
 
 ## Development
 
 ```bash
 bin/setup              # Install dependencies
-bundle exec rspec      # Run tests
+bundle exec rspec      # Run tests (231 examples)
 bundle exec rubocop    # Lint code
 bin/console            # Interactive console
 ```
 
+### Benchmarking
+
+```bash
+bundle exec ruby benchmark/validation_benchmark.rb
+```
+
 ## Requirements
 
 - Ruby >= 3.2.0
 - Interactor ~> 3.0
 - ActiveModel >= 6.0
+- ActiveSupport >= 6.0
 
 ## License
 
 MIT License - see [LICENSE.txt](LICENSE.txt)
+
+## Contributing
+
+Issues and pull requests are welcome at [https://github.com/zyxzen/interactor-validation](https://github.com/zyxzen/interactor-validation)

data/lib/interactor/validation/configuration.rb

@@ -9,10 +9,10 @@ module Interactor
       attr_reader :error_mode
 
       # Available error modes:
-      # - :default - Uses ActiveModel-style human-readable messages
-      # - :code - Returns structured error codes (e.g., USERNAME_IS_REQUIRED) [DEFAULT]
+      # - :default - Uses ActiveModel-style human-readable messages [DEFAULT]
+      # - :code - Returns structured error codes (e.g., USERNAME_IS_REQUIRED)
       def initialize
-        @error_mode = :code
+        @error_mode = :default
         @halt_on_first_error = false
         @regex_timeout = 0.1 # 100ms timeout for regex matching (ReDoS protection)
         @max_array_size = 1000 # Maximum array size for nested validation (memory protection)

data/lib/interactor/validation/version.rb

@@ -2,6 +2,6 @@
 
 module Interactor
   module Validation
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

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