cmdx 1.1.2 → 1.5.0

data/lib/cmdx/validators/numeric.rb

@@ -2,232 +2,157 @@
 
 module CMDx
   module Validators
-    # Validator class for validating numeric values with various constraints.
+    # Validates numeric values against various constraints and ranges
     #
     # This validator ensures that numeric values meet specified criteria such as
-    # being within a range, having minimum/maximum values, or matching exact values.
-    # It supports both inclusive and exclusive range validation, as well as discrete
-    # value matching and rejection.
-    class Numeric < Validator
-
-      # Validates that the given numeric value meets the specified constraints.
-      #
-      # @param value [Numeric] the numeric value to validate
-      # @param options [Hash] validation options containing numeric configuration
-      # @option options [Hash] :numeric numeric validation configuration
-      # @option options [Range] :numeric.within the range the value must be within
-      # @option options [Range] :numeric.not_within the range the value must not be within
-      # @option options [Range] :numeric.in alias for :within
-      # @option options [Range] :numeric.not_in alias for :not_within
-      # @option options [Numeric] :numeric.min the minimum allowed value (can be combined with :max)
-      # @option options [Numeric] :numeric.max the maximum allowed value (can be combined with :min)
-      # @option options [Numeric] :numeric.is the exact value required
-      # @option options [Numeric] :numeric.is_not the exact value that is not allowed
-      # @option options [String] :numeric.message custom error message for any validation
-      # @option options [String] :numeric.within_message custom error message for within validation
-      # @option options [String] :numeric.in_message alias for :within_message
-      # @option options [String] :numeric.not_within_message custom error message for not_within validation
-      # @option options [String] :numeric.not_in_message alias for :not_within_message
-      # @option options [String] :numeric.min_message custom error message for min validation
-      # @option options [String] :numeric.max_message custom error message for max validation
-      # @option options [String] :numeric.is_message custom error message for is validation
-      # @option options [String] :numeric.is_not_message custom error message for is_not validation
-      #
-      # @return [void]
-      #
-      # @raise [ValidationError] if the value doesn't meet the specified constraints
-      # @raise [ArgumentError] if no known numeric validator options are provided
-      #
-      # @example Range validation
-      #   Validators::Numeric.call(5, numeric: { within: 1..10 })
-      #   #=> nil (no error raised)
-      #
-      # @example Range exclusion
-      #   Validators::Numeric.call(5, numeric: { not_within: 1..10 })
-      #   # raises ValidationError: "must not be within 1 and 10"
-      #
-      # @example Min/max validation
-      #   Validators::Numeric.call(15, numeric: { min: 10, max: 20 })
-      #   #=> nil (no error raised)
-      #
-      # @example Minimum value validation
-      #   Validators::Numeric.call(5, numeric: { min: 10 })
-      #   # raises ValidationError: "must be at least 10"
-      #
-      # @example Exact value validation
-      #   Validators::Numeric.call(42, numeric: { is: 42 })
-      #   #=> nil (no error raised)
-      #
-      # @example Custom error message
-      #   Validators::Numeric.call(5, numeric: { min: 10, message: "Age must be at least %{min}" })
-      #   # raises ValidationError: "Age must be at least 10"
+    # minimum/maximum bounds, exact matches, or range inclusions. It supports
+    # both inclusive and exclusive range validations with customizable error messages.
+    module Numeric
+
+      extend self
+
+      # Validates a numeric value against the specified options
+      #
+      # @param value [Numeric] The numeric value to validate
+      # @param options [Hash] Validation configuration options
+      # @option options [Range] :within Range that the value must fall within (inclusive)
+      # @option options [Range] :not_within Range that the value must not fall within
+      # @option options [Range] :in Alias for :within option
+      # @option options [Range] :not_in Alias for :not_within option
+      # @option options [Numeric] :min Minimum allowed value (inclusive)
+      # @option options [Numeric] :max Maximum allowed value (inclusive)
+      # @option options [Numeric] :is Exact value that must match
+      # @option options [Numeric] :is_not Value that must not match
+      # @option options [String] :message Custom error message template
+      # @option options [String] :within_message Custom message for range validations
+      # @option options [String] :not_within_message Custom message for exclusion validations
+      # @option options [String] :min_message Custom message for minimum validation
+      # @option options [String] :max_message Custom message for maximum validation
+      # @option options [String] :is_message Custom message for exact match validation
+      # @option options [String] :is_not_message Custom message for exclusion validation
+      #
+      # @return [nil] Returns nil if validation passes
+      #
+      # @raise [ValidationError] When the value fails validation
+      # @raise [ArgumentError] When unknown validator options are provided
+      #
+      # @example Validate value within a range
+      #   Numeric.call(5, within: 1..10)
+      #   # => nil (validation passes)
+      # @example Validate minimum and maximum bounds
+      #   Numeric.call(15, min: 10, max: 20)
+      #   # => nil (validation passes)
+      # @example Validate exact value match
+      #   Numeric.call(42, is: 42)
+      #   # => nil (validation passes)
+      # @example Validate value exclusion
+      #   Numeric.call(5, not_in: 1..10)
+      #   # => nil (validation passes - 5 is not in 1..10)
       def call(value, options = {})
         case options
