cmdx 1.1.0 → 1.1.1

data/lib/cmdx/task.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Core task execution system for CMDx framework.
+  # Core task implementation providing executable units of work with parameter management.
   #
-  # Task provides the foundational functionality for executing business logic
-  # with parameter validation, middleware support, callback execution, and
-  # result tracking. Tasks encapsulate reusable business operations with
-  # comprehensive error handling, logging, and execution state management.
+  # Task is the fundamental building block of the CMDx framework, providing a structured
+  # approach to implementing business logic with built-in parameter validation, middleware
+  # support, callback handling, and comprehensive result tracking. Tasks encapsulate
+  # discrete units of work that can be chained together into workflows or executed
+  # independently with rich execution context and error handling.
   class Task
 
     cmdx_attr_setting :cmd_settings,
@@ -45,20 +46,28 @@ module CMDx
     # @return [Result] alias for result
     alias res result
 
-    # Creates a new task instance with the provided execution context.
+    # Creates a new task instance with the given execution context.
     #
-    # @param context [Hash, Context] execution context data or Context instance
+    # Initializes all internal state including context, errors, unique identifier,
+    # result tracking, and execution chain. The context parameter supports various
+    # input formats and will be normalized into a Context instance.
     #
-    # @return [Task] a new task instance ready for execution
+    # @param context [Hash, Context, Object] initial execution context and parameters
     #
-    # @example Create a task with hash context
+    # @return [Task] the newly created task instance
+    #
+    # @example Create task with hash context
     #   task = MyTask.new(user_id: 123, action: "process")
     #   task.context.user_id #=> 123
     #
-    # @example Create a task with existing context
-    #   existing_context = CMDx::Context.build(name: "John")
+    # @example Create task with existing context
+    #   existing_context = OtherTask.call(status: "active")
     #   task = MyTask.new(existing_context)
-    #   task.context.name #=> "John"
+    #   task.context.status #=> "active"
+    #
+    # @example Create task with empty context
+    #   task = MyTask.new
+    #   task.context #=> empty Context instance
     def initialize(context = {})
       context  = context.context if context.respond_to?(:context)
 
@@ -73,95 +82,138 @@ module CMDx
 
     class << self
 
-      # Registers callbacks for task execution lifecycle events.
-      #
-      # These methods are dynamically defined for each callback type and provide
-      # a clean DSL for registering callbacks that will be executed at specific
-      # points during task execution.
-      #
-      # @param callables [Array<Object>] callback objects to register (symbols, procs, classes)
-      # @param options [Hash] conditional execution options
-      # @param block [Proc] optional block to register as a callback
-      #
-      # @return [void]
-      #
-      # @example Register before_execution callback with symbol
-      #   MyTask.before_execution :setup_database
-      #
-      # @example Register before_execution callback with proc
-      #   MyTask.before_execution -> { puts "Starting task execution" }
-      #
-      # @example Register before_execution callback with class
-      #   MyTask.before_execution SetupCallback
-      #
-      # @example Register before_execution callback with block
-      #   MyTask.before_execution { |task| task.context.started_at = Time.now }
-      #
-      # @example Register on_success callback with conditional options
-      #   MyTask.on_success :send_notification, if: -> { Rails.env.production? }
-      #
-      # @example Register on_success callback with multiple callables
-      #   MyTask.on_success :log_success, :send_email, :update_metrics
       CallbackRegistry::TYPES.each do |callback|
+        # Registers a callback for the specified lifecycle event.
+        #
+        # This method is dynamically defined for each callback type supported by
+        # CallbackRegistry, allowing tasks to register callbacks for various
+        # execution lifecycle events.
+        #
+        # @param callables [Array<Object>] callback objects or procs to register
+        # @param options [Hash] options for callback registration
+        # @param block [Proc] optional block to use as callback
+        #
+        # @return [void]
+        #
+        # @example Register before_execution callback with symbol
+        #   class MyTask < CMDx::Task
+        #     before_execution :setup_database
+        #   end
+        #
+        # @example Register before_execution callback with proc
+        #   class MyTask < CMDx::Task
+        #     before_execution -> { puts "Starting task execution" }
+        #   end
+        #
+        # @example Register before_execution callback with class
+        #   class MyTask < CMDx::Task
+        #     before_execution SetupCallback
+        #   end
+        #
+        # @example Register before_execution callback with block
+        #   class MyTask < CMDx::Task
+        #     before_execution { |task| task.context.started_at = Time.now }
+        #   end
+        #
+        # @example Register on_success callback with conditional options
+        #   class MyTask < CMDx::Task
+        #     on_success :send_notification, if: -> { Rails.env.production? }
+        #   end
+        #
+        # @example Register on_success callback with multiple callables
+        #   class MyTask < CMDx::Task
+        #     on_success :log_success, :send_email, :update_metrics
+        #   end
         define_method(callback) do |*callables, **options, &block|
           cmd_callbacks.register(callback, *callables, **options, &block)
         end
       end
 
