cmdx 1.0.0 → 1.1.0

data/lib/cmdx/parameter.rb

@@ -1,95 +1,60 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter definition class for CMDx task parameter management.
+  # Parameter definition system for CMDx tasks.
   #
-  # The Parameter class represents individual parameter definitions within CMDx tasks.
-  # It handles parameter configuration, validation rules, type coercion, nested parameters,
-  # and method generation for accessing parameter values within task instances.
-  #
-  # @example Basic parameter definition
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id
-  #     optional :priority
-  #   end
-  #
-  # @example Parameter with type coercion and validation
-  #   class ProcessUserTask < CMDx::Task
-  #     required :age, type: :integer, numeric: { min: 18, max: 120 }
-  #     required :email, type: :string, format: { with: /@/ }
-  #   end
-  #
-  # @example Nested parameters
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :shipping_address do
-  #       required :street, :city, :state
-  #       optional :apartment
-  #     end
-  #   end
-  #
-  # @example Parameter with custom source
-  #   class ProcessUserTask < CMDx::Task
-  #     required :name, source: :user
-  #     required :company_name, source: -> { user.company }
-  #   end
-  #
-  # @example Parameter with default values
-  #   class ProcessOrderTask < CMDx::Task
-  #     optional :priority, default: "normal"
-  #     optional :notification, default: -> { user.preferences.notify? }
-  #   end
-  #
-  # @see CMDx::Task Task parameter integration
-  # @see CMDx::ParameterValue Parameter value resolution and validation
-  # @see CMDx::Parameters Parameter collection management
+  # This class manages parameter definitions including type coercion, validation,
+  # and nested parameter structures. It handles the creation of accessor methods
+  # on task classes and provides a flexible system for defining required and
+  # optional parameters with various data types and validation rules.
   class Parameter
 
-    __cmdx_attr_delegator :invalid?, :valid?,
-                          to: :errors
+    cmdx_attr_delegator :invalid?, :valid?,
+                        to: :errors
 
     # @return [CMDx::Task] The task class this parameter belongs to
     attr_accessor :task
 
     # @return [Class] The task class this parameter is defined in
+    attr_reader :klass
+
     # @return [Parameter, nil] The parent parameter for nested parameters
+    attr_reader :parent
+
     # @return [Symbol] The parameter name
+    attr_reader :name
+
     # @return [Symbol, Array<Symbol>] The parameter type(s) for coercion
+    attr_reader :type
+
     # @return [Hash] The parameter configuration options
+    attr_reader :options
+
     # @return [Array<Parameter>] Child parameters for nested parameter definitions
+    attr_reader :children
+
     # @return [CMDx::Errors] Validation errors for this parameter
-    attr_reader :klass, :parent, :name, :type, :options, :children, :errors
+    attr_reader :errors
 
-    # Initializes a new Parameter instance.
-    #
-    # Creates a parameter definition with the specified configuration options.
-    # Automatically defines accessor methods on the task class and processes
-    # any nested parameter definitions provided via block.
+    # Creates a new parameter definition with the given name and options.
     #
     # @param name [Symbol] The parameter name
