cmdx 1.1.2 → 1.5.1

data/lib/cmdx/utils/call.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Utils
+    # Utility module for invoking callable objects with different invocation strategies.
+    #
+    # This module provides a unified interface for calling methods, procs, and other
+    # callable objects on target objects, handling the appropriate invocation method
+    # based on the callable type.
+    module Call
+
+      extend self
+
+      # Invokes a callable object on the target with the given arguments.
+      #
+      # @param target [Object] The target object to invoke the callable on
+      # @param callable [Symbol, Proc, #call] The callable to invoke
+      # @param args [Array] Positional arguments to pass to the callable
+      # @param kwargs [Hash] Keyword arguments to pass to the callable
+      # @param &block [Proc, nil] Block to pass to the callable
+      #
+      # @return [Object] The result of invoking the callable
+      #
+      # @raise [RuntimeError] When the callable cannot be invoked
+      #
+      # @example Invoking a method by symbol
+      #   Call.invoke(user, :name)
+      #   Call.invoke(user, :update, { name: 'John' })
+      # @example Invoking a proc
+      #   proc = ->(name) { "Hello #{name}" }
+      #   Call.invoke(user, proc, 'John')
+      # @example Invoking a callable object
+      #   callable = MyCallable.new
+      #   Call.invoke(user, callable, 'data')
+      def invoke(target, callable, *args, **kwargs, &)
+        if callable.is_a?(Symbol)
+          target.send(callable, *args, **kwargs, &)
+        elsif callable.is_a?(Proc)
+          target.instance_exec(*args, **kwargs, &callable)
+        elsif callable.respond_to?(:call)
+          callable.call(*args, **kwargs, &)
+        else
+          raise "cannot invoke #{callable}"
+        end
+      end
+
+    end
+  end
+end

data/lib/cmdx/utils/condition.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Utils
+    # Provides conditional evaluation utilities for CMDx tasks and workflows.
+    #
+    # This module handles conditional logic evaluation with support for `if` and `unless`
+    # conditions using various callable types including symbols, procs, and objects
+    # responding to `call`.
+    module Condition
+
+      extend self
+
+      EVAL = proc do |target, callable, *args, **kwargs, &block|
+        case callable
+        when NilClass, FalseClass, TrueClass then !!callable
+        when Symbol then target.send(callable, *args, **kwargs, &block)
+        when Proc then target.instance_exec(*args, **kwargs, &callable)
+        else
+          raise "cannot evaluate #{callable.inspect}" unless callable.respond_to?(:call)
+
+          callable.call(*args, **kwargs, &block)
+        end
+      end.freeze
+      private_constant :EVAL
+
+      # Evaluates conditional logic based on provided options.
+      #
+      # Supports both `if` and `unless` conditions, with `unless` taking precedence
+      # when both are specified. Returns true if no conditions are provided.
+      #
+      # @param target [Object] The target object to evaluate conditions against
+      # @param options [Hash] Conditional options hash
+      # @option options [Object] :if Condition that must be true for evaluation to succeed
+      # @option options [Object] :unless Condition that must be false for evaluation to succeed
+      # @param args [Array] Additional arguments passed to condition evaluation
+      # @param kwargs [Hash] Additional keyword arguments passed to condition evaluation
+      # @param block [Proc, nil] Optional block passed to condition evaluation
+      #
+      # @return [Boolean] true if conditions are met, false otherwise
+      #
+      # @raise [RuntimeError] When a callable cannot be evaluated
+      #
+      # @example Basic if condition
+      #   Condition.evaluate(user, if: :active?)
+      #   # => true if user.active? returns true
+      # @example Unless condition
+      #   Condition.evaluate(user, unless: :blocked?)
+      #   # => true if user.blocked? returns false
+      # @example Combined conditions
+      #   Condition.evaluate(user, if: :verified?, unless: :suspended?)
+      #   # => true if user.verified? is true AND user.suspended? is false
+      # @example With arguments and block
+      #   Condition.evaluate(user, if: ->(u) { u.has_permission?(:admin) }, :admin)
+      #   # => true if the proc returns true when called with user and :admin
+      def evaluate(target, options, ...)
+        case options
+        in if: if_cond, unless: unless_cond
+          EVAL.call(target, if_cond, ...) && !EVAL.call(target, unless_cond, ...)
+        in if: if_cond
+          EVAL.call(target, if_cond, ...)
+        in unless: unless_cond
+          !EVAL.call(target, unless_cond, ...)
+        else
+          true
+        end
+      end
+
+    end
+  end
+end