-      # Retrieves the value of a task setting.
+      # Retrieves a configuration setting value by key.
+      #
+      # Provides access to task-specific configuration settings that control
+      # various aspects of task execution including logging, halt conditions,
+      # and custom settings.
       #
-      # @param key [Symbol] the setting key to retrieve
+      # @param key [Symbol, String] the configuration setting key to retrieve
       #
-      # @return [Object] the setting value, processed through cmdx_yield
+      # @return [Object] the configuration value, or nil if key doesn't exist
       #
       # @example Get logger setting
-      #   MyTask.cmd_setting(:logger) #=> #<Logger:...>
+      #   MyTask.cmd_setting(:logger) #=> Logger instance
       #
-      # @example Get halt setting
-      #   MyTask.cmd_setting(:task_halt) #=> "failed"
+      # @example Get custom setting
+      #   MyTask.cmd_settings!(timeout: 30)
+      #   MyTask.cmd_setting(:timeout) #=> 30
       def cmd_setting(key)
         cmdx_yield(cmd_settings[key])
       end
 
-      # Checks if a task setting key exists.
+      # Checks if a configuration setting exists.
       #
-      # @param key [Symbol] the setting key to check
+      # @param key [Symbol, String] the configuration setting key to check
       #
-      # @return [Boolean] true if the setting exists, false otherwise
+      # @return [Boolean] true if the setting key exists, false otherwise
       #
-      # @example Check if setting exists
+      # @example Check for existing setting
       #   MyTask.cmd_setting?(:logger) #=> true
-      #   MyTask.cmd_setting?(:invalid) #=> false
+      #
+      # @example Check for non-existing setting
+      #   MyTask.cmd_setting?(:nonexistent) #=> false
       def cmd_setting?(key)
         cmd_settings.key?(key)
       end
 
-      # Updates task settings with new values.
+      # Updates task configuration settings with the provided options.
       #
-      # @param options [Hash] hash of setting keys and values to merge
+      # Merges the given options into the existing configuration settings,
+      # allowing tasks to customize their execution behavior.
       #
-      # @return [Hash] the updated task settings hash
+      # @param options [Hash] configuration options to merge
       #
-      # @example Update task settings
+      # @return [Hash] the updated settings hash
+      #
+      # @example Set custom timeout
+      #   MyTask.cmd_settings!(timeout: 60, retries: 3)
+      #
+      # @example Override halt condition
       #   MyTask.cmd_settings!(task_halt: ["failed", "error"])
-      #   MyTask.cmd_setting(:task_halt) #=> ["failed", "error"]
       def cmd_settings!(**options)
         cmd_settings.merge!(options)
       end
 
       # Registers middleware, callbacks, validators, or coercions with the task.
       #
-      # @param type [Symbol] the type of registration (:middleware, :callback, :validator, :coercion)
-      # @param object [Object] the object to register
-      # @param args [Array] additional arguments passed to the registration method
+      # Provides a unified interface for registering various types of task
+      # extensions that modify or enhance task execution behavior.
+      #
+      # @param type [Symbol] the type of extension to register (:middleware, :callback, :validator, :coercion)
+      # @param object [Object] the extension object to register
+      # @param args [Array] additional arguments for registration
       #
       # @return [void]
       #
+      # @raise [ArgumentError] if an unsupported type is provided
+      #
+      # @example Register coercion
+      #   class MyTask < CMDx::Task
+      #     use :coercion, TemperatureCoercion
+      #   end
+      #
+      # @example Register validator
+      #   class MyTask < CMDx::Task
+      #     use :validator, ZipcodeValidator, country: "US"
+      #   end
+      #
       # @example Register middleware