-    # @param options [Hash] Parameter configuration options
-    # @option options [Class] :klass The task class (required)
-    # @option options [Parameter] :parent Parent parameter for nesting
-    # @option options [Symbol, Array<Symbol>] :type (:virtual) Type(s) for coercion
-    # @option options [Boolean] :required (false) Whether parameter is required
-    # @option options [Object, Proc] :default Default value or callable
-    # @option options [Symbol, Proc] :source (:context) Parameter value source
-    # @option options [Hash] :* Validation options (presence, format, etc.)
-    #
-    # @yield Optional block for defining nested parameters
-    #
-    # @raise [KeyError] If :klass option is not provided
-    #
-    # @example Basic parameter creation
-    #   Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
-    #
-    # @example Parameter with validation
-    #   Parameter.new(:email, klass: MyTask, type: :string,
-    #                 format: { with: /@/ }, presence: true)
-    #
-    # @example Nested parameter with block
-    #   Parameter.new(:address, klass: MyTask) do
-    #     required :street, :city
-    #     optional :apartment
+    # @param options [Hash] Configuration options for the parameter
+    # @option options [Class] :klass The task class this parameter belongs to (required)
+    # @option options [Parameter] :parent The parent parameter for nested parameters
+    # @option options [Symbol, Array<Symbol>] :type (:virtual) The parameter type(s) for coercion
+    # @option options [Boolean] :required (false) Whether the parameter is required
+    # @param block [Proc] Optional block for defining nested parameters
+    # @return [Parameter] The newly created parameter
+    # @raise [KeyError] If the :klass option is not provided
+    #
+    # @example Create a simple parameter
+    #   Parameter.new(:name, klass: MyTask, type: :string, required: true)
+    #
+    # @example Create a parameter with nested children
+    #   Parameter.new(:user, klass: MyTask, type: :hash) do
+    #     required :name, type: :string
+    #     optional :age, type: :integer
     #   end
     def initialize(name, **options, &)
       @klass    = options.delete(:klass) || raise(KeyError, "klass option required")
@@ -108,26 +73,21 @@ module CMDx
 
     class << self
 
-      # Defines one or more optional parameters.
-      #
-      # Creates parameter definitions that are not required for task execution.
-      # Optional parameters return nil if not provided in the call arguments.
+      # Creates one or more optional parameters with the given names and options.
       #
-      # @param names [Array<Symbol>] Parameter names to define
-      # @param options [Hash] Parameter configuration options
-      # @yield Optional block for nested parameter definitions
+      # @param names [Array<Symbol>] Parameter names to create
+      # @param options [Hash] Configuration options for all parameters
+      # @param block [Proc] Optional block for defining nested parameters
+      # @return [Array<Parameter>] The created optional parameters
+      # @raise [ArgumentError] If no parameters are given or :as option is used with multiple names
       #
-      # @return [Array<Parameter>] Created parameter instances
-      # @raise [ArgumentError] If no parameter names provided or :as option used with multiple names
+      # @example Create multiple optional parameters
+      #   Parameter.optional(:name, :email, type: :string, klass: MyTask)
       #
-      # @example Single optional parameter
-      #   Parameter.optional(:priority, type: :string, default: "normal")
-      #
-      # @example Multiple optional parameters
-      #   Parameter.optional(:width, :height, type: :integer, numeric: { min: 0 })
-      #
-      # @example Optional parameter with validation
-      #   Parameter.optional(:email, type: :string, format: { with: /@/ })
+      # @example Create optional parameter with nested structure
+      #   Parameter.optional(:user, klass: MyTask, type: :hash) do
+      #     required :name, type: :string
+      #   end
       def optional(*names, **options, &)
         if names.none?
           raise ArgumentError, "no parameters given"
@@ -138,69 +98,56 @@ module CMDx
         names.filter_map { |n| new(n, **options, &) }
       end
 
-      # Defines one or more required parameters.
-      #
-      # Creates parameter definitions that must be provided for task execution.
-      # Missing required parameters will cause task validation to fail.
-      #
-      # @param names [Array<Symbol>] Parameter names to define
-      # @param options [Hash] Parameter configuration options
-      # @yield Optional block for nested parameter definitions
-      #
-      # @return [Array<Parameter>] Created parameter instances
-      # @raise [ArgumentError] If no parameter names provided or :as option used with multiple names
+      # Creates one or more required parameters with the given names and options.
       #
-      # @example Single required parameter
-      #   Parameter.required(:user_id, type: :integer)
+      # @param names [Array<Symbol>] Parameter names to create
+      # @param options [Hash] Configuration options for all parameters
+      # @param block [Proc] Optional block for defining nested parameters
+      # @return [Array<Parameter>] The created required parameters
+      # @raise [ArgumentError] If no parameters are given or :as option is used with multiple names
       #
-      # @example Multiple required parameters
-      #   Parameter.required(:first_name, :last_name, type: :string, presence: true)
+      # @example Create multiple required parameters
+      #   Parameter.required(:name, :email, type: :string, klass: MyTask)
       #