-        in { within: within }
+        in within:
           raise_within_validation_error!(within.begin, within.end, options) unless within.cover?(value)
-        in { not_within: not_within }
+        in not_within:
           raise_not_within_validation_error!(not_within.begin, not_within.end, options) if not_within.cover?(value)
-        in { in: yn }
-          raise_within_validation_error!(yn.begin, yn.end, options) unless yn.cover?(value)
-        in { not_in: not_in }
+        in in: xin
+          raise_within_validation_error!(xin.begin, xin.end, options) unless xin.cover?(value)
+        in not_in:
           raise_not_within_validation_error!(not_in.begin, not_in.end, options) if not_in.cover?(value)
-        in { min: min, max: max }
+        in min:, max:
           raise_within_validation_error!(min, max, options) unless value.between?(min, max)
-        in { min: min }
+        in min:
           raise_min_validation_error!(min, options) unless min <= value
-        in { max: max }
+        in max:
           raise_max_validation_error!(max, options) unless value <= max
-        in { is: is }
+        in is:
           raise_is_validation_error!(is, options) unless value == is
-        in { is_not: is_not }
+        in is_not:
           raise_is_not_validation_error!(is_not, options) if value == is_not
         else
-          raise ArgumentError, "no known numeric validator options given"
+          raise ArgumentError, "unknown numeric validator options given"
         end
       end
 
       private
 
-      # Raises a validation error for within/range validation.
+      # Raises validation error for range inclusion validation
       #
-      # @param min [Numeric] the minimum value of the range
-      # @param max [Numeric] the maximum value of the range
-      # @param options [Hash] validation options
+      # @param min [Numeric] The minimum value of the allowed range
+      # @param max [Numeric] The maximum value of the allowed range
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @return [void]
-      #
-      # @raise [ValidationError] always raised with appropriate message
-      #
-      # @example
-      #   raise_within_validation_error!(1, 10, {})
-      #   # raises ValidationError: "must be within 1 and 10"
+      # @raise [ValidationError] With appropriate error message
       def raise_within_validation_error!(min, max, options)
         message = options[:within_message] || options[:in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.numeric.within",
-          min:,
-          max:,
-          default: "must be within #{min} and #{max}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.numeric.within", min:, max:)
       end
 
-      # Raises a validation error for not_within/range exclusion validation.
-      #
-      # @param min [Numeric] the minimum value of the excluded range
-      # @param max [Numeric] the maximum value of the excluded range
-      # @param options [Hash] validation options
+      # Raises validation error for range exclusion validation
       #
-      # @return [void]
+      # @param min [Numeric] The minimum value of the excluded range
+      # @param max [Numeric] The maximum value of the excluded range
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @raise [ValidationError] always raised with appropriate message
-      #
-      # @example
-      #   raise_not_within_validation_error!(1, 10, {})
-      #   # raises ValidationError: "must not be within 1 and 10"
+      # @raise [ValidationError] With appropriate error message
       def raise_not_within_validation_error!(min, max, options)
         message = options[:not_within_message] || options[:not_in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.numeric.not_within",
-          min:,
-          max:,
-          default: "must not be within #{min} and #{max}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.numeric.not_within", min:, max:)
       end
 
