cmdx 1.0.1 → 1.1.1

data/lib/cmdx/utils/monotonic_runtime.rb

@@ -2,79 +2,27 @@
 
 module CMDx
   module Utils
-    # Utility for measuring execution time using monotonic clock.
+    # Utility module for measuring execution time using monotonic clock.
     #
-    # MonotonicRuntime provides accurate execution time measurement that is
-    # unaffected by system clock adjustments, leap seconds, or other time
-    # synchronization events. Uses Ruby's Process.clock_gettime with
-    # CLOCK_MONOTONIC for reliable performance measurements.
-    #
-    # @example Basic runtime measurement
-    #   runtime = Utils::MonotonicRuntime.call do
-    #     sleep(1.5)
-    #     # ... task execution code ...
-    #   end
-    #   # => 1500 (milliseconds)
-    #
-    # @example Task execution timing
-    #   class ProcessOrderTask < CMDx::Task
-    #     def call
-    #       runtime = Utils::MonotonicRuntime.call do
-    #         # Complex business logic
-    #         process_payment
-    #         update_inventory
-    #         send_confirmation
-    #       end
-    #       logger.info "Order processed in #{runtime}ms"
-    #     end
-    #   end
-    #
-    # @example Performance benchmarking
-    #   fast_time = Utils::MonotonicRuntime.call { fast_algorithm }
-    #   slow_time = Utils::MonotonicRuntime.call { slow_algorithm }
-    #   puts "Fast algorithm is #{slow_time / fast_time}x faster"
-    #
-    # @see CMDx::Task Uses this internally to measure task execution time
-    # @see CMDx::Result#runtime Contains the measured execution time
+    # This module provides functionality to measure the time taken to execute
+    # a block of code using the monotonic clock, which is not affected by
+    # system clock adjustments and provides more accurate timing measurements.
     module MonotonicRuntime
 
       module_function
 
       # Measures the execution time of a given block using monotonic clock.
       #
-      # Executes the provided block and returns the elapsed time in milliseconds.
-      # Uses Process.clock_gettime with CLOCK_MONOTONIC to ensure accurate
-      # timing that is immune to system clock changes.
-      #
-      # @yield Block of code to measure execution time for
-      # @return [Integer] Execution time in milliseconds
-      #
-      # @example Simple timing measurement
-      #   time_taken = MonotonicRuntime.call do
-      #     expensive_operation
-      #   end
-      #   puts "Operation took #{time_taken}ms"
+      # @param block [Proc] the block of code to measure execution time for
+      # @yield executes the provided block while measuring its runtime
       #
-      # @example Database query timing
-      #   query_time = MonotonicRuntime.call do
-      #     User.joins(:orders).where(active: true).count
-      #   end
-      #   logger.debug "Query executed in #{query_time}ms"
+      # @return [Integer] the execution time in milliseconds
       #
-      # @example API call timing with error handling
-      #   api_time = MonotonicRuntime.call do
-      #     begin
-      #       external_api.fetch_data
-      #     rescue => e
-      #       logger.error "API call failed: #{e.message}"
-      #       raise
-      #     end
-      #   end
-      #   # Time is measured even if an exception occurs
+      # @example Basic usage
+      #   MonotonicRuntime.call { sleep(0.1) } #=> 100 (approximately)
       #
-      # @note The block's return value is discarded; only execution time is returned
-      # @note Uses millisecond precision for practical performance monitoring
-      # @note Monotonic clock ensures accurate timing regardless of system clock changes
+      # @example Measuring database query time
+      #   MonotonicRuntime.call { User.find(1) } #=> 15 (milliseconds)
       def call(&)
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
         yield

data/lib/cmdx/utils/name_affix.rb

@@ -2,92 +2,42 @@
 
 module CMDx
   module Utils
-    # Utility for generating method names with prefixes and suffixes.
+    # Utility module for generating method names with configurable prefixes and suffixes.
     #
-    # NameAffix provides flexible method name generation for dynamic method
-    # creation, delegation, and metaprogramming scenarios. Supports custom
-    # prefixes, suffixes, and complete name overrides for method naming
-    # conventions in CMDx's parameter and delegation systems.
-    #
-    # @example Basic prefix and suffix usage
-    #   Utils::NameAffix.call(:name, "user", prefix: true, suffix: true)
-    #   # => :user_name_user
-    #
-    # @example Custom prefix
-    #   Utils::NameAffix.call(:email, "admin", prefix: "get_")
-    #   # => :get_email
-    #
-    # @example Custom suffix
-    #   Utils::NameAffix.call(:count, "items", suffix: "_total")
-    #   # => :count_total
-    #
-    # @example Complete name override
-    #   Utils::NameAffix.call(:original, "source", as: :custom_method)
-    #   # => :custom_method
-    #
-    # @example Parameter delegation usage
-    #   class MyTask < CMDx::Task
-    #     required :user_id
-    #
-    #     # Internally uses NameAffix for method generation
-    #     # Creates methods like user_id, user_id?, etc.
-    #   end
-    #
-    # @see CMDx::Parameter Uses this for parameter method name generation
-    # @see CMDx::CoreExt::Module Uses this for delegation method naming
+    # This module provides functionality to dynamically construct method names
+    # by applying prefixes and suffixes to a base method name, with support
+    # for custom naming through options.
     module NameAffix
 