-      # @example Required parameter with complex validation
-      #   Parameter.required(:age, type: :integer, numeric: { within: 18..120 })
+      # @example Create required parameter with validation
+      #   Parameter.required(:age, type: :integer, validate: { numeric: { greater_than: 0 } }, klass: MyTask)
       def required(*names, **options, &)
         optional(*names, **options.merge(required: true), &)
       end
 
     end
 
-    # Defines nested optional parameters within this parameter.
+    # Creates one or more optional child parameters under this parameter.
     #
-    # Creates child parameter definitions that inherit this parameter as their source.
-    # Child parameters are only validated if the parent parameter is provided.
+    # @param names [Array<Symbol>] Parameter names to create
+    # @param options [Hash] Configuration options for all parameters
+    # @param block [Proc] Optional block for defining nested parameters
+    # @return [Array<Parameter>] The created optional child parameters
     #
-    # @param names [Array<Symbol>] Child parameter names to define
-    # @param options [Hash] Parameter configuration options
-    # @yield Optional block for further nested parameter definitions
+    # @example Add optional child parameters
+    #   user_param.optional(:nickname, :bio, type: :string)
     #
-    # @return [Array<Parameter>] Created child parameter instances
-    #
-    # @example Nested optional parameters
-    #   address_param.optional(:apartment, :unit, type: :string)
-    #
-    # @example Nested parameter with validation
-    #   user_param.optional(:age, type: :integer, numeric: { min: 0 })
+    # @example Add optional child with further nesting
+    #   user_param.optional(:preferences, type: :hash) do
+    #     required :theme, type: :string
+    #   end
     def optional(*names, **options, &)
       parameters = Parameter.optional(*names, **options.merge(klass: @klass, parent: self), &)
       children.concat(parameters)
     end
 
-    # Defines nested required parameters within this parameter.
-    #
-    # Creates child parameter definitions that are required if the parent parameter
-    # is provided. Child parameters inherit this parameter as their source.
+    # Creates one or more required child parameters under this parameter.
     #
-    # @param names [Array<Symbol>] Child parameter names to define
-    # @param options [Hash] Parameter configuration options
-    # @yield Optional block for further nested parameter definitions
+    # @param names [Array<Symbol>] Parameter names to create
+    # @param options [Hash] Configuration options for all parameters
+    # @param block [Proc] Optional block for defining nested parameters
+    # @return [Array<Parameter>] The created required child parameters
     #
-    # @return [Array<Parameter>] Created child parameter instances
+    # @example Add required child parameters
+    #   user_param.required(:first_name, :last_name, type: :string)
     #
-    # @example Nested required parameters
-    #   address_param.required(:street, :city, :state, type: :string)
-    #
-    # @example Nested parameter with validation
-    #   payment_param.required(:amount, type: :float, numeric: { min: 0.01 })
+    # @example Add required child with validation
+    #   user_param.required(:email, type: :string, validate: { format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i } })
     def required(*names, **options, &)
       parameters = Parameter.required(*names, **options.merge(klass: @klass, parent: self), &)
       children.concat(parameters)
@@ -208,117 +155,92 @@ module CMDx
 
     # Checks if this parameter is required.
     #
-    # @return [Boolean] true if parameter is required, false otherwise
+    # @return [Boolean] True if the parameter is required, false otherwise
     #
-    # @example
-    #   required_param.required?  # => true
-    #   optional_param.required?  # => false
+    # @example Check if parameter is required
+    #   param.required? # => true
     def required?
       !!@required
     end
 
     # Checks if this parameter is optional.
     #
-    # @return [Boolean] true if parameter is optional, false otherwise
+    # @return [Boolean] True if the parameter is optional, false otherwise
     #
-    # @example
-    #   required_param.optional?  # => false
-    #   optional_param.optional?  # => true
+    # @example Check if parameter is optional
+    #   param.optional? # => false
     def optional?
       !required?
     end
 
-    # Gets the method name that will be defined on the task class.
-    #
-    # The method name is generated using NameAffix utility and can be customized
-    # with :as, :prefix, and :suffix options.
-    #
-    # @return [Symbol] The generated method name
+    # Gets the method name that will be used to access this parameter's value.
     #