-      # Raises a validation error for minimum value validation.
-      #
-      # @param min [Numeric] the minimum allowed value
-      # @param options [Hash] validation options
-      #
-      # @return [void]
+      # Raises validation error for minimum value validation
       #
-      # @raise [ValidationError] always raised with appropriate message
+      # @param min [Numeric] The minimum allowed value
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @example
-      #   raise_min_validation_error!(10, {})
-      #   # raises ValidationError: "must be at least 10"
+      # @raise [ValidationError] With appropriate error message
       def raise_min_validation_error!(min, options)
         message = options[:min_message] || options[:message]
         message %= { min: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.numeric.min",
-          min:,
-          default: "must be at least #{min}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.numeric.min", min:)
       end
 
-      # Raises a validation error for maximum value validation.
+      # Raises validation error for maximum value validation
       #
-      # @param max [Numeric] the maximum allowed value
-      # @param options [Hash] validation options
+      # @param max [Numeric] The maximum allowed value
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @return [void]
-      #
-      # @raise [ValidationError] always raised with appropriate message
-      #
-      # @example
-      #   raise_max_validation_error!(100, {})
-      #   # raises ValidationError: "must be at most 100"
+      # @raise [ValidationError] With appropriate error message
       def raise_max_validation_error!(max, options)
         message = options[:max_message] || options[:message]
         message %= { max: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.numeric.max",
-          max:,
-          default: "must be at most #{max}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.numeric.max", max:)
       end
 
-      # Raises a validation error for exact value validation.
-      #
-      # @param is [Numeric] the exact value required
-      # @param options [Hash] validation options
+      # Raises validation error for exact value match validation
       #
-      # @return [void]
+      # @param is [Numeric] The exact value that was expected
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @raise [ValidationError] always raised with appropriate message
-      #
-      # @example
-      #   raise_is_validation_error!(42, {})
-      #   # raises ValidationError: "must be 42"
+      # @raise [ValidationError] With appropriate error message
       def raise_is_validation_error!(is, options)
         message = options[:is_message] || options[:message]
         message %= { is: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.numeric.is",
-          is:,
-          default: "must be #{is}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.numeric.is", is:)
       end
 
-      # Raises a validation error for exact value exclusion validation.
-      #
-      # @param is_not [Numeric] the exact value that is not allowed
-      # @param options [Hash] validation options
-      #
-      # @return [void]
+      # Raises validation error for value exclusion validation
       #
-      # @raise [ValidationError] always raised with appropriate message
+      # @param is_not [Numeric] The value that was not allowed
+      # @param options [Hash] Validation options containing custom messages
       #
-      # @example
-      #   raise_is_not_validation_error!(0, {})
-      #   # raises ValidationError: "must not be 0"
+      # @raise [ValidationError] With appropriate error message
       def raise_is_not_validation_error!(is_not, options)
         message = options[:is_not_message] || options[:message]
         message %= { is_not: } unless message.nil?
 
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.numeric.is_not",
-          is_not:,
-          default: "must not be #{is_not}"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.numeric.is_not", is_not:)
       end
 
     end

data/lib/cmdx/validators/presence.rb

@@ -2,54 +2,44 @@
 
 module CMDx
   module Validators
-    # Validator class for ensuring values are present (not empty or nil).
+    # Validates that a value is present and not empty
     #
-    # This validator checks that a value is not empty, blank, or nil. For strings,
-    # it validates that there are non-whitespace characters. For objects that respond
-    # to empty?, it ensures they are not empty. For all other objects, it validates
-    # they are not nil.
-    class Presence < Validator
+    # This validator ensures that the given value exists and contains meaningful content.
+    # It handles different value types appropriately:
+    # - Strings: checks for non-whitespace characters
+    # - Collections: checks for non-empty collections
+    # - Other objects: checks for non-nil values
+    module Presence
 