data/lib/cmdx/utils/format.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Utils
+    # Utility module for formatting data structures into log-friendly strings
+    # and converting messages to appropriate formats for logging
+    module Format
+
+      extend self
+
+      FORMATTER = proc do |key, value|
+        "#{key}=#{value.inspect}"
+      end.freeze
+      private_constant :FORMATTER
+
+      # Converts a message to a format suitable for logging
+      #
+      # @param message [Object] The message to format
+      #
+      # @return [Hash, Object] Returns a hash if the message responds to to_h and is a CMDx object, otherwise returns the original message
+      #
+      # @example Hash like objects
+      #   Format.to_log({user_id: 123, action: "login"})
+      #   # => {user_id: 123, action: "login"}
+      # @example Simple message
+      #   Format.to_log("simple message")
+      #   # => "simple message"
+      # @example CMDx object
+      #   Format.to_log(CMDx::Task.new(name: "task1"))
+      #   # => {name: "task1"}
+      def to_log(message)
+        if message.respond_to?(:to_h) && message.class.ancestors.any? { |a| a.to_s.start_with?("CMDx") }
+          message.to_h
+        else
+          message
+        end
+      end
+
+      # Converts a hash to a formatted string using a custom formatter
+      #
+      # @param hash [Hash] The hash to convert to string
+      # @param block [Proc, nil] Optional custom formatter block
+      # @option block [String] :key The hash key
+      # @option block [Object] :value The hash value
+      #
+      # @return [String] Space-separated formatted key-value pairs
+      #
+      # @example Default formatter
+      #   Format.to_str({user_id: 123, status: "active"})
+      #   # => "user_id=123 status=\"active\""
+      # @example Custom formatter
+      #   Format.to_str({count: 5, total: 100}) { |k, v| "#{k}:#{v}" }
+      #   # => "count:5 total:100"
+      def to_str(hash, &block)
+        block ||= FORMATTER
+        hash.map(&block).join(" ")
+      end
+
+    end
+  end
+end

data/lib/cmdx/validator_registry.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Registry for parameter validation handlers in the CMDx framework.
-  #
-  # ValidatorRegistry manages the collection of validator implementations
-  # that can be used for parameter validation in tasks. It provides a
-  # centralized registry where validators can be registered by type and
-  # invoked during parameter processing. The registry comes pre-loaded
-  # with built-in validators for common validation scenarios.
+  # Registry for managing validation rules and their corresponding validator classes.
+  # Provides methods to register, deregister, and execute validators against task values.
   class ValidatorRegistry
 
-    # @return [Hash] internal hash storing validator implementations by type
+    extend Forwardable
+
     attr_reader :registry
+    alias to_h registry
 
-    # Creates a new validator registry with built-in validators.
-    #
-    # The registry is initialized with standard validators including
-    # exclusion, format, inclusion, length, numeric, and presence validation.
-    # These built-in validators provide common validation functionality
-    # that can be immediately used without additional registration.
+    def_delegators :registry, :keys
+
+    # Initialize a new validator registry with default validators.
     #
-    # @return [ValidatorRegistry] a new registry instance with built-in validators
+    # @param registry [Hash, nil] Optional hash mapping validator names to validator classes
     #