-      # Proc for handling affix logic with boolean or custom values
-      # @return [Proc] processor for affix options that handles true/false and custom strings
+      # Proc that handles affix logic - returns block result if value is true, otherwise returns value as-is.
       AFFIX = proc do |o, &block|
         o == true ? block.call : o
       end.freeze
 
       module_function
 
-      # Generates a method name with optional prefix and suffix.
-      #
-      # Creates a method name by combining the base method name with optional
-      # prefixes and suffixes. Supports boolean flags for default affixes or
-      # custom string values for specific naming patterns.
-      #
-      # @param method_name [Symbol, String] Base method name to transform
-      # @param source [String] Source identifier used for default prefix/suffix generation
-      # @param options [Hash] Configuration options for name generation
-      # @option options [Boolean, String] :prefix (false) Add prefix - true for "#{source}_", string for custom
-      # @option options [Boolean, String] :suffix (false) Add suffix - true for "_#{source}", string for custom
-      # @option options [Symbol] :as Override the entire generated name
-      #
-      # @return [Symbol] Generated method name with applied affixes
-      #
-      # @example Default prefix generation
-      #   NameAffix.call(:method, "user", prefix: true)
-      #   # => :user_method
+      # Generates a method name with optional prefix and suffix based on source and options.
       #
-      # @example Custom prefix
-      #   NameAffix.call(:method, "user", prefix: "get_")
-      #   # => :get_method
+      # @param method_name [String, Symbol] the base method name to be affixed
+      # @param source [String, Symbol] the source identifier used for generating default prefixes/suffixes
+      # @param options [Hash] configuration options for name generation
+      # @option options [String, Symbol, true] :prefix custom prefix or true for default "#{source}_"
+      # @option options [String, Symbol, true] :suffix custom suffix or true for default "_#{source}"
+      # @option options [String, Symbol] :as override the entire generated name
       #
-      # @example Default suffix generation
-      #   NameAffix.call(:method, "user", suffix: true)
-      #   # => :method_user
+      # @return [Symbol] the generated method name as a symbol
       #
-      # @example Custom suffix
-      #   NameAffix.call(:method, "user", suffix: "_count")
-      #   # => :method_count
+      # @example Using default prefix and suffix
+      #   NameAffix.call("process", "user", prefix: true, suffix: true) #=> :user_process_user
       #
-      # @example Combined prefix and suffix
-      #   NameAffix.call(:name, "user", prefix: "get_", suffix: "_value")
-      #   # => :get_name_value
+      # @example Using custom prefix
+      #   NameAffix.call("process", "user", prefix: "handle_") #=> :handle_process
       #
-      # @example Complete name override (ignores prefix/suffix)
-      #   NameAffix.call(:original, "user", prefix: true, as: :custom)
-      #   # => :custom
+      # @example Using custom suffix
+      #   NameAffix.call("process", "user", suffix: "_data") #=> :process_data
       #
-      # @example Parameter method generation
-      #   # CMDx internally uses this for parameter methods:
-      #   NameAffix.call(:email, "user", suffix: "?")  # => :email?
-      #   NameAffix.call(:process, "order", prefix: "can_")  # => :can_process
+      # @example Overriding with custom name
+      #   NameAffix.call("process", "user", as: "custom_method") #=> :custom_method
       def call(method_name, source, options = {})
         options[:as] || begin
           prefix = AFFIX.call(options[:prefix]) { "#{source}_" }