-      # Validates that the given value is present (not empty or nil).
-      #
-      # @param value [Object] the value to validate
-      # @param options [Hash] validation options containing presence configuration
-      # @option options [Hash] :presence presence validation configuration
-      # @option options [String] :presence.message custom error message
-      #
-      # @return [void] returns nothing when validation passes
-      #
-      # @raise [ValidationError] if the value is empty, blank, or nil
-      #
-      # @example Validating a non-empty string
-      #   Validators::Presence.call("hello", presence: {})
-      #   #=> nil (no error raised)
-      #
-      # @example Validating an empty string
-      #   Validators::Presence.call("", presence: {})
-      #   # raises ValidationError: "cannot be empty"
-      #
-      # @example Validating a whitespace-only string
-      #   Validators::Presence.call("   ", presence: {})
-      #   # raises ValidationError: "cannot be empty"
-      #
-      # @example Validating a non-empty array
-      #   Validators::Presence.call([1, 2, 3], presence: {})
-      #   #=> nil (no error raised)
-      #
-      # @example Validating an empty array
-      #   Validators::Presence.call([], presence: {})
-      #   # raises ValidationError: "cannot be empty"
-      #
-      # @example Validating a nil value
-      #   Validators::Presence.call(nil, presence: {})
-      #   # raises ValidationError: "cannot be empty"
-      #
-      # @example Using a custom message
-      #   Validators::Presence.call("", presence: { message: "This field is required" })
-      #   # raises ValidationError: "This field is required"
+      extend self
+
+      # Validates that a value is present and not empty
+      #
+      # @param value [Object] The value to validate for presence
+      # @param options [Hash] Validation configuration options
+      # @option options [String] :message Custom error message
+      #
+      # @return [nil] Returns nil if validation passes
+      #
+      # @raise [ValidationError] When the value is empty, nil, or contains only whitespace
+      #
+      # @example Validate string presence
+      #   Presence.call("hello world")
+      #   # => nil (validation passes)
+      # @example Validate empty string
+      #   Presence.call("   ")
+      #   # => raises ValidationError
+      # @example Validate array presence
+      #   Presence.call([1, 2, 3])
+      #   # => nil (validation passes)
+      # @example Validate empty array
+      #   Presence.call([])
+      #   # => raises ValidationError
+      # @example Validate with custom message
+      #   Presence.call(nil, message: "Value cannot be blank")
+      #   # => raises ValidationError with custom message
       def call(value, options = {})
-        present =
+        match =
           if value.is_a?(String)
             /\S/.match?(value)
           elsif value.respond_to?(:empty?)
@@ -58,13 +48,10 @@ module CMDx
             !value.nil?
           end
 
-        return if present
+        return if match
 
         message = options[:message] if options.is_a?(Hash)
-        raise ValidationError, message || I18n.t(
-          "cmdx.validators.presence",
-          default: "cannot be empty"
-        )
+        raise ValidationError, message || Locale.t("cmdx.validators.presence")
       end
 
     end

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.1.2"
+  VERSION = "1.5.0"
 
 end