-    # @example Default method name
-    #   Parameter.new(:user_id, klass: Task).method_name  # => :user_id
+    # @return [Symbol] The method name for accessing this parameter
     #
-    # @example Custom method name
-    #   Parameter.new(:id, klass: Task, as: :user_id).method_name  # => :user_id
-    #
-    # @example Method name with prefix
-    #   Parameter.new(:name, klass: Task, prefix: "get_").method_name  # => :get_name
+    # @example Get method name
+    #   param.method_name # => :user_name
     def method_name
       @method_name ||= Utils::NameAffix.call(name, method_source, options)
     end
 
-    # Gets the source object/method that provides the parameter value.
-    #
-    # Determines where the parameter value should be retrieved from, defaulting
-    # to :context or inheriting from parent parameter.
+    # Gets the source object from which this parameter's value will be retrieved.
     #
-    # @return [Symbol] The source method name
+    # @return [Symbol] The method source (:context by default, or parent's method_name)
     #
-    # @example Default source
-    #   Parameter.new(:user_id, klass: Task).method_source  # => :context
-    #
-    # @example Custom source
-    #   Parameter.new(:name, klass: Task, source: :user).method_source  # => :user
-    #
-    # @example Inherited source from parent
-    #   child_param.method_source  # => parent parameter's method_name
+    # @example Get method source
+    #   param.method_source # => :context
     def method_source
       @method_source ||= options[:source] || parent&.method_name || :context
     end
 
     # Converts the parameter to a hash representation.
     #
-    # @return [Hash] Serialized parameter data including configuration and children
+    # @return [Hash] A hash representation of the parameter
     #
-    # @example
-    #   param.to_h
-    #   # => {
-    #   #   source: :context,
-    #   #   name: :user_id,
-    #   #   type: :integer,
-    #   #   required: true,
-    #   #   options: { numeric: { min: 1 } },
-    #   #   children: []
-    #   # }
+    # @example Convert to hash
+    #   param.to_h # => { name: :user_name, type: :string, required: true, ... }
     def to_h
       ParameterSerializer.call(self)
     end
 
-    # Converts the parameter to a string representation for inspection.
+    # Converts the parameter to a string representation.
     #
-    # @return [String] Human-readable parameter description
+    # @return [String] A string representation of the parameter
     #
-    # @example
-    #   param.to_s
-    #   # => "Parameter: name=user_id type=integer source=context required=true options={numeric: {min: 1}}"
+    # @example Convert to string
+    #   param.to_s # => "Parameter(name: user_name, type: string, required: true)"
     def to_s
       ParameterInspector.call(to_h)
     end
 
     private
 
-    # Defines the accessor method on the task class for this parameter.
+    # Defines the attribute accessor method for this parameter on the task class.
+    # The method handles parameter value retrieval, coercion, and validation.
     #
-    # Creates a private method that handles parameter value resolution,
-    # type coercion, validation, and error handling with caching.
-    #
-    # @param parameter [Parameter] The parameter to define method for
+    # @param parameter [Parameter] The parameter to define the method for
     # @return [void]
+    # @raise [CoercionError] If parameter value cannot be coerced to the expected type
+    # @raise [ValidationError] If parameter value fails validation
+    #
+    # @example Define parameter method (internal use)
+    #   define_attribute(param) # Defines a private method on the task class
     def define_attribute(parameter)
       klass.send(:define_method, parameter.method_name) do
-        @parameters_cache ||= {}
-        return @parameters_cache[parameter.method_name] if @parameters_cache.key?(parameter.method_name)
-
-        begin
-          parameter_value = ParameterValue.new(self, parameter).call
-        rescue CoercionError, ValidationError => e
-          parameter.errors.add(parameter.method_name, e.message)
-          errors.merge!(parameter.errors.to_hash)
-        ensure
-          @parameters_cache[parameter.method_name] = parameter_value
+        @cmd_parameter_value_cache ||= {}
+
+        unless @cmd_parameter_value_cache.key?(parameter.method_name)
+          begin
+            parameter_value = ParameterEvaluator.call(self, parameter)
+          rescue CoercionError, ValidationError => e
+            parameter.errors.add(parameter.method_name, e.message)
+            errors.merge!(parameter.errors.to_hash)
+          ensure
+            @cmd_parameter_value_cache[parameter.method_name] = parameter_value
+          end
         end
 
