hash_validator 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4074014e1480acf0709f7a6c5c4f444e7a9b740bdb58eb04345fc930e1528f90
-  data.tar.gz: 196e0be47b751403869cf47a48f946e63bfd949d88fda63f4f04e57327b1541e
+  metadata.gz: 01246137fa6612aec48d3ebabfb97fa856482f73d0827c520765ad636690cc85
+  data.tar.gz: 4e20f8ad39a7a5f1b4f978d5f832ae30a6896687dc3373d7885c41e637efbad4
 SHA512:
-  metadata.gz: 6f121a0d98d4c6e9c825290951cec72985e169a5fd9ef8e69fda5216554a1ae17405a397a0c82041677ae96881c24104fcdf04dc76f9ccf91647207766e739ea
-  data.tar.gz: 67b9c1941c04c075c247496d9b69c509c272eaa2f5b633af74fb94e1c9b135149cf76cd8f6a344ad41424804ff224662f353fd65070cc157517a19d4f70ca049
+  metadata.gz: a6503553a0ec7c997006ac24dc183ddfbda551c2a94daaefff08d40733fbf474f2e99d181feccde06faa2312b9bb0d6d7c5eaac810a5d776dd928b8f21946253
+  data.tar.gz: 7710ce2712a4e67f0e164bd8ca648c4233ecab28e73542fe93b9dbc52cda2a77c1ebb5eee2e22608ca52a398cba0c9c21c99ec744dc155c512a08f751d404d31

data/.github/workflows/ruby.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["2.3", "2.4", "2.5", "2.6", "2.7", "3.0", "3.1", "3.2", "3.3"]
+        ruby: ["3.0", "3.1", "3.2", "3.3", "3.4"]
     steps:
       - run: sudo apt-get install libcurl4-openssl-dev
       - uses: actions/checkout@v4

data/.ruby-version

@@ -1 +1 @@
-2.7.1
+3.0.7

data/README.md

@@ -6,6 +6,10 @@
 
 Ruby library to validate hashes (Hash) against user-defined requirements
 
+## Requirements
+
+* Ruby 3.0+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,78 +24,192 @@ Or install it yourself as:
 
     $ gem install hash_validator
 
-## Example
+## Quick Start
+
+```ruby
+require 'hash_validator'
+
+# Define validation rules
+validations = { name: 'string', age: 'integer', email: 'email' }
+
+# Validate a hash
+validator = HashValidator.validate(
+  { name: 'John', age: 30, email: 'john@example.com' },
+  validations
+)
+
+validator.valid?  # => true
+```
+
+## Examples
+
+### Successful Validation
+```ruby
+validations = { name: 'string', active: 'boolean', tags: 'array' }
+hash = { name: 'Product', active: true, tags: ['new', 'featured'] }
+
+validator = HashValidator.validate(hash, validations)
+validator.valid?  # => true
+validator.errors  # => {}
+```
 
+### Failed Validation
 ```ruby
-# Validations hash
 validations = {
   user: {
-    first_name: String,
-    last_name:  'string',
-    age:        'numeric',
-    likes:      'array'
+    first_name: 'string',
+    age: 'integer',
+    email: 'email'
   }
 }
 
-# Hash to validate
 hash = {
-  foo: 1,
-  bar: 'baz',
   user: {
     first_name: 'James',
-    last_name:  12345
+    age: 'thirty',  # Should be integer
+    # email missing
   }
 }
 
 validator = HashValidator.validate(hash, validations)
+validator.valid?  # => false
+validator.errors  # => { user: { age: "integer required", email: "email required" } }
+```
 
