cmdx 1.0.1 → 1.1.1

data/lib/cmdx/parameter.rb

@@ -1,95 +1,70 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Parameter definition class for CMDx task parameter management.
+  # Parameter definition and management for task attribute configuration.
   #
-  # 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
+  # Parameter provides a flexible system for defining, validating, and managing
+  # task parameters with support for type coercion, nested parameter structures,
+  # validation rules, and dynamic attribute generation. Parameters can be defined
+  # as required or optional with various configuration options including custom
+  # naming, source specification, and child parameter definitions.
   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 specified configuration.
     #
-    # @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.)
+    # @param name [Symbol, String] the parameter name
+    # @param options [Hash] parameter configuration options
+    # @option options [Class] :klass the task class this parameter belongs to (required)
+    # @option options [Parameter] :parent the parent parameter for nested definitions
+    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option options [Boolean] :required whether the parameter is required for task execution
+    # @option options [Symbol] :source the source context for parameter resolution
+    # @option options [Symbol, String] :as custom method name for the parameter
+    # @option options [Hash] :validates validation rules to apply to the parameter
+    # @option options [Object] :default default value when parameter is not provided
+    # @param block [Proc] optional block for defining nested parameters
     #
-    # @yield Optional block for defining nested parameters
+    # @return [Parameter] a new parameter instance
     #
-    # @raise [KeyError] If :klass option is not provided
+    # @raise [KeyError] if the :klass option is not provided
     #
-    # @example Basic parameter creation
+    # @example Create a simple required parameter
     #   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 Create parameter with validation
+    #   Parameter.new(:email, klass: MyTask, type: :string, validates: { format: /@/ })
     #
-    # @example Nested parameter with block
-    #   Parameter.new(:address, klass: MyTask) do
-    #     required :street, :city
-    #     optional :apartment
+    # @example Create nested parameter with 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 +83,32 @@ module CMDx
 
     class << self
 
-      # Defines one or more optional parameters.
+      # Creates one or more optional parameter definitions.
       #
-      # Creates parameter definitions that are not required for task execution.
-      # Optional parameters return nil if not provided in the call arguments.
+      # @param names [Array<Symbol>] parameter names to define as optional
+      # @param options [Hash] parameter configuration options
+      # @option options [Class] :klass the task class this parameter belongs to
+      # @option options [Parameter] :parent the parent parameter for nested definitions
+      # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+      # @option options [Symbol] :source the source context for parameter resolution
+      # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+      # @option options [Hash] :validates validation rules to apply to the parameter
+      # @option options [Object] :default default value when parameter is not provided
+      # @param block [Proc] optional block for defining nested parameters
       #
-      # @param names [Array<Symbol>] Parameter names to define
-      # @param options [Hash] Parameter configuration options
-      # @yield Optional block for nested parameter definitions
+      # @return [Array<Parameter>] array of created optional parameter instances
       #
-      # @return [Array<Parameter>] Created parameter instances
-      # @raise [ArgumentError] If no parameter names provided or :as option used with multiple names
+      # @raise [ArgumentError] if no parameter names are provided
+      # @raise [ArgumentError] if :as option is used with multiple parameter names
       #
-      # @example Single optional parameter
-      #   Parameter.optional(:priority, type: :string, default: "normal")
+      # @example Define single optional parameter
+      #   Parameter.optional(:description, klass: MyTask, type: :string)
       #
-      # @example Multiple optional parameters
-      #   Parameter.optional(:width, :height, type: :integer, numeric: { min: 0 })
+      # @example Define multiple optional parameters
+      #   Parameter.optional(:name, :email, klass: MyTask, type: :string)
       #
-      # @example Optional parameter with validation
-      #   Parameter.optional(:email, type: :string, format: { with: /@/ })
+      # @example Define optional parameter with custom name
+      #   Parameter.optional(:user_id, klass: MyTask, type: :integer, as: :current_user_id)
       def optional(*names, **options, &)
         if names.none?
           raise ArgumentError, "no parameters given"
@@ -138,187 +119,190 @@ module CMDx
         names.filter_map { |n| new(n, **options, &) }
       end
 
-      # Defines one or more required parameters.
+      # Creates one or more required parameter definitions.
       #