-      #   MyTask.use(:middleware, TimeoutMiddleware, timeout: 30)
+      #   class MyTask < CMDx::Task
+      #     use :middleware, CMDx::Middlewares::Timeout.new(seconds: 30)
+      #   end
       #
       # @example Register callback
-      #   MyTask.use(:callback, :before_execution, MyCallback)
+      #   class MyTask < CMDx::Task
+      #     use :callback, :before, LogCallback.new
+      #   end
       def use(type, object, ...)
         case type
         when :middleware
@@ -175,77 +227,120 @@ module CMDx
         end
       end
 
-      # Defines optional parameters for the task.
+      # Defines optional parameters for the task with validation and coercion.
+      #
+      # Creates parameter definitions that are not required for task execution
+      # but will be validated and coerced if provided. Supports nested parameter
+      # structures through block syntax.
       #
       # @param attributes [Array<Symbol>] parameter names to define as optional
       # @param options [Hash] parameter configuration options
+      # @option options [Symbol, Array<Symbol>] :type parameter type(s) for coercion
+      # @option options [Object] :default default value if parameter not provided
+      # @option options [Hash] :validates validation rules to apply
       # @param block [Proc] optional block for defining nested parameters
       #
-      # @return [void]
+      # @return [Array<Parameter>] the created parameter definitions
       #
-      # @example Define optional parameters
-      #   MyTask.optional :name, :email, type: :string
+      # @example Define simple optional parameters
+      #   class MyTask < CMDx::Task
+      #     optional :name, :email, type: :string
+      #     optional :age, type: :integer, default: 0
+      #   end
       #
       # @example Define optional parameter with validation
-      #   MyTask.optional :age, type: :integer, validate: { numeric: { greater_than: 0 } }
+      #   class MyTask < CMDx::Task
+      #     optional :score, type: :integer, validates: { numeric: { greater_than: 0 } }
+      #   end
+      #
+      # @example Define nested optional parameters
+      #   class MyTask < CMDx::Task
+      #     optional :user, type: :hash do
+      #       required :name, type: :string
+      #       optional :age, type: :integer
+      #     end
+      #   end
       def optional(*attributes, **options, &)
         parameters = Parameter.optional(*attributes, **options.merge(klass: self), &)
         cmd_parameters.registry.concat(parameters)
       end
 
-      # Defines required parameters for the task.
+      # Defines required parameters for the task with validation and coercion.
+      #
+      # Creates parameter definitions that must be provided for successful task
+      # execution. Missing required parameters will cause task validation to fail.
+      # Supports nested parameter structures through block syntax.
       #
       # @param attributes [Array<Symbol>] parameter names to define as required
       # @param options [Hash] parameter configuration options
+      # @option options [Symbol, Array<Symbol>] :type parameter type(s) for coercion
+      # @option options [Object] :default default value if parameter not provided
+      # @option options [Hash] :validates validation rules to apply
       # @param block [Proc] optional block for defining nested parameters
       #
-      # @return [void]
+      # @return [Array<Parameter>] the created parameter definitions
+      #
+      # @example Define simple required parameters
+      #   class MyTask < CMDx::Task
+      #     required :user_id, type: :integer
+      #     required :action, type: :string
+      #   end
       #
-      # @example Define required parameters
-      #   MyTask.required :user_id, :action, type: :string
+      # @example Define required parameter with validation
+      #   class MyTask < CMDx::Task
+      #     required :email, type: :string, validates: { format: /@/ }
+      #   end
       #
-      # @example Define required parameter with nested structure
-      #   MyTask.required :user, type: :hash do
-      #     required :name, type: :string
-      #     optional :email, type: :string
+      # @example Define nested required parameters
+      #   class MyTask < CMDx::Task
+      #     required :payment, type: :hash do
+      #       required :amount, type: :big_decimal
+      #       required :currency, type: :string
+      #       optional :description, type: :string
+      #     end
       #   end
       def required(*attributes, **options, &)
         parameters = Parameter.required(*attributes, **options.merge(klass: self), &)
         cmd_parameters.registry.concat(parameters)
       end
 
-      # Executes the task with fault tolerance and returns the result.
+      # Executes a task instance and returns the result without raising exceptions.
+      #
+      # Creates a new task instance with the provided context, processes it through
+      # the complete execution pipeline, and returns the result. This method will
+      # not raise exceptions for task failures but will capture them in the result.
       #