-validator.valid?
-  # => false
-
-validator.errors
-  # {
-      :user => {
-          :last_name => "string required",
-                :age => "numeric required",
-              :likes => "array required"
+### Rails Controller Example
+```ruby
+class UsersController < ApplicationController
+  def create
+    validations = {
+      user: {
+        name: 'string',
+        email: 'email',
+        age: 'integer',
+        website: 'url',
+        preferences: {
+          theme: ['light', 'dark'],
+          notifications: 'boolean'
+        }
       }
     }
+
+    validator = HashValidator.validate(params, validations)
+
+    if validator.valid?
+      user = User.create(params[:user])
+      render json: { user: user }, status: :created
+    else
+      render json: { errors: validator.errors }, status: :unprocessable_entity
+    end
+  end
+end
+
+# Example request that would pass validation:
+# POST /users
+# {
+#   "user": {
+#     "name": "John Doe",
+#     "email": "john@example.com",
+#     "age": 30,
+#     "website": "https://johndoe.com",
+#     "preferences": {
+#       "theme": "dark",
+#       "notifications": true
+#     }
+#   }
+# }
 ```
 
 ## Usage
 
-Define a validation hash which will be used to validate. This has can be nested as deeply as required using the following values to validate specific value types:
+Define a validation hash which will be used to validate. This hash can be nested as deeply as required using the following validators:
+
+| Validator | Validation Configuration | Example Valid Payload |
+|-----------|-------------------------|----------------------|
+| `alpha` | `{ name: 'alpha' }` | `{ name: 'James' }` |
+| `alphanumeric` | `{ username: 'alphanumeric' }` | `{ username: 'user123' }` |
+| `array` | `{ tags: 'array' }` | `{ tags: ['ruby', 'rails'] }` |
+| `boolean` | `{ active: 'boolean' }` | `{ active: true }` |
+| `complex` | `{ number: 'complex' }` | `{ number: Complex(1, 2) }` |
+| `digits` | `{ zip_code: 'digits' }` | `{ zip_code: '12345' }` |
+| `email` | `{ contact: 'email' }` | `{ contact: 'user@example.com' }` |
+| `enumerable` | `{ status: ['active', 'inactive'] }` | `{ status: 'active' }` |
+| `float` | `{ price: 'float' }` | `{ price: 19.99 }` |
+| `hex_color` | `{ color: 'hex_color' }` | `{ color: '#ff0000' }` |
+| `integer` | `{ age: 'integer' }` | `{ age: 25 }` |
+| `ip` | `{ address: 'ip' }` | `{ address: '192.168.1.1' }` |
+| `ipv4` | `{ address: 'ipv4' }` | `{ address: '10.0.0.1' }` |
+| `ipv6` | `{ address: 'ipv6' }` | `{ address: '2001:db8::1' }` |
+| `json` | `{ config: 'json' }` | `{ config: '{"theme": "dark"}' }` |
+| `numeric` | `{ score: 'numeric' }` | `{ score: 95.5 }` |
+| `range` | `{ priority: 1..10 }` | `{ priority: 5 }` |
+| `rational` | `{ ratio: 'rational' }` | `{ ratio: Rational(3, 4) }` |
+| `regexp` | `{ code: /^[A-Z]{3}$/ }` | `{ code: 'ABC' }` |
+| `required` | `{ id: 'required' }` | `{ id: 'any_value' }` |
+| `string` | `{ title: 'string' }` | `{ title: 'Hello World' }` |
+| `symbol` | `{ type: 'symbol' }` | `{ type: :user }` |
+| `time` | `{ created_at: 'time' }` | `{ created_at: Time.now }` |
+| `url` | `{ website: 'url' }` | `{ website: 'https://example.com' }` |
+
+For hash validation, use nested validations or `{}` to just require a hash to be present.
+
+## Advanced Features
+
+### Class Validation
+On top of the pre-defined validators, classes can be used directly to validate the presence of a value of a specific class:
+
+```ruby
+validations = { created_at: Time, user_id: Integer }
+hash = { created_at: Time.now, user_id: 123 }
+HashValidator.validate(hash, validations).valid?  # => true
+```
+
+### Enumerable Validation
+Validate that a value is contained within a supplied enumerable:
+
+```ruby
+validations = { status: ['active', 'inactive', 'pending'] }
+hash = { status: 'active' }
+HashValidator.validate(hash, validations).valid?  # => true
+```
+
+### Lambda/Proc Validation
+Use custom logic with lambdas or procs (must accept only one argument):
+
+```ruby
+validations = { age: ->(value) { value.is_a?(Integer) && value >= 18 } }
+hash = { age: 25 }
+HashValidator.validate(hash, validations).valid?  # => true
+```
+
+### Regular Expression Validation
+Validate that a string matches a regex pattern:
+
+```ruby
+validations = { product_code: /^[A-Z]{2}\d{4}$/ }
+hash = { product_code: 'AB1234' }
+HashValidator.validate(hash, validations).valid?  # => true
+```
 
-* `array`
-* `boolean`
-* `complex`
-* `enumerable`
-* `float`
-* `integer`
-* `numeric`
-* `range`
-* `rational`
-* `regexp`
-* `string`
-* `symbol`
-* `time`
-* `required`: just requires any value to be present for the designated key.
-* hashes are validates by nesting validations, or if just the presence of a hash is required `{}` can be used.
+### Multiple Validators
+Apply multiple validators to a single key:
 
-On top of the pre-defined simple types, classes can be used directly (e.g. String) to validate the presence of a value of a desired class.
+```ruby
+HashValidator.validate(
+  { score: 85 },
+  { score: HashValidator.multiple('numeric', 1..100) }
+).valid?  # => true
+```
 
-Additional validations exist to validate beyond simple typing, such as:
+This is particularly useful when combining built-in validators with custom validation logic.
 
-* An Enumerable instance: validates that the value is contained within the supplied enumerable.
-* A lambda/Proc instance: validates that the lambda/proc returns true when the value is supplied (lambdas must accept only one argument).
-* A regexp instance: validates that the regex returns a match when the value is supplied (Regexp#match(value) is not nil).
-* `email`: email address validation (string + email address).
+## Custom Validations
 
-Example use-cases include Ruby APIs (I'm currently using it in a Rails API that I'm building for better error responses to developers).
+Allows custom defined validations (must inherit from `HashValidator::Validator::Base`).
 
-## Custom validations
+### Simple Example (using `valid?`)
 
-Allows custom defined validations (must inherit from `HashValidator::Validator::Base`). Example:
+For simple boolean validations, implement the `valid?` method:
 
 ```ruby
 # Define our custom validator
@@ -100,34 +218,175 @@ class HashValidator::Validator::OddValidator < HashValidator::Validator::Base
     super('odd')  # The name of the validator
   end
 
-  def validate(key, value, validations, errors)
-    unless value.is_a?(Integer) && value.odd?
-      errors[key] = presence_error_message
-    end
+  def error_message
+    'must be an odd number'
+  end
+
+  def valid?(value)
+    value.is_a?(Integer) && value.odd?
   end
 end
 
 # Add the validator
-HashValidator.append_validator(HashValidator::Validator::OddValidator.new)
+HashValidator.add_validator(HashValidator::Validator::OddValidator.new)
 
-# Now the validator can be used! e.g.
+# Now the validator can be used!
 validator = HashValidator.validate({ age: 27 }, { age: 'odd' })
 validator.valid?  # => true
 validator.errors  # => {}
+
+validator = HashValidator.validate({ age: 26 }, { age: 'odd' })
+validator.valid?  # => false
+validator.errors  # => { age: 'must be an odd number' }
 ```
 
-## Multiple validators
+### Complex Example (using `validate`)
 
-Multiple validators can be applied to a single key, e.g.
+For more complex validations that need access to the validation parameters or custom error handling, override the `validate` method:
 
 ```ruby
-HashValidator.validate(
-  { foo: 73 },
-  { foo: HashValidator.multiple('numeric', 1..100) }
+# Define a validator that checks if a number is within a range
+class HashValidator::Validator::RangeValidator < HashValidator::Validator::Base
+  def initialize
+    super('_range')  # Underscore prefix as it's invoked through the validation parameter
+  end
+
+  def should_validate?(validation)
+    validation.is_a?(Range)
+  end
+
+  def error_message
+    'is out of range'
+  end
+
+  def validate(key, value, range, errors)
+    unless range.include?(value)
+      errors[key] = "must be between #{range.min} and #{range.max}"
+    end
+  end
+end
+
+# Add the validator
+HashValidator.add_validator(HashValidator::Validator::RangeValidator.new)
+
+# Now the validator can be used with Range objects!
+validator = HashValidator.validate({ age: 25 }, { age: 18..65 })
+validator.valid?  # => true
+validator.errors  # => {}
+
+validator = HashValidator.validate({ age: 10 }, { age: 18..65 })
+validator.valid?  # => false
+validator.errors  # => { age: 'must be between 18 and 65' }
+```
+
+## Simple Custom Validators
+
+For simpler use cases, you can define custom validators without creating a full class using pattern matching or custom functions.
+
+### Configuration DSL
+
+Use the configuration DSL to define multiple validators at once, similar to a Rails initializer:
+
+```ruby
+# In a Rails app, this would go in config/initializers/hash_validator.rb
+HashValidator.configure do |config|
+  # Add instance-based validators
+  config.add_validator HashValidator::Validator::CustomValidator.new
+
+  # Add pattern-based validators
+  config.add_validator 'phone',
+    pattern: /\A\+?[1-9]\d{1,14}\z/,
+    error_message: 'must be a valid international phone number'
+
+  config.add_validator 'postal_code',
+    pattern: /\A[A-Z0-9]{3,10}\z/i,
+    error_message: 'must be a valid postal code'
+
+  # Add function-based validators
+  config.add_validator 'adult',
+    func: ->(age) { age.is_a?(Integer) && age >= 18 },
+    error_message: 'must be 18 or older'
+
+  config.add_validator 'business_hours',
+    func: ->(hour) { hour.between?(9, 17) },
+    error_message: 'must be between 9 AM and 5 PM'
+end
+```
+
+### Pattern-Based Validators
+
+Use regular expressions to validate string formats:
+
+```ruby
+# Add a validator for odd numbers using a pattern
+HashValidator.add_validator('odd_string',
+  pattern: /\A\d*[13579]\z/,
+  error_message: 'must be an odd number string')
+
+# Add a validator for US phone numbers
+HashValidator.add_validator('us_phone',
+  pattern: /\A\d{3}-\d{3}-\d{4}\z/,
+  error_message: 'must be a valid US phone number (XXX-XXX-XXXX)')
+
+# Use the validators
+validator = HashValidator.validate(
+  { number: '27', phone: '555-123-4567' },
+  { number: 'odd_string', phone: 'us_phone' }
+)
+validator.valid?  # => true
+
+validator = HashValidator.validate(
+  { number: '26', phone: '5551234567' },
+  { number: 'odd_string', phone: 'us_phone' }
+)
+validator.valid?  # => false
+validator.errors  # => { number: 'must be an odd number string', phone: 'must be a valid US phone number (XXX-XXX-XXXX)' }
+```
+
+### Function-Based Validators
+
+Use lambdas or procs for custom validation logic:
+
+```ruby
+# Add a validator for adult age using a lambda
+HashValidator.add_validator('adult_age',
+  func: ->(age) { age.is_a?(Integer) && age >= 18 },
+  error_message: 'must be 18 or older')
+
+# Add a validator for palindromes using a proc
+HashValidator.add_validator('palindrome',
+  func: proc { |str| str.to_s == str.to_s.reverse },
+  error_message: 'must be a palindrome')
+
+# Use the validators
+validator = HashValidator.validate(
+  { age: 25, word: 'racecar' },
+  { age: 'adult_age', word: 'palindrome' }
+)
+validator.valid?  # => true
+
+validator = HashValidator.validate(
+  { age: 16, word: 'hello' },
+  { age: 'adult_age', word: 'palindrome' }
 )
+validator.valid?  # => false
+validator.errors  # => { age: 'must be 18 or older', word: 'must be a palindrome' }
+```
+
+### Removing Custom Validators
+
+You can remove custom validators when they're no longer needed:
+
+```ruby
+# Remove a specific validator
+HashValidator.remove_validator('adult_age')
 ```
 
-This is particularly useful when defining custom validators.
+These simple validators are ideal for:
+- Quick format validation without regex in your main code
+- Reusable validation logic across your application
+- Keeping validation definitions close to your configuration
+- Avoiding the overhead of creating full validator classes for simple rules
 
 ## Contributing
 

data/hash_validator.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/JamesBrooks/hash_validator"
   spec.license       = "MIT"
 
-  spec.required_ruby_version = ">= 2.0.0"
+  spec.required_ruby_version = ">= 3.0.0"
   spec.files                 = `git ls-files`.split($/)
   spec.executables           = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files            = spec.files.grep(%r{^(test|spec|features)/})

data/lib/hash_validator/configuration.rb

@@ -0,0 +1,16 @@
+module HashValidator
+  class Configuration
+    def add_validator(*args)
+      HashValidator.add_validator(*args)
+    end
+    
+    def remove_validator(name)
+      HashValidator.remove_validator(name)
+    end
+  end
+  
+  def self.configure
+    config = Configuration.new
+    yield(config) if block_given?
+  end
+end

data/lib/hash_validator/validators/alpha_validator.rb

@@ -0,0 +1,15 @@
+class HashValidator::Validator::AlphaValidator < HashValidator::Validator::Base
+  def initialize
+    super('alpha')  # The name of the validator
+  end
+
+  def error_message
+    'must contain only letters'
+  end
+
+  def valid?(value)
+    value.is_a?(String) && /\A[a-zA-Z]+\z/.match?(value)
+  end
+end
+
+HashValidator.add_validator(HashValidator::Validator::AlphaValidator.new)

data/lib/hash_validator/validators/alphanumeric_validator.rb

@@ -0,0 +1,15 @@
+class HashValidator::Validator::AlphanumericValidator < HashValidator::Validator::Base
+  def initialize
+    super('alphanumeric')  # The name of the validator
+  end
+
+  def error_message
+    'must contain only letters and numbers'
+  end
+
+  def valid?(value)
+    value.is_a?(String) && /\A[a-zA-Z0-9]+\z/.match?(value)
+  end
+end
+
+HashValidator.add_validator(HashValidator::Validator::AlphanumericValidator.new)

data/lib/hash_validator/validators/array_validator.rb

@@ -77,4 +77,4 @@ class HashValidator::Validator::ArrayValidator < HashValidator::Validator::Base
   end
 end
 
-HashValidator.append_validator(HashValidator::Validator::ArrayValidator.new)
+HashValidator.add_validator(HashValidator::Validator::ArrayValidator.new)

data/lib/hash_validator/validators/base.rb

@@ -14,11 +14,36 @@ class HashValidator::Validator::Base
     self.name == name.to_s
   end
 
-  def presence_error_message
+  def error_message
     "#{self.name} required"
   end
 
-  def validate(*)
-    raise StandardError.new('validate should not be called directly on BaseValidator')
+  def validate(key, value, validations, errors)
+    # If the subclass implements valid?, use that for simple boolean validation
+    if self.class.instance_methods(false).include?(:valid?)
+      # Check the arity of the valid? method to determine how many arguments to pass
+      valid_result = case method(:valid?).arity
+      when 1
+        valid?(value)
+      when 2
+        valid?(value, validations)
+      else
+        raise StandardError.new("valid? method must accept either 1 argument (value) or 2 arguments (value, validations)")
+      end
+      
+      unless valid_result
+        errors[key] = error_message
+      end
+    else
+      # Otherwise, subclass must override validate
+      raise StandardError.new('Validator must implement either valid? or override validate method')
+    end
   end
+  
+  # Subclasses can optionally implement this for simple boolean validation
+  # Return true if valid, false if invalid
+  # Either:
+  #   def valid?(value)           # For simple validations
+  #   def valid?(value, validations)  # When validation context is needed
+  # end
 end

data/lib/hash_validator/validators/boolean_validator.rb

@@ -3,11 +3,9 @@ class HashValidator::Validator::BooleanValidator < HashValidator::Validator::Bas
     super('boolean')  # The name of the validator
   end
 
-  def validate(key, value, _validations, errors)
-    unless [TrueClass, FalseClass].include?(value.class)
-      errors[key] = presence_error_message
-    end
+  def valid?(value)
+    [TrueClass, FalseClass].include?(value.class)
   end
 end
 
-HashValidator.append_validator(HashValidator::Validator::BooleanValidator.new)
+HashValidator.add_validator(HashValidator::Validator::BooleanValidator.new)

data/lib/hash_validator/validators/class_validator.rb

@@ -14,4 +14,4 @@ class HashValidator::Validator::ClassValidator < HashValidator::Validator::Base
   end
 end
 
-HashValidator.append_validator(HashValidator::Validator::ClassValidator.new)
+HashValidator.add_validator(HashValidator::Validator::ClassValidator.new)

data/lib/hash_validator/validators/digits_validator.rb

@@ -0,0 +1,15 @@
+class HashValidator::Validator::DigitsValidator < HashValidator::Validator::Base
+  def initialize
+    super('digits')  # The name of the validator
+  end
+
+  def error_message
+    'must contain only digits'
+  end
+
+  def valid?(value)
+    value.is_a?(String) && /\A\d+\z/.match?(value)
+  end
+end
+
+HashValidator.add_validator(HashValidator::Validator::DigitsValidator.new)

data/lib/hash_validator/validators/dynamic_func_validator.rb

@@ -0,0 +1,26 @@
+class HashValidator::Validator::DynamicFuncValidator < HashValidator::Validator::Base
+  attr_accessor :func, :custom_error_message
+
+  def initialize(name, func, error_message = nil)
+    super(name)
+    
+    unless func.respond_to?(:call)
+      raise ArgumentError, "Function must be callable (proc or lambda)"
+    end
+    
+    @func = func
+    @custom_error_message = error_message
+  end
+
+  def error_message
+    @custom_error_message || super
+  end
+
+  def valid?(value)
+    begin
+      !!@func.call(value)
+    rescue => e
+      false
+    end
+  end
+end

data/lib/hash_validator/validators/dynamic_pattern_validator.rb

@@ -0,0 +1,23 @@
+class HashValidator::Validator::DynamicPatternValidator < HashValidator::Validator::Base
+  attr_accessor :pattern, :custom_error_message
+
+  def initialize(name, pattern, error_message = nil)
+    super(name)
+    
+    unless pattern.is_a?(Regexp)
+      raise ArgumentError, "Pattern must be a regular expression"
+    end
+    
+    @pattern = pattern
+    @custom_error_message = error_message
+  end
+
+  def error_message
+    @custom_error_message || super
+  end
+
+  def valid?(value)
+    return false unless value.respond_to?(:to_s)
+    @pattern.match?(value.to_s)
+  end
+end

data/lib/hash_validator/validators/email_validator.rb

@@ -3,15 +3,13 @@ class HashValidator::Validator::EmailValidator < HashValidator::Validator::Base
     super('email')  # The name of the validator
   end
 
-  def presence_error_message
+  def error_message
     'is not a valid email'
   end
 
-  def validate(key, value, _validations, errors)
-    unless value.is_a?(String) && value.include?("@")
-      errors[key] = presence_error_message
-    end
+  def valid?(value)
+    value.is_a?(String) && value.include?("@")
   end
 end
 
-HashValidator.append_validator(HashValidator::Validator::EmailValidator.new)
+HashValidator.add_validator(HashValidator::Validator::EmailValidator.new)