data/lib/cmdx/validator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Base class for implementing parameter validation functionality in task processing.
+  #
+  # Validators are used to validate parameter values against specific rules and constraints,
+  # supporting both built-in validation types and custom validation logic. All validator
+  # implementations must inherit from this class and implement the abstract call method.
+  class Validator
+
+    # Executes a validator by creating a new instance and calling it.
+    #
+    # @param value [Object] the value to be validated
+    # @param options [Hash] additional options for the validation
+    #
+    # @return [Object] the validated value if validation passes
+    #
+    # @raise [UndefinedCallError] when the validator subclass doesn't implement call
+    # @raise [ValidationError] when validation fails
+    #
+    # @example Execute a validator on a value
+    #   PresenceValidator.call("some_value") #=> "some_value"
+    #
+    # @example Execute with options
+    #   NumericValidator.call(42, greater_than: 10) #=> 42
+    def self.call(value, options = {})
+      new.call(value, options)
+    end
+
+    # Abstract method that must be implemented by validator subclasses.
+    #
+    # This method contains the actual validation logic to verify the input
+    # value meets the specified criteria. Subclasses must override this method
+    # to provide their specific validation implementation.
+    #
+    # @param value [Object] the value to be validated
+    # @param options [Hash] additional options for the validation
+    #
+    # @return [Object] the validated value if validation passes
+    #
+    # @raise [UndefinedCallError] always raised in the base class
+    # @raise [ValidationError] when validation fails in subclass implementations
+    #
+    # @example Implement in a subclass
+    #   class BlankValidator < CMDx::Validator
+    #     def call(value, options = {})
+    #       if value.nil? || value.empty?
+    #         raise ValidationError, options[:message] || "Value cannot be blank"
+    #       end
+    #     end
+    #   end
+    def call(value, options = {}) # rubocop:disable Lint/UnusedMethodArgument
+      raise UndefinedCallError, "call method not defined in #{self.class.name}"
+    end
+
+  end
+end

data/lib/cmdx/validator_registry.rb

@@ -0,0 +1,108 @@
+# 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.
+  class ValidatorRegistry
+
+    # @return [Hash] internal hash storing validator implementations by type
+    attr_reader :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.
+    #
+    # @return [ValidatorRegistry] a new registry instance with built-in validators
+    #
+    # @example Create a new validator registry
+    #   registry = ValidatorRegistry.new
+    #   registry.registry.keys #=> [:exclusion, :format, :inclusion, :length, :numeric, :presence]
+    def initialize
+      @registry = {
+        exclusion: Validators::Exclusion,
+        format: Validators::Format,
+        inclusion: Validators::Inclusion,
+        length: Validators::Length,
+        numeric: Validators::Numeric,
+        presence: Validators::Presence
+      }
+    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.
+    #
+    # @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)
+    #
+    # @example Register a symbol validator
+    #   registry.register(:zipcode, :validate_zipcode)
+    #
+    # @example Register a proc validator
+    #   registry.register(:positive, ->(value, options) { value > 0 })
+    #
+    # @example Method chaining
+    #   registry.register(:email, EmailValidator)
+    #           .register(:phone, PhoneValidator)
+    def register(type, validator)
+      registry[type] = 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.
+    #
+    # @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
+    #
+    # @return [Object, nil] the validation result or nil if validation was skipped
+    #
+    # @raise [UnknownValidatorError] if the specified validator type is not registered
+    #
+    # @example Validate with a built-in validator
+    #   registry.call(task, :presence, "", {})
+    #   #=> may raise ValidationError if value is blank
+    #
+    # @example Validate with options
+    #   registry.call(task, :length, "hello", minimum: 3, maximum: 10)
+    #   #=> validates string length is between 3 and 10 characters
+    #
+    # @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)
+
+      case validator = registry[type]
+      when Symbol, String, Proc
+        task.cmdx_try(validator, value, options)
+      else
+        validator.call(value, options)
+      end
+    end
+
+  end
+end

data/lib/cmdx/validators/exclusion.rb

@@ -2,96 +2,46 @@
 
 module CMDx
   module Validators
-    # Exclusion validator for parameter validation against forbidden values.
+    # Validator class for excluding values from a specified set.
     #