-      # 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 as required
+      # @param options [Hash] parameter configuration options
+      # @option options [Class] :klass the task class this parameter belongs to
+      # @option options [Parameter] :parent the parent parameter for nested definitions
+      # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+      # @option options [Symbol] :source the source context for parameter resolution
+      # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+      # @option options [Hash] :validates validation rules to apply to the parameter
+      # @option options [Object] :default default value when parameter is not provided
+      # @param block [Proc] optional block for defining nested parameters
       #
-      # @param names [Array<Symbol>] Parameter names to define
-      # @param options [Hash] Parameter configuration options
-      # @yield Optional block for nested parameter definitions
+      # @return [Array<Parameter>] array of created required parameter instances
       #
-      # @return [Array<Parameter>] Created parameter instances
-      # @raise [ArgumentError] If no parameter names provided or :as option used with multiple names
+      # @raise [ArgumentError] if no parameter names are provided
+      # @raise [ArgumentError] if :as option is used with multiple parameter names
       #
-      # @example Single required parameter
-      #   Parameter.required(:user_id, type: :integer)
+      # @example Define single required parameter
+      #   Parameter.required(:user_id, klass: MyTask, type: :integer)
       #
-      # @example Multiple required parameters
-      #   Parameter.required(:first_name, :last_name, type: :string, presence: true)
+      # @example Define multiple required parameters
+      #   Parameter.required(:name, :email, klass: MyTask, type: :string)
       #
-      # @example Required parameter with complex validation
-      #   Parameter.required(:age, type: :integer, numeric: { within: 18..120 })
+      # @example Define required parameter with validation
+      #   Parameter.required(:email, klass: MyTask, type: :string, validates: { format: /@/ })
       def required(*names, **options, &)
         optional(*names, **options.merge(required: true), &)
       end
 
     end
 
-    # Defines nested optional parameters within this parameter.
-    #
-    # Creates child parameter definitions that inherit this parameter as their source.
-    # Child parameters are only validated if the parent parameter is provided.
+    # Defines optional child parameters for nested parameter structures.
     #
-    # @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 define as optional children
+    # @param options [Hash] parameter configuration options
+    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option options [Symbol] :source the source context for parameter resolution
+    # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+    # @option options [Hash] :validates validation rules to apply to the parameter
+    # @option options [Object] :default default value when parameter is not provided
+    # @param block [Proc] optional block for defining nested parameters
     #
-    # @return [Array<Parameter>] Created child parameter instances
+    # @return [Array<Parameter>] array of created optional child parameter instances
     #
-    # @example Nested optional parameters
-    #   address_param.optional(:apartment, :unit, type: :string)
+    # @raise [ArgumentError] if no parameter names are provided
+    # @raise [ArgumentError] if :as option is used with multiple parameter names
     #
-    # @example Nested parameter with validation
-    #   user_param.optional(:age, type: :integer, numeric: { min: 0 })
+    # @example Define optional child parameters
+    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash)
+    #   user_param.optional(:description, :bio, type: :string)
     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.
+    # Defines required child parameters for nested parameter structures.
     #
-    # Creates child parameter definitions that are required if the parent parameter
-    # is provided. Child parameters inherit this parameter as their source.
+    # @param names [Array<Symbol>] parameter names to define as required children
+    # @param options [Hash] parameter configuration options
+    # @option options [Symbol, Array<Symbol>] :type the parameter type(s) for coercion
+    # @option options [Symbol] :source the source context for parameter resolution
+    # @option options [Symbol, String] :as custom method name (only allowed for single parameter)
+    # @option options [Hash] :validates validation rules to apply to the parameter
+    # @option options [Object] :default default value when parameter is not provided
+    # @param block [Proc] optional block for defining nested parameters
     #
-    # @param names [Array<Symbol>] Child parameter names to define
-    # @param options [Hash] Parameter configuration options
-    # @yield Optional block for further nested parameter definitions
+    # @return [Array<Parameter>] array of created required child parameter instances
     #
-    # @return [Array<Parameter>] Created child parameter instances
+    # @raise [ArgumentError] if no parameter names are provided
+    # @raise [ArgumentError] if :as option is used with multiple parameter names
     #