data/lib/cmdx/worker.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Executes CMDx tasks with middleware support, error handling, and lifecycle management.
+  #
+  # The Worker class is responsible for orchestrating task execution, including
+  # pre-execution validation, execution with middleware, post-execution callbacks,
+  # and proper error handling for different types of failures.
+  class Worker
+
+    attr_reader :task
+
+    # @param task [CMDx::Task] The task to execute
+    #
+    # @return [CMDx::Worker] A new worker instance
+    #
+    # @example
+    #   worker = CMDx::Worker.new(my_task)
+    def initialize(task)
+      @task = task
+    end
+
+    # Executes a task with optional exception raising.
+    #
+    # @param task [CMDx::Task] The task to execute
+    # @param raise [Boolean] Whether to raise exceptions (default: false)
+    #
+    # @return [CMDx::Result] The execution result
+    #
+    # @raise [StandardError] When raise is true and execution fails
+    #
+    # @example
+    #   CMDx::Worker.execute(my_task)
+    #   CMDx::Worker.execute(my_task, raise: true)
+    def self.execute(task, raise: false)
+      instance = new(task)
+      raise ? instance.execute! : instance.execute
+    end
+
+    # Executes the task with graceful error handling.
+    #
+    # @return [CMDx::Result] The execution result
+    #
+    # @example
+    #   worker = CMDx::Worker.new(my_task)
+    #   result = worker.execute
+    def execute
+      task.class.settings[:middlewares].call!(task) do
+        pre_execution!
+        execution!
+      rescue UndefinedMethodError => e
+        raise(e) # No need to clear the Chain since exception is not being re-raised
+      rescue Fault => e
+        task.result.throw!(e.result, halt: false, cause: e)
+      rescue StandardError => e
+        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+      ensure
+        task.result.executed!
+        post_execution!
+      end
+
+      finalize_execution!
+    end
+
+    # Executes the task with exception raising on failure.
+    #
+    # @return [CMDx::Result] The execution result
+    #
+    # @raise [StandardError] When execution fails
+    #
+    # @example
+    #   worker = CMDx::Worker.new(my_task)
+    #   result = worker.execute!
+    def execute!
+      task.class.settings[:middlewares].call!(task) do
+        pre_execution!
+        execution!
+      rescue UndefinedMethodError => e
+        raise_exception(e)
+      rescue Fault => e
+        task.result.throw!(e.result, halt: false, cause: e)
+        halt_execution?(e) ? raise_exception(e) : post_execution!
+      rescue StandardError => e
+        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        raise_exception(e)
+      else
+        task.result.executed!
+        post_execution!
+      end
+
+      finalize_execution!
+    end
+
+    protected
+
+    # Determines if execution should halt based on breakpoint configuration.
+    #
+    # @param exception [Exception] The exception that occurred
+    #
+    # @return [Boolean] Whether execution should halt
+    #
+    # @example
+    #   halt_execution?(fault_exception)
+    def halt_execution?(exception)
+      breakpoints = task.class.settings[:breakpoints] || task.class.settings[:task_breakpoints]
+      breakpoints = Array(breakpoints).map(&:to_s).uniq
+
+      breakpoints.include?(exception.result.status)
+    end
+
+    # Raises an exception and clears the chain.
+    #
+    # @param exception [Exception] The exception to raise
+    #
+    # @raise [Exception] The provided exception
+    #
+    # @example
+    #   raise_exception(standard_error)
+    def raise_exception(exception)
+      Chain.clear
+      raise(exception)
+    end
+
+    # Invokes callbacks of a specific type for the task.
+    #
+    # @param type [Symbol] The type of callback to invoke
+    #
+    # @return [void]
+    #
+    # @example
+    #   invoke_callbacks(:before_execution)
+    def invoke_callbacks(type)
+      task.class.settings[:callbacks].invoke(type, task)
+    end
+
+    private
+
+    # Performs pre-execution tasks including validation and attribute verification.
+    def pre_execution!
+      invoke_callbacks(:before_validation)
+
+      task.class.settings[:attributes].define_and_verify(task)
+      return if task.errors.empty?
+
+      task.result.fail!(task.errors.to_s, messages: task.errors.to_h)
+    end
+
+    # Executes the main task logic.
+    def execution!
+      invoke_callbacks(:before_execution)
+
+      task.result.executing!
+      task.work
+    end
+
+    # Performs post-execution tasks including callback invocation.
+    def post_execution!
+      invoke_callbacks(:"on_#{task.result.state}")
+      invoke_callbacks(:on_executed) if task.result.executed?
+
+      invoke_callbacks(:"on_#{task.result.status}")
+      invoke_callbacks(:on_good) if task.result.good?
+      invoke_callbacks(:on_bad) if task.result.bad?
+    end
+
+    # Finalizes execution by freezing the task and logging results.
+    def finalize_execution!
+      Freezer.immute(task)
+
+      task.logger.tap do |logger|
+        logger.with_level(:info) do
+          logger.info { task.result.to_h }
+        end
+      end
+    end
+
+  end
+end