-    # The Exclusion validator ensures that parameter values are NOT within a
-    # specified set of forbidden values. It supports both array-based exclusion
-    # (specific values) and range-based exclusion (value ranges).
-    #
-    # @example Basic exclusion validation with array
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :status, exclusion: { in: ['cancelled', 'refunded'] }
-    #     required :priority, exclusion: { in: [0, -1] }
-    #   end
-    #
-    # @example Range-based exclusion
-    #   class ProcessUserTask < CMDx::Task
-    #     required :age, exclusion: { in: 0..17 }  # Must be 18 or older
-    #     required :score, exclusion: { within: 90..100 }  # Cannot be in top 10%
-    #   end
-    #
-    # @example Custom error messages
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :status, exclusion: {
-    #       in: ['cancelled', 'refunded'],
-    #       of_message: "cannot be cancelled or refunded"
-    #     }
-    #     required :age, exclusion: {
-    #       in: 0..17,
-    #       in_message: "must be %{min} or older"
-    #     }
-    #   end
-    #
-    # @example Exclusion validation behavior
-    #   # Array exclusion
-    #   Exclusion.call("active", exclusion: { in: ['cancelled'] })     # passes
-    #   Exclusion.call("cancelled", exclusion: { in: ['cancelled'] })  # raises ValidationError
-    #
-    #   # Range exclusion
-    #   Exclusion.call(25, exclusion: { in: 0..17 })  # passes
-    #   Exclusion.call(15, exclusion: { in: 0..17 })  # raises ValidationError
-    #
-    # @see CMDx::Validators::Inclusion For validating values must be in a set
-    # @see CMDx::Parameter Parameter validation integration
-    # @see CMDx::ValidationError Raised when validation fails
-    module Exclusion
+    # 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
 
-      extend self
-
-      # Validates that a parameter value is not in the excluded set.
-      #
-      # Checks that the value is not present in the specified array or range
-      # of forbidden values. Raises ValidationError if the value is found
-      # in the exclusion set.
+      # Validates that the given value is not included in the exclusion set.
       #
-      # @param value [Object] The parameter value to validate
-      # @param options [Hash] Validation configuration options
-      # @option options [Hash] :exclusion Exclusion validation configuration
-      # @option options [Array, Range] :exclusion.in Values/range to exclude
-      # @option options [Array, Range] :exclusion.within Alias for :in
-      # @option options [String] :exclusion.of_message Error message for array exclusion
-      # @option options [String] :exclusion.in_message Error message for range exclusion
-      # @option options [String] :exclusion.within_message Alias for :in_message
-      # @option options [String] :exclusion.message General error message override
+      # @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 value is found in the exclusion set
       #
-      # @example Array exclusion validation
-      #   Exclusion.call("pending", exclusion: { in: ['cancelled', 'failed'] })
-      #   # => passes without error
+      # @raise [ValidationError] if the value is found in the exclusion set
       #
-      # @example Failed array exclusion
-      #   Exclusion.call("cancelled", exclusion: { in: ['cancelled', 'failed'] })
-      #   # => raises ValidationError: "must not be one of: \"cancelled\", \"failed\""
+      # @example Excluding from an array
+      #   Validators::Exclusion.call("admin", exclusion: { in: ["admin", "root"] })
+      #   # raises ValidationError: "must not be one of: \"admin\", \"root\""
       #
-      # @example Range exclusion validation
-      #   Exclusion.call(25, exclusion: { in: 0..17 })
-      #   # => passes without error
+      # @example Excluding from a range
+      #   Validators::Exclusion.call(5, exclusion: { in: 1..10 })
+      #   # raises ValidationError: "must not be within 1 and 10"
       #
-      # @example Failed range exclusion
-      #   Exclusion.call(15, exclusion: { in: 0..17 })
-      #   # => raises ValidationError: "must not be within 0 and 17"
+      # @example Valid exclusion
+      #   Validators::Exclusion.call("user", exclusion: { in: ["admin", "root"] })
+      #   #=> nil (no error raised)
       #
-      # @example Custom error messages
-      #   Exclusion.call("admin", exclusion: {
-      #     in: ['admin', 'root'],
-      #     of_message: "role is restricted"
-      #   })
-      #   # => raises ValidationError: "role is restricted"
+      # @example Using a custom message
+      #   Validators::Exclusion.call("admin", exclusion: { in: ["admin", "root"], message: "Reserved username not allowed" })
+      #   # raises ValidationError: "Reserved username not allowed"
       def call(value, options = {})
-        values = options.dig(:exclusion, :in) ||
-                 options.dig(:exclusion, :within)
+        values = options[:in] || options[:within]
 
         if values.is_a?(Range)
           raise_within_validation_error!(values.begin, values.end, options) if values.cover?(value)
@@ -102,15 +52,21 @@ module CMDx
 
       private
 
-      # Raises validation error for array-based exclusion violations.
+      # Raises a validation error for array-based exclusion.
       #
-      # @param values [Array] The excluded values array
-      # @param options [Hash] Validation options containing error messages
-      # @raise [ValidationError] With formatted error message
+      # @param values [Array] the excluded values
+      # @param options [Hash] validation options
+      #
+      # @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\""
       def raise_of_validation_error!(values, options)
-        values  = values.map(&:inspect).join(", ")
-        message = options.dig(:exclusion, :of_message) ||
-                  options.dig(:exclusion, :message)
+        values  = values.map(&:inspect).join(", ") unless values.nil?
+        message = options[:of_message] || options[:message]
         message %= { values: } unless message.nil?
 
         raise ValidationError, message || I18n.t(
@@ -120,16 +76,21 @@ module CMDx
         )
       end
 
-      # Raises validation error for range-based exclusion violations.
+      # 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]
+      #
+      # @raise [ValidationError] always raised with appropriate message
       #
-      # @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
+      # @example
+      #   raise_within_validation_error!(1, 10, {})
+      #   # raises ValidationError: "must not be within 1 and 10"
       def raise_within_validation_error!(min, max, options)
-        message = options.dig(:exclusion, :in_message) ||
-                  options.dig(:exclusion, :within_message) ||
-                  options.dig(:exclusion, :message)
+        message = options[:in_message] || options[:within_message] || options[:message]
         message %= { min:, max: } unless message.nil?
 
         raise ValidationError, message || I18n.t(