-      # @param args [Array] arguments passed to the task constructor
+      # @param args [Array] arguments passed to task constructor
       #
-      # @return [Result] the task execution result
+      # @return [Result] the execution result containing state, status, and metadata
       #
-      # @example Execute task with fault tolerance
-      #   result = MyTask.call(user_id: 123)
-      #   result.success? #=> true
-      #   result.context.user_id #=> 123
+      # @example Execute task
+      #   result = MyTask.call(user_id: 123, action: "process")
+      #   puts result.status #=> "success" or "failed" or "skipped"
       def call(...)
         instance = new(...)
         instance.process
         instance.result
       end
 
-      # Executes the task with strict fault handling and returns the result.
+      # Executes a task instance and returns the result, raising exceptions on failure.
       #
-      # @param args [Array] arguments passed to the task constructor
+      # Creates a new task instance with the provided context, processes it through
+      # the complete execution pipeline, and returns the result. This method will
+      # raise appropriate fault exceptions if the task fails or is skipped.
       #
-      # @return [Result] the task execution result
+      # @param args [Array] arguments passed to task constructor
       #
-      # @raise [Fault] if the task fails and task_halt setting includes the failure status
+      # @return [Result] the execution result containing state, status, and metadata
       #
-      # @example Execute task with strict fault handling
-      #   result = MyTask.call!(user_id: 123)
-      #   result.success? #=> true
+      # @raise [Failed] when task execution fails
+      # @raise [Skipped] when task execution is skipped
       #
-      # @example Handling fault on failure
+      # @example Execute task
       #   begin
-      #     MyTask.call!(invalid_data: true)
-      #   rescue CMDx::Fault => e
+      #     result = MyTask.call!(user_id: 123)
+      #     puts "Success: #{result.status}"
+      #   rescue CMDx::Failed => e
       #     puts "Task failed: #{e.message}"
       #   end
       def call!(...)
@@ -258,58 +353,84 @@ module CMDx
 
     # Abstract method that must be implemented by task subclasses.
     #
-    # This method contains the core business logic to be executed by the task.
-    # Subclasses must override this method to provide their specific implementation.
+    # This method contains the actual business logic for the task. Subclasses
+    # must override this method to provide their specific implementation.
+    # The method has access to the task's context, can modify it, and can
+    # use skip!, fail!, or throw! to control execution flow.
     #
     # @return [void]
     #
-    # @raise [UndefinedCallError] if not implemented by subclass
+    # @raise [UndefinedCallError] always raised in the base Task class
     #
     # @example Implement in a subclass
     #   class ProcessUserTask < CMDx::Task
+    #     required :user_id, type: :integer
+    #
     #     def call
-    #       # Business logic here
-    #       context.processed = true
+    #       user = User.find(context.user_id)
+    #       skip!(reason: "User already processed") if user.processed?
+    #
+    #       user.process!
+    #       context.processed_at = Time.now
     #     end
     #   end
     def call
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end
 
-    # Performs task execution with middleware support and fault tolerance.
+    # Executes the task through the middleware pipeline without raising exceptions.
+    #
+    # Processes the task by running it through all registered middleware and
+    # the TaskProcessor. This method captures exceptions and converts them
+    # into result states rather than propagating them.
     #
     # @return [void]
     #
-    # @example Task execution with middleware
-    #   task = MyTask.new(user_id: 123)
+    # @example Process a task instance
+    #   task = MyTask.new(data: "input")
     #   task.process
-    #   task.result.success? #=> true
+    #   puts task.result.status #=> "success", "failed", or "skipped"
     def process
       cmd_middlewares.call(self) { |task| TaskProcessor.call(task) }
     end
 
-    # Performs task execution with middleware support and strict fault handling.
+    # Executes the task through the middleware pipeline, raising exceptions on failure.
+    #
+    # Processes the task by running it through all registered middleware and
+    # the TaskProcessor. This method will raise appropriate fault exceptions
+    # if the task fails or is skipped.
     #
     # @return [void]
     #
-    # @raise [Fault] if task fails and task_halt setting includes the failure status
+    # @raise [Failed] when task execution fails
+    # @raise [Skipped] when task execution is skipped
     #