-    # @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 Define required child parameters
+    #   user_param = Parameter.new(:user, klass: MyTask, type: :hash)
+    #   user_param.required(:name, :email, type: :string)
     def required(*names, **options, &)
       parameters = Parameter.required(*names, **options.merge(klass: @klass, parent: self), &)
       children.concat(parameters)
     end
 
-    # Checks if this parameter is required.
+    # Checks if the parameter is marked as required for task execution.
     #
-    # @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 = Parameter.new(:name, klass: MyTask, required: true)
+    #   param.required? #=> true
     def required?
       !!@required
     end
 
-    # Checks if this parameter is optional.
+    # Checks if the parameter is marked as optional for task execution.
     #
-    # @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 = Parameter.new(:description, klass: MyTask, required: false)
+    #   param.optional? #=> true
     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.
+    # Generates the method name that will be created on the task class for this parameter.
     #
-    # @return [Symbol] The generated method name
+    # @return [Symbol] the method name with any configured prefix, suffix, or custom naming
     #
-    # @example Default method name
-    #   Parameter.new(:user_id, klass: Task).method_name  # => :user_id
+    # @example Get method name for simple parameter
+    #   param = Parameter.new(:user_id, klass: MyTask)
+    #   param.method_name #=> :user_id
     #
-    # @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 with custom naming
+    #   param = Parameter.new(:user_id, klass: MyTask, as: :current_user_id)
+    #   param.method_name #=> :current_user_id
     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.
-    #
-    # @return [Symbol] The source method name
+    # Determines the source context for parameter resolution and method name generation.
     #
-    # @example Default source
-    #   Parameter.new(:user_id, klass: Task).method_source  # => :context
+    # @return [Symbol] the source identifier used for parameter resolution
     #
-    # @example Custom source
-    #   Parameter.new(:name, klass: Task, source: :user).method_source  # => :user
+    # @example Get method source for simple parameter
+    #   param = Parameter.new(:user_id, klass: MyTask)
+    #   param.method_source #=> :context
     #
-    # @example Inherited source from parent
-    #   child_param.method_source  # => parent parameter's method_name
+    # @example Get method source for nested parameter
+    #   parent = Parameter.new(:user, klass: MyTask)
+    #   child = Parameter.new(:name, klass: MyTask, parent: parent)
+    #   child.method_source #=> :user
     def method_source
       @method_source ||= options[:source] || parent&.method_name || :context
     end
 
-    # Converts the parameter to a hash representation.
+    # Converts the parameter to a hash representation for serialization.
     #
-    # @return [Hash] Serialized parameter data including configuration and children
+    # @return [Hash] hash containing all parameter metadata and configuration
     #
-    # @example
+    # @example Convert parameter to hash
+    #   param = Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
     #   param.to_h
-    #   # => {
-    #   #   source: :context,
-    #   #   name: :user_id,
-    #   #   type: :integer,
-    #   #   required: true,
-    #   #   options: { numeric: { min: 1 } },
-    #   #   children: []
-    #   # }
+    #   #=> { name: :user_id, type: :integer, required: true, ... }
     def to_h
       ParameterSerializer.call(self)
     end
 
-    # Converts the parameter to a string representation for inspection.
+    # Converts the parameter to a formatted string representation for inspection.
     #
-    # @return [String] Human-readable parameter description
+    # @return [String] human-readable string representation of the parameter
     #
-    # @example
+    # @example Convert parameter to string
+    #   param = Parameter.new(:user_id, klass: MyTask, type: :integer, required: true)
     #   param.to_s
-    #   # => "Parameter: name=user_id type=integer source=context required=true options={numeric: {min: 1}}"
+    #   #=> "Parameter: name=user_id type=integer required=true ..."
     def to_s
       ParameterInspector.call(to_h)
     end
 
     private
 
-    # Defines the accessor method on the task class for this parameter.
+    # Dynamically defines a method on the task class for parameter value access.
     #
-    # Creates a private method that handles parameter value resolution,
-    # type coercion, validation, and error handling with caching.
+    # @param parameter [Parameter] the parameter to create a method for
     #
-    # @param parameter [Parameter] The parameter to define method for
     # @return [void]
+    #
+    # @example Define parameter method on task class
+    #   # Creates a private method that evaluates and caches parameter values
+    #   # with automatic error handling for coercion and validation failures
     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)