-    # @example Create a new validator registry
-    #   registry = ValidatorRegistry.new
-    #   registry.registry.keys #=> [:exclusion, :format, :inclusion, :length, :numeric, :presence]
-    def initialize
-      @registry = {
+    # @return [ValidatorRegistry] A new validator registry instance
+    def initialize(registry = nil)
+      @registry = registry || {
         exclusion: Validators::Exclusion,
         format: Validators::Format,
         inclusion: Validators::Inclusion,
@@ -36,72 +28,71 @@ module CMDx
       }
     end
 
-    # Registers a new validator implementation for the specified type.
-    #
-    # This method allows custom validators to be added to the registry,
-    # enabling extended validation functionality beyond the built-in
-    # validators. The validator can be a class, symbol, string, or proc
-    # that implements the validation logic.
+    # Create a duplicate of the registry with copied internal state.
     #
-    # @param type [Symbol] the validator type identifier
-    # @param validator [Class, Symbol, String, Proc] the validator implementation
-    #
-    # @return [ValidatorRegistry] returns self for method chaining
-    #
-    # @example Register a custom validator class
-    #   registry.register(:email, EmailValidator)
+    # @return [ValidatorRegistry] A new validator registry with duplicated registry hash
+    def dup
+      self.class.new(registry.dup)
+    end
+
+    # Register a new validator class with the given name.
     #
-    # @example Register a symbol validator
-    #   registry.register(:zipcode, :validate_zipcode)
+    # @param name [String, Symbol] The name to register the validator under
+    # @param validator [Class] The validator class to register
     #
-    # @example Register a proc validator
-    #   registry.register(:positive, ->(value, options) { value > 0 })
+    # @return [ValidatorRegistry] Returns self for method chaining
     #
-    # @example Method chaining
-    #   registry.register(:email, EmailValidator)
-    #           .register(:phone, PhoneValidator)
-    def register(type, validator)
-      registry[type] = validator
+    # @example
+    #   registry.register(:custom, CustomValidator)
+    #   registry.register("email", EmailValidator)
+    def register(name, validator)
+      registry[name.to_sym] = validator
       self
     end
 
-    # Executes validation for a parameter value using the specified validator type.
-    #
-    # This method performs validation by looking up the registered validator
-    # for the given type and executing it with the provided value and options.
-    # The validation is only performed if the task's evaluation of the options
-    # returns a truthy value, allowing for conditional validation.
+    # Remove a validator from the registry by name.
     #
-    # @param task [Task] the task instance performing validation
-    # @param type [Symbol] the validator type to use
-    # @param value [Object] the value to validate
-    # @param options [Hash] validation options and configuration
+    # @param name [String, Symbol] The name of the validator to remove
     #
-    # @return [Object, nil] the validation result or nil if validation was skipped
+    # @return [ValidatorRegistry] Returns self for method chaining
     #
-    # @raise [UnknownValidatorError] if the specified validator type is not registered
+    # @example
+    #   registry.deregister(:format)
+    #   registry.deregister("presence")
+    def deregister(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    # Validate a value using the specified validator type and options.
     #
-    # @example Validate with a built-in validator
-    #   registry.call(task, :presence, "", {})
-    #   #=> may raise ValidationError if value is blank
+    # @param type [Symbol] The type of validator to use
+    # @param task [Task] The task context for validation
+    # @param value [Object] The value to validate
+    # @param options [Hash, Object] Validation options or condition
+    # @option options [Boolean] :allow_nil Whether to allow nil values
     #
-    # @example Validate with options
-    #   registry.call(task, :length, "hello", minimum: 3, maximum: 10)
-    #   #=> validates string length is between 3 and 10 characters
+    # @raise [TypeError] When the validator type is not registered
     #
-    # @example Conditional validation that gets skipped
-    #   registry.call(task, :presence, "", if: -> { false })
-    #   #=> returns nil without performing validation
-    def call(task, type, value, options = {})
-      raise UnknownValidatorError, "unknown validator #{type}" unless registry.key?(type)
-      return unless task.cmdx_eval(options)
+    # @example
+    #   registry.validate(:presence, task, user.name, presence: true)
+    #   registry.validate(:length, task, password, { min: 8, allow_nil: false })
+    def validate(type, task, value, options = {})
+      raise TypeError, "unknown validator type #{type.inspect}" unless registry.key?(type)
+
+      match =
+        if options.is_a?(Hash)
+          case options
+          in allow_nil: then allow_nil && value.nil?
+          else Utils::Condition.evaluate(task, options, value)
+          end
+        else
+          options
+        end
+
+      return unless match
 
-      case validator = registry[type]
-      when Symbol, String, Proc
-        task.cmdx_try(validator, value, options)
-      else
-        validator.call(value, options)
-      end
+      Utils::Call.invoke(task, registry[type], value, options)
     end
 
   end

data/lib/cmdx/validators/exclusion.rb

@@ -2,103 +2,74 @@
 
 module CMDx
   module Validators
-    # Validator class for excluding values from a specified set.
+    # Validates that a value is not included in a specified set or range
     #
-    # This validator ensures that a value is not included in a given array or range
-    # of forbidden values. It supports both discrete value exclusion and range-based
-    # exclusion validation.
-    class Exclusion < Validator
+    # This validator ensures that the given value is excluded from a collection
+    # of forbidden values or falls outside a specified range. It supports both
+    # discrete value lists and range-based exclusions.
+    module Exclusion
 
-      # Validates that the given value is not included in the exclusion set.
-      #
-      # @param value [Object] the value to validate
-      # @param options [Hash] validation options containing exclusion configuration
-      # @option options [Hash] :exclusion exclusion validation configuration
-      # @option options [Array, Range] :exclusion.in the values to exclude
-      # @option options [Array, Range] :exclusion.within alias for :in
-      # @option options [String] :exclusion.message custom error message
-      # @option options [String] :exclusion.of_message custom error message for array exclusion
-      # @option options [String] :exclusion.in_message custom error message for range exclusion
-      # @option options [String] :exclusion.within_message alias for :in_message
-      #
-      # @return [void]
-      #
-      # @raise [ValidationError] if the value is found in the exclusion set
-      #
-      # @example Excluding from an array
-      #   Validators::Exclusion.call("admin", exclusion: { in: ["admin", "root"] })
-      #   # raises ValidationError: "must not be one of: \"admin\", \"root\""
+      extend self
+
+      # Validates that a value is excluded from the specified options
       #
-      # @example Excluding from a range
-      #   Validators::Exclusion.call(5, exclusion: { in: 1..10 })
-      #   # raises ValidationError: "must not be within 1 and 10"
+      # @param value [Object] The value to validate for exclusion
+      # @param options [Hash] Validation configuration options
+      # @option options [Array, Range] :in The collection of forbidden values or range
+      # @option options [Array, Range] :within Alias for :in option
+      # @option options [String] :message Custom error message template
+      # @option options [String] :of_message Custom message for discrete value exclusions
+      # @option options [String] :in_message Custom message for range-based exclusions
+      # @option options [String] :within_message Custom message for range-based exclusions
       #
-      # @example Valid exclusion
-      #   Validators::Exclusion.call("user", exclusion: { in: ["admin", "root"] })
-      #   #=> nil (no error raised)
+      # @raise [ValidationError] When the value is found in the forbidden collection
       #
-      # @example Using a custom message
-      #   Validators::Exclusion.call("admin", exclusion: { in: ["admin", "root"], message: "Reserved username not allowed" })
-      #   # raises ValidationError: "Reserved username not allowed"
+      # @example Exclude specific values
+      #   Exclusion.call("admin", in: ["admin", "root", "superuser"])
+      #   # => raises ValidationError if value is "admin"
+      # @example Exclude values within a range
+      #   Exclusion.call(5, in: 1..10)
+      #   # => raises ValidationError if value is 5 (within 1..10)
+      # @example Exclude with custom message
+      #   Exclusion.call("test", in: ["test", "demo"], message: "value %{values} is forbidden")
       def call(value, options = {})
         values = options[:in] || options[:within]
 
         if values.is_a?(Range)
           raise_within_validation_error!(values.begin, values.end, options) if values.cover?(value)
-        elsif Array(values).any? { |v| v === value } # rubocop:disable Style/CaseEquality
+        elsif Array(values).any? { |v| v === value }
           raise_of_validation_error!(values, options)
         end
       end
 
       private
 
-      # Raises a validation error for array-based exclusion.
+      # Raises validation error for discrete value exclusions
       #
-      # @param values [Array] the excluded values
-      # @param options [Hash] validation options
+      # @param values [Array] The forbidden values that caused the error
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @return [void]
-      #
-      # @raise [ValidationError] always raised with appropriate message
-      #
-      # @example
-      #   raise_of_validation_error!(["admin", "root"], {})
-      #   # raises ValidationError: "must not be one of: \"admin\", \"root\""
+      # @raise [ValidationError] With appropriate error message
       def raise_of_validation_error!(values, options)
-        values  = values.map(&:inspect).join(", ") unless values.nil?
+        values = values.map(&:inspect).join(", ") unless values.nil?
         message = options[:of_message] || options[:message]
         message %= { values: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.exclusion.of",
-          values:,
-          default: "must not be one of: #{values}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.exclusion.of", values:)
       end
 
-      # Raises a validation error for range-based exclusion.
-      #
-      # @param min [Object] the minimum value of the range
-      # @param max [Object] the maximum value of the range
-      # @param options [Hash] validation options
-      #
-      # @return [void]
+      # Raises validation error for range-based exclusions
       #
-      # @raise [ValidationError] always raised with appropriate message
+      # @param min [Object] The minimum value of the forbidden range
+      # @param max [Object] The maximum value of the forbidden range
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @example
-      #   raise_within_validation_error!(1, 10, {})
-      #   # raises ValidationError: "must not be within 1 and 10"
+      # @raise [ValidationError] With appropriate error message
       def raise_within_validation_error!(min, max, options)
         message = options[:in_message] || options[:within_message] || options[:message]
         message %= { min:, max: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.exclusion.within",
-          min:,
-          max:,
-          default: "must not be within #{min} and #{max}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.exclusion.within", min:, max:)
       end
 
     end

data/lib/cmdx/validators/format.rb

@@ -2,64 +2,63 @@
 
 module CMDx
   module Validators
-    # Validator class for format validation using regular expressions.
+    # Validates that a value matches a specified format pattern
     #
-    # This validator ensures that a value matches or doesn't match specified
-    # regular expression patterns. It supports both positive matching (with)
-    # and negative matching (without) patterns, which can be used independently
-    # or in combination.
-    class Format < Validator
+    # This validator ensures that the given value conforms to a specific format
+    # using regular expressions. It supports both direct regex matching and
+    # conditional matching with inclusion/exclusion patterns.
+    module Format
 
-      # Validates that the given value matches the specified format pattern(s).
-      #
-      # @param value [Object] the value to validate
-      # @param options [Hash] validation options containing format configuration
-      # @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 the value doesn't match the format requirements
-      #
-      # @example Validating with a positive pattern
-      #   Validators::Format.call("user123", format: { with: /\A[a-z]+\d+\z/ })
-      #   #=> nil (no error raised)
+      extend self
+
+      # Validates that a value matches the specified format pattern
       #
-      # @example Validating with a negative pattern
-      #   Validators::Format.call("admin", format: { without: /admin|root/ })
-      #   # raises ValidationError: "is an invalid format"
+      # @param value [Object] The value to validate for format compliance
+      # @param options [Hash, Regexp] Validation configuration options or direct regex pattern
+      # @option options [Regexp] :with Required pattern that the value must match
+      # @option options [Regexp] :without Pattern that the value must not match
+      # @option options [String] :message Custom error message
       #
-      # @example Validating with both patterns
-      #   Validators::Format.call("user123", format: { with: /\A[a-z]+\d+\z/, without: /admin|root/ })
-      #   #=> nil (no error raised)
+      # @return [nil] Returns nil if validation passes
       #
-      # @example Invalid format with positive pattern
-      #   Validators::Format.call("123abc", format: { with: /\A[a-z]+\d+\z/ })
-      #   # raises ValidationError: "is an invalid format"
+      # @raise [ValidationError] When the value doesn't match the required format
       #
-      # @example Using a custom message
-      #   Validators::Format.call("123abc", format: { with: /\A[a-z]+\d+\z/, message: "Username must start with letters" })
-      #   # raises ValidationError: "Username must start with letters"
+      # @example Direct regex validation
+      #   Format.call("user@example.com", /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+      #   # => nil (validation passes)
+      # @example Validate with required pattern
+      #   Format.call("ABC123", with: /\A[A-Z]{3}\d{3}\z/)
+      #   # => nil (validation passes)
+      # @example Validate with exclusion pattern
+      #   Format.call("hello", without: /\d/)
+      #   # => nil (validation passes - no digits)
+      # @example Validate with both patterns
+      #   Format.call("test123", with: /\A\w+\z/, without: /\A\d+\z/)
+      #   # => nil (validation passes - alphanumeric but not all digits)
+      # @example Validate with custom message
+      #   Format.call("invalid", with: /\A\d+\z/, message: "Must contain only digits")
+      #   # => raises ValidationError with custom message
       def call(value, options = {})
-        valid = case options
-                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
+        match =
+          if options.is_a?(Regexp)
+            value&.match?(options)
+          else
+            case options
+            in with:, without:
+              value&.match?(with) && !value&.match?(without)
+            in with:
+              value&.match?(with)
+            in without:
+              !value&.match?(without)
+            else
+              false
+            end
+          end
 
-        return if valid
+        return if match
 
-        raise ValidationError, options[:message] || I18n.t(
-          "cmdx.validators.format",
-          default: "is an invalid format"
-        )
+        message = options[:message] if options.is_a?(Hash)
+        raise ValidationError, message || Locale.t("cmdx.validators.format")
       end
 
     end