-    # @example Task execution with strict fault handling
-    #   task = MyTask.new(user_id: 123)
-    #   task.process!
-    #   task.result.success? #=> true
+    # @example Process a task instance with exception handling
+    #   task = RiskyTask.new(data: "input")
+    #   begin
+    #     task.process!
+    #     puts "Task completed successfully"
+    #   rescue CMDx::Failed => e
+    #     puts "Task failed: #{e.message}"
+    #   end
     def process!
       cmd_middlewares.call(self) { |task| TaskProcessor.call!(task) }
     end
 
-    # Creates a logger instance for this task.
+    # Creates a logger instance configured for this task.
     #
-    # @return [Logger] logger instance configured for this task
+    # Returns a logger instance that is pre-configured with the task's
+    # settings and context information for consistent logging throughout
+    # task execution.
     #
-    # @example Getting task logger
-    #   task = MyTask.new
-    #   logger = task.send(:logger)
-    #   logger.info("Task started")
+    # @return [Logger] configured logger instance for this task
+    #
+    # @example Log task execution
+    #   def call
+    #     logger.info "Starting user processing"
+    #     # ... task logic ...
+    #     logger.info "User processing completed"
+    #   end
     def logger
       Logger.call(self)
     end

data/lib/cmdx/task_deprecator.rb

@@ -1,52 +1,49 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Handles deprecation checking for CMDx tasks.
+  # Task deprecation system for CMDx tasks.
   #
-  # This module provides functionality to check if a task is marked as deprecated
-  # and raise appropriate errors when deprecated tasks are instantiated. It integrates
-  # with the task lifecycle to prevent usage of deprecated functionality.
+  # This module provides a centralized system for handling task deprecation
+  # warnings and errors. It supports multiple deprecation modes including
+  # raising exceptions, logging warnings, or issuing Ruby warnings based
+  # on task configuration settings.
   module TaskDeprecator
 
     module_function
 
-    # Checks deprecation status of a task and handles it according to the configured behavior.
-    #
-    # This method examines the task's deprecation setting and takes appropriate action:
-    # - :raise - raises DeprecationError to prevent task execution
-    # - :warn - issues Ruby deprecation warning
-    # - :log or true - logs deprecation warning
-    # - nil or false - allows task execution without warnings
-    #
-    # @param task [Task] the task instance to check for deprecation
+    # Processes task deprecation based on the task's deprecated setting.
     #
+    # @param task [CMDx::Task] the task instance to check for deprecation
     # @return [void]
+    # @raise [DeprecationError] when task's deprecated setting is :error
     #
-    # @raise [DeprecationError] when task is marked with deprecated: :raise
-    #
-    # @example Task with raise deprecation setting
+    # @example Handle task with raise deprecation
     #   class MyTask < CMDx::Task
-    #     cmd_settings! deprecated: :raise
+    #     cmd_setting!(deprecated: :error)
     #   end
-    #   CMDx::TaskDeprecator.call(MyTask.new) # raises DeprecationError
+    #   task = MyTask.new
+    #   TaskDeprecator.call(task) # raises DeprecationError
     #
-    # @example Task with a proc deprecation setting
+    # @example Handle task with log deprecation
     #   class MyTask < CMDx::Task
-    #     cmd_settings! deprecated: -> { Time.now.year > 2025 ? :raise : :log }
+    #     cmd_setting!(deprecated: :log)
     #   end
-    #   CMDx::TaskDeprecator.call(MyTask.new) # issues warnings
+    #   task = MyTask.new
+    #   TaskDeprecator.call(task) # logs warning via task.logger
     #
-    # @example Task with no deprecation setting
+    # @example Handle task with warn deprecation
     #   class MyTask < CMDx::Task
+    #     cmd_setting!(deprecated: :warning)
     #   end
-    #   CMDx::TaskDeprecator.call(MyTask.new) # no action taken
+    #   task = MyTask.new
+    #   TaskDeprecator.call(task) # issues Ruby warning
     def call(task)
       case task.cmd_setting(:deprecated)
-      when :raise
+      when :error
         raise(DeprecationError, "#{task.class.name} usage prohibited")
       when :log, true
         task.logger.warn { "DEPRECATED: migrate to replacement or discontinue use" }
-      when :warn
+      when :warning
         warn("[#{task.class.name}] DEPRECATED: migrate to replacement or discontinue use", category: :deprecated)
       end
     end