-        @parameters_cache[parameter.method_name]
+        @cmd_parameter_value_cache[parameter.method_name]
       end
 
       klass.send(:private, parameter.method_name)

data/lib/cmdx/parameter_evaluator.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Parameter evaluation system for task execution context.
+  #
+  # ParameterEvaluator processes parameter definitions by extracting values from
+  # task context sources, applying type coercions, performing validations, and
+  # handling optional parameters with default values. It ensures parameter values
+  # meet the requirements defined in parameter specifications before task execution.
+  class ParameterEvaluator
+
+    cmdx_attr_delegator :parent, :method_source, :name, :options, :required?, :optional?, :type,
+                        to: :parameter,
+                        private: true
+
+    # @return [CMDx::Task] The task instance being processed
+    attr_reader :task
+
+    # @return [CMDx::Parameter] The parameter definition being processed
+    attr_reader :parameter
+
+    # Creates a new parameter evaluator instance.
+    #
+    # @param task [CMDx::Task] the task instance containing parameter context
+    # @param parameter [CMDx::Parameter] the parameter definition to evaluate
+    #
+    # @example Create evaluator for a task parameter
+    #   evaluator = ParameterEvaluator.new(task, parameter)
+    def initialize(task, parameter)
+      @task      = task
+      @parameter = parameter
+    end
+
+    # Evaluates a parameter by creating a new evaluator instance and calling it.
+    #
+    # @param task [CMDx::Task] the task instance containing parameter context
+    # @param parameter [CMDx::Parameter] the parameter definition to evaluate
+    #
+    # @return [Object] the coerced and validated parameter value
+    #
+    # @raise [ValidationError] when parameter source is undefined or required parameter is missing
+    # @raise [CoercionError] when parameter value cannot be coerced to expected type
+    #
+    # @example Evaluate a parameter value
+    #   value = ParameterEvaluator.call(task, parameter)
+    def self.call(task, parameter)
+      new(task, parameter).call
+    end
+
+    # Evaluates the parameter by applying coercion and validation.
+    #
+    # @return [Object] the coerced and validated parameter value
+    #
+    # @raise [ValidationError] when parameter source is undefined or required parameter is missing
+    # @raise [CoercionError] when parameter value cannot be coerced to expected type
+    #
+    # @example Evaluate parameter with coercion and validation
+    #   evaluator = ParameterEvaluator.new(task, parameter)
+    #   value = evaluator.call
+    def call
+      coerce!.tap { validate! }
+    end
+
+    private
+
+    # Checks if the parameter source method is defined on the task.
+    #
+    # @return [Boolean] true if the source method exists, false otherwise
+    #
+    # @example Check if parameter source is defined
+    #   evaluator.send(:source_defined?) #=> true
+    def source_defined?
+      task.respond_to?(method_source, true) || task.cmdx_try(method_source)
+    end
+
+    # Retrieves the parameter source object from the task.
+    #
+    # @return [Object] the source object containing parameter values
+    #
+    # @raise [ValidationError] when the source method is not defined on the task
+    #
+    # @example Get parameter source
+    #   evaluator.send(:source) #=> #<Context:...>
+    def source
+      return @source if defined?(@source)
+
+      unless source_defined?
+        raise ValidationError, I18n.t(
+          "cmdx.parameters.undefined",
+          default: "delegates to undefined method #{method_source}",
+          source: method_source
+        )
+      end
+
+      @source = task.cmdx_try(method_source)
+    end
+
+    # Checks if the parameter value exists in the source object.
+    #
+    # @return [Boolean] true if the parameter value exists, false otherwise
+    #
+    # @example Check if parameter value exists
+    #   evaluator.send(:source_value?) #=> true
+    def source_value?
+      return false if source.nil?
+
+      source.cmdx_respond_to?(name, true)
+    end
+
+    # Checks if a required parameter value is missing from the source.
+    #
+    # @return [Boolean] true if required parameter is missing, false otherwise
+    #
+    # @example Check if required parameter is missing
+    #   evaluator.send(:source_value_required?) #=> false
+    def source_value_required?
+      return false if parent&.optional? && source.nil?
+
+      required? && !source_value?
+    end
+
+    # Extracts the parameter value from the source with default handling.
+    #
+    # @return [Object] the parameter value or default value
+    #
+    # @raise [ValidationError] when a required parameter is missing
+    #
+    # @example Get parameter value with default
+    #   evaluator.send(:value) #=> "default_value"
+    def value
+      return @value if defined?(@value)
+
+      if source_value_required?
+        raise ValidationError, I18n.t(
+          "cmdx.parameters.required",
+          default: "is a required parameter"
+        )
+      end
+
+      @value = source.cmdx_try(name)
+      return @value unless @value.nil? && options.key?(:default)
+
+      @value = task.cmdx_yield(options[:default])
+    end
+
+    # Applies type coercion to the parameter value.
+    #
+    # @return [Object] the coerced parameter value
+    #
+    # @raise [CoercionError] when value cannot be coerced to expected type
+    #
+    # @example Coerce parameter value
+    #   evaluator.send(:coerce!) #=> 42
+    def coerce!
+      types = Array(type)
+      tsize = types.size - 1
+
+      types.each_with_index do |key, i|
+        break CMDx.configuration.coercions.call(task, key, value, options)
+      rescue CoercionError => e
+        next if tsize != i
+
+        raise(e) if tsize.zero?
+
+        values = types.map(&:to_s).join(", ")
+        raise CoercionError, I18n.t(
+          "cmdx.coercions.into_any",
+          values:,
+          default: "could not coerce into one of: #{values}"
+        )
+      end
+    end
+
+    # Checks if validations should be skipped for optional missing arguments.
+    #
+    # @return [Boolean] true if validations should be skipped, false otherwise
+    #
+    # @example Check if validations should be skipped
+    #   evaluator.send(:skip_validations_due_to_optional_missing_argument?) #=> false
+    def skip_validations_due_to_optional_missing_argument?
+      optional? && value.nil? && !source.nil? && !source.cmdx_respond_to?(name, true)
+    end
+
+    # Checks if validator should be skipped due to conditional options.
+    #
+    # @param opts [Hash] the validator options
+    #
+    # @return [Boolean] true if validator should be skipped, false otherwise
+    #
+    # @example Check if validator should be skipped
+    #   evaluator.send(:skip_validator_due_to_conditional?, :presence) #=> false
+    def skip_validator_due_to_conditional?(opts)
+      opts.is_a?(Hash) && !task.cmdx_eval(opts)
+    end
+
+    # Checks if validator should be skipped due to allow_nil option.
+    #
+    # @param opts [Symbol] the validator options
+    #
+    # @return [Boolean] true if validator should be skipped, false otherwise
+    #
+    # @example Check if validator should be skipped for nil
+    #   evaluator.send(:skip_validator_due_to_allow_nil?, :presence) #=> true
+    def skip_validator_due_to_allow_nil?(opts)
+      opts.is_a?(Hash) && opts[:allow_nil] && value.nil?
+    end
+
+    # Applies all configured validations to the parameter value.
+    #
+    # @return [void]
+    #
+    # @raise [ValidationError] when parameter value fails validation
+    #
+    # @example Validate parameter value
+    #   evaluator.send(:validate!)
+    def validate!
+      return if skip_validations_due_to_optional_missing_argument?
+
+      types = CMDx.configuration.validators.registry.keys
+
+      options.slice(*types).each_key do |key|
+        opts = options[key]
+        next if skip_validator_due_to_allow_nil?(opts)
+        next if skip_validator_due_to_conditional?(opts)
+
+        CMDx.configuration.validators.call(task, key, value, opts)
+      end
+    end
+
+  end
+end