cmdx 0.5.0 → 1.0.0

data/lib/cmdx/task.rb

@@ -1,9 +1,109 @@
 # frozen_string_literal: true
 
 module CMDx
+  ##
+  # Task is the base class for all command objects in CMDx, providing a framework
+  # for encapsulating business logic with parameter validation, callbacks, and result tracking.
+  #
+  # Tasks follow a single-use pattern where each instance can only be executed once,
+  # after which it becomes frozen and immutable. This ensures predictable execution
+  # and prevents side effects from multiple calls.
+  #
+  # @example Basic task definition
+  #   class ProcessOrderTask < CMDx::Task
+  #     required :order_id, type: :integer
+  #     optional :notify_user, type: :boolean, default: true
+  #
+  #     def call
+  #       # Business logic here
+  #       context.order = Order.find(order_id)
+  #       skip!(reason: "Order already processed") if context.order.processed?
+  #
+  #       context.order.process!
+  #       NotificationService.call(order_id: order_id) if notify_user
+  #     end
+  #   end
+  #
+  # @example Task execution
+  #   result = ProcessOrderTask.call(order_id: 123, notify_user: false)
+  #   result.success? #=> true
+  #   result.context.order #=> <Order id: 123>
+  #
+  # @example Task chaining with Result objects
+  #   # First task extracts data
+  #   class ExtractDataTask < CMDx::Task
+  #     required :source_id, type: :integer
+  #
+  #     def call
+  #       context.extracted_data = DataSource.extract(source_id)
+  #       context.extraction_time = Time.now
+  #     end
+  #   end
+  #
+  #   # Second task processes the extracted data
+  #   class ProcessDataTask < CMDx::Task
+  #     def call
+  #       # Access data from previous task's context
+  #       fail!(reason: "No data to process") unless context.extracted_data
+  #
+  #       context.processed_data = DataProcessor.process(context.extracted_data)
+  #       context.processing_time = Time.now
+  #     end
+  #   end
+  #
+  #   # Chain tasks by passing Result objects
+  #   extraction_result = ExtractDataTask.call(source_id: 123)
+  #   processing_result = ProcessDataTask.call(extraction_result)
+  #
+  #   # Result object context is automatically extracted
+  #   processing_result.context.extracted_data #=> data from first task
+  #   processing_result.context.processed_data #=> data from second task
+  #
+  # @example Using callbacks
+  #   class ProcessOrderTask < CMDx::Task
+  #     before_validation :log_start
+  #     after_execution :cleanup_resources
+  #     on_success :send_confirmation
+  #     on_failure :alert_support, if: :critical_order?
+  #
+  #     def call
+  #       # Implementation
+  #     end
+  #
+  #     private
+  #
+  #     def critical_order?
+  #       context.order.value > 10_000
+  #     end
+  #   end
+  #
+  # == Task Chaining and Data Flow
+  #
+  # Tasks can be seamlessly chained by passing Result objects between them.
+  # This enables powerful workflows where the output of one task becomes the
+  # input for the next, maintaining data consistency and enabling complex
+  # business logic composition.
+  #
+  # Benefits of Result object chaining:
+  # - Automatic context extraction and data flow
+  # - Preserves all context data including custom attributes
+  # - Maintains execution chain relationships
+  # - Enables conditional task execution based on previous results
+  # - Simplifies error handling and rollback scenarios
+  #
+  # @see Result Result object for execution outcomes
+  # @see Context Context object for parameter access
+  # @see ParameterRegistry Parameter definition and validation
+  # @see Workflow Workflow for executing multiple tasks
+  # @since 1.0.0
   class Task
 
-    HOOKS = [
+    ##
+    # Available callback types for task lifecycle events.
+    # Callbacks are executed in a specific order during task execution.
+    #
+    # @return [Array<Symbol>] frozen array of available callback names
+    CALLBACKS = [
       :before_validation,
       :after_validation,
       :before_execution,
@@ -15,112 +115,370 @@ module CMDx
       *Result::STATES.map { |s| :"on_#{s}" }
     ].freeze
 
-    __cmdx_attr_setting :task_settings, default: -> { CMDx.configuration.to_h.merge(tags: []) }
-    __cmdx_attr_setting :cmd_parameters, default: -> { Parameters.new }
-    __cmdx_attr_setting :cmd_hooks, default: {}
-
-    __cmdx_attr_delegator :task_setting, :task_setting?, to: :class
-    __cmdx_attr_delegator :skip!, :fail!, :throw!, to: :result
-
-    attr_reader :id, :errors, :context, :result, :run
+    __cmdx_attr_setting :task_settings,
+                        default: -> { CMDx.configuration.to_h.merge(tags: []) }
+    __cmdx_attr_setting :cmd_middlewares,
+                        default: -> { MiddlewareRegistry.new(CMDx.configuration.middlewares) }
+    __cmdx_attr_setting :cmd_callbacks,
+                        default: -> { CallbackRegistry.new(CMDx.configuration.callbacks) }
+    __cmdx_attr_setting :cmd_parameters,
+                        default: -> { ParameterRegistry.new }
+
+    __cmdx_attr_delegator :cmd_middlewares, :cmd_callbacks, :cmd_parameters, :task_setting, :task_setting?,
+                          to: :class
+    __cmdx_attr_delegator :skip!, :fail!, :throw!,
+                          to: :result
+
+    ##
+    # @!attribute [r] context
+    #   @return [Context] parameter context for this task execution
+    attr_reader :context
+
+    ##
+    # @!attribute [r] errors
+    #   @return [Errors] collection of validation and execution errors
+    attr_reader :errors
+
+    ##
+    # @!attribute [r] id
+    #   @return [String] unique identifier for this task instance
+    attr_reader :id
+
+    ##
+    # @!attribute [r] result
+    #   @return [Result] execution result tracking state and status
+    attr_reader :result
+
+    ##
+    # @!attribute [r] chain
+    #   @return [Chain] execution chain containing this task and related executions
+    attr_reader :chain
+
+    # @return [Context] alias for context
     alias ctx context
-    alias res result
 
-    private_class_method :new
+    # @return [Result] alias for result
+    alias res result
 
+    ##
+    # Initializes a new task instance with the given context parameters.
+    #
+    # The context can be provided as a Hash, Context object, or Result object.
+    # When a Result object is passed, its context is automatically extracted,
+    # enabling seamless task chaining and data flow between tasks.
+    #
+    # @param context [Hash, Context, Result] parameters and configuration for task execution
+    # @example With hash parameters
+    #   task = ProcessOrderTask.new(order_id: 123, notify_user: true)
+    #
+    # @example With Result object (task chaining)
+    #   extraction_result = ExtractDataTask.call(source_id: 456)
+    #   processing_task = ProcessDataTask.new(extraction_result)
+    #   # Context from extraction_result is automatically extracted
     def initialize(context = {})
-      @id      = SecureRandom.uuid
-      @errors  = Errors.new
+      context  = context.context if context.respond_to?(:context)
+
       @context = Context.build(context)
-      @run = @context.run || begin
-        run = Run.new(@context.delete!(:run).to_h)
-        @context.instance_variable_set(:@run, run)
-      end
-      @run.results << @result = Result.new(self)
+      @errors  = Errors.new
+      @id      = CMDx::Correlator.generate
+      @result  = Result.new(self)
+      @chain   = Chain.build(@result)
     end
 
     class << self
 
-      HOOKS.each do |hook|
-        define_method(hook) do |*callables, **options, &block|
-          callables << block if block_given?
-          (cmd_hooks[hook] ||= []).push([callables, options]).uniq!
+      ##
+      # Dynamically defines callback methods for each available callback type.
+      # Each callback method accepts callables and options for conditional execution.
+      #
+      # @example Callback with method name
+      #   before_validation :validate_permissions
+      #
+      # @example Callback with proc
+      #   on_success -> { logger.info "Task completed successfully" }
+      #
+      # @example Callback with conditions
+      #   on_failure :alert_support, if: :critical_error?
+      #   after_execution :cleanup, unless: :skip_cleanup?
+      #
+      # @param callables [Array<Symbol, Proc, #call>] methods or callables to execute
+      # @param options [Hash] conditions for callback execution
+      # @option options [Symbol, Proc, #call] :if condition that must be truthy
+      # @option options [Symbol, Proc, #call] :unless condition that must be falsy
+      # @param block [Proc] block to execute as part of the callback
+      # @return [Array] updated callbacks array
+      CALLBACKS.each do |callback|
+        define_method(callback) do |*callables, **options, &block|
+          cmd_callbacks.register(callback, *callables, **options, &block)
         end
       end
 
+      ##
+      # Retrieves a task setting value, evaluating it if it's a callable.
+      #
+      # @param key [Symbol, String] setting key to retrieve
+      # @return [Object] the setting value
+      # @example
+      #   task_setting(:timeout) #=> 30
       def task_setting(key)
         __cmdx_yield(task_settings[key])
       end
 
+      ##
+      # Checks if a task setting exists.
+      #
+      # @param key [Symbol, String] setting key to check
+      # @return [Boolean] true if setting exists
       def task_setting?(key)
         task_settings.key?(key)
       end
 
+      ##
+      # Updates task settings with new options.
+      #
+      # @param options [Hash] settings to merge
+      # @return [Hash] updated settings
+      # @example
+      #   task_settings!(timeout: 60, retries: 3)
       def task_settings!(**options)
         task_settings.merge!(options)
       end
 
+      ##
+      # Adds middleware to the task execution stack.
+      #
+      # Middleware can wrap task execution to provide cross-cutting concerns
+      # like logging, authentication, caching, or error handling.
+      #
+      # @param middleware [Class, Object, Proc] middleware to add
+      # @param args [Array] arguments for middleware instantiation
+      # @param block [Proc] block for middleware instantiation
+      # @return [MiddlewareRegistry] updated middleware registry
+      # @example
+      #   use LoggingMiddleware
+      #   use AuthenticationMiddleware, "admin"
+      #   use CachingMiddleware.new(ttl: 300)
+      def use(middleware, ...)
+        cmd_middlewares.use(middleware, ...)
+      end
+
+      ##
+      # Registers callbacks for the task execution lifecycle.
+      #
+      # Callbacks can observe or modify task execution at specific lifecycle
+      # points like before validation, on success, after execution, etc.
+      #
+      # @param callback [Symbol] The callback type to register for
+      # @param callables [Array<Symbol, Proc, Callback, #call>] Methods, callables, or Callback instances to execute
+      # @param options [Hash] Conditions for callback execution
+      # @option options [Symbol, Proc, #call] :if condition that must be truthy
+      # @option options [Symbol, Proc, #call] :unless condition that must be falsy
+      # @param block [Proc] Block to execute as part of the callback
+      # @return [CallbackRegistry] updated callback registry
+      # @example
+      #   register :before_execution, LoggingCallback.new(:debug)
+      #   register :on_success, NotificationCallback.new([:email, :slack])
+      #   register :on_failure, :alert_admin, if: :critical?
+      def register(callback, ...)
+        cmd_callbacks.register(callback, ...)
+      end
+
+      ##
+      # Defines optional parameters for the task.
+      #
+      # @param attributes [Array<Symbol>] parameter names
+      # @param options [Hash] parameter options (type, default, validations, etc.)
+      # @param block [Proc] block for nested parameter definitions
+      # @return [ParameterRegistry] updated parameters collection
+      # @example
+      #   optional :timeout, type: :integer, default: 30
+      #   optional :options, type: :hash do
+      #     required :api_key, type: :string
+      #   end
       def optional(*attributes, **options, &)
         parameters = Parameter.optional(*attributes, **options.merge(klass: self), &)
         cmd_parameters.concat(parameters)
       end
 
+      ##
+      # Defines required parameters for the task.
+      #
+      # @param attributes [Array<Symbol>] parameter names
+      # @param options [Hash] parameter options (type, validations, etc.)
+      # @param block [Proc] block for nested parameter definitions
+      # @return [ParameterRegistry] updated parameters collection
+      # @example
+      #   required :user_id, type: :integer
+      #   required :profile, type: :hash do
+      #     required :name, type: :string
+      #     optional :age, type: :integer
+      #   end
       def required(*attributes, **options, &)
         parameters = Parameter.required(*attributes, **options.merge(klass: self), &)
         cmd_parameters.concat(parameters)
       end
 
+      ##
+      # Executes the task with the given parameters, returning a result object.
+      # This method handles all exceptions and ensures the task completes properly.
+      #
+      # Parameters can be provided as a Hash, Context object, or Result object.
+      # When a Result object is passed, its context is automatically extracted,
+      # enabling seamless task chaining.
+      #
+      # @param args [Array] arguments passed to task initialization
+      # @return [Result] execution result with state and status information
+      # @example With hash parameters
+      #   result = ProcessOrderTask.call(order_id: 123)
+      #   result.success? #=> true or false
+      #   result.context.order #=> processed order
+      #
+      # @example With Result object (task chaining)
+      #   extraction_result = ExtractDataTask.call(source_id: 456)
+      #   processing_result = ProcessDataTask.call(extraction_result)
+      #   # Context from extraction_result is automatically used
+      #   processing_result.context.source_id #=> 456
       def call(...)
-        instance = send(:new, ...)
-        instance.send(:execute_call)
+        instance = new(...)
+        instance.perform
         instance.result
       end
 
+      ##
+      # Executes the task with the given parameters, raising exceptions for failures.
+      # This method is useful in background jobs where retries are handled via exceptions.
+      #
+      # Parameters can be provided as a Hash, Context object, or Result object.
+      # When a Result object is passed, its context is automatically extracted,
+      # enabling seamless task chaining with exception propagation.
+      #
+      # @param args [Array] arguments passed to task initialization
+      # @return [Result] execution result if successful
+      # @raise [Fault] if task fails and task_halt includes the failure status
+      # @example With hash parameters
+      #   begin
+      #     result = ProcessOrderTask.call!(order_id: 123)
+      #   rescue CMDx::Failed => e
+      #     # Handle failure
+      #   end
+      #
+      # @example With Result object (task chaining)
+      #   begin
+      #     extraction_result = ExtractDataTask.call!(source_id: 456)
+      #     processing_result = ProcessDataTask.call!(extraction_result)
+      #   rescue CMDx::Failed => e
+      #     # Handle failure from either task
+      #   end
       def call!(...)
-        instance = send(:new, ...)
-        instance.send(:execute_call!)
+        instance = new(...)
+        instance.perform!
         instance.result
       end
 
     end
 
+    ##
+    # The main execution method that must be implemented by subclasses.
+    # This method contains the core business logic of the task.
+    #
+    # @abstract Subclasses must implement this method
+    # @return [void]
+    # @raise [UndefinedCallError] if not implemented in subclass
+    # @example
+    #   def call
+    #     context.user = User.find(user_id)
+    #     fail!(reason: "User not found") unless context.user
+    #
+    #     context.user.activate!
+    #     context.activation_date = Time.now
+    #   end
     def call
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end
 
+    ##
+    # Executes the task with full exception handling for the non-bang call method.
+    # Captures all exceptions and converts them to appropriate result states.
+    #
+    # @return [void]
+    def perform
+      return execute_call if cmd_middlewares.empty?
+
+      cmd_middlewares.call(self) { |task| task.send(:execute_call) }
+    end
+
+    ##
+    # Executes the task with exception propagation for the bang call method.
+    # Allows exceptions to bubble up for external handling.
+    #
+    # @return [void]
+    # @raise [Fault] if task fails and task_halt includes the failure status
+    def perform!
+      return execute_call! if cmd_middlewares.empty?
+
+      cmd_middlewares.call(self) { |task| task.send(:execute_call!) }
+    end
+
     private
 
+    ##
+    # Returns the logger instance for this task.
+    #
+    # @return [Logger] configured logger instance
+    # @api private
     def logger
       Logger.call(self)
     end
 
+    ##
+    # Executes before-call callbacks and validations.
+    # Sets up the execution context and validates parameters.
+    #
+    # @return [void]
+    # @api private
     def before_call
-      TaskHook.call(self, :before_execution)
+      cmd_callbacks.call(self, :before_execution)
 
       result.executing!
-      TaskHook.call(self, :on_executing)
+      cmd_callbacks.call(self, :on_executing)
 
-      TaskHook.call(self, :before_validation)
+      cmd_callbacks.call(self, :before_validation)
       ParameterValidator.call(self)
-      TaskHook.call(self, :after_validation)
+      cmd_callbacks.call(self, :after_validation)
     end
 
+    ##
+    # Executes after-call callbacks based on execution results.
+    # Handles state and status transitions with appropriate callbacks.
+    #
+    # @return [void]
+    # @api private
     def after_call
-      TaskHook.call(self, :"on_#{result.state}")
-      TaskHook.call(self, :on_executed) if result.executed?
+      cmd_callbacks.call(self, :"on_#{result.state}")
+      cmd_callbacks.call(self, :on_executed) if result.executed?
 
-      TaskHook.call(self, :"on_#{result.status}")
-      TaskHook.call(self, :on_good) if result.good?
-      TaskHook.call(self, :on_bad) if result.bad?
+      cmd_callbacks.call(self, :"on_#{result.status}")
+      cmd_callbacks.call(self, :on_good) if result.good?
+      cmd_callbacks.call(self, :on_bad) if result.bad?
 
-      TaskHook.call(self, :after_execution)
+      cmd_callbacks.call(self, :after_execution)
     end
 
+    ##
+    # Finalizes task execution by freezing the task and logging results.
+    #
+    # @return [void]
+    # @api private
     def terminate_call
       Immutator.call(self)
       ResultLogger.call(result)
     end
 
+    ##
+    # Executes the task directly without middleware for the non-bang call method.
+    #
+    # @return [void]
+    # @api private
     def execute_call
       result.runtime do
         before_call
@@ -139,15 +497,25 @@ module CMDx
       terminate_call
     end
 
+    ##
+    # Executes the task directly without middleware for the bang call method.
+    #
+    # @return [void]
+    # @api private
     def execute_call!
       result.runtime do
         before_call
         call
       rescue UndefinedCallError => e
+        Chain.clear
         raise(e)
       rescue Fault => e
         result.executed!
-        raise(e) if Array(task_setting(:task_halt)).include?(e.result.status)
+
+        if Array(task_setting(:task_halt)).include?(e.result.status)
+          Chain.clear
+          raise(e)
+        end
 
         after_call # HACK: treat as NO-OP
       else

data/lib/cmdx/task_serializer.rb

@@ -1,15 +1,87 @@
 # frozen_string_literal: true
 
 module CMDx
+  ##
+  # TaskSerializer converts task instances into hash representations for
+  # logging, debugging, and serialization purposes. It extracts key metadata
+  # about the task execution context and identification.
+  #
+  # The serialized format includes:
+  # - Execution index within the chain
+  # - Chain identifier for grouping related tasks
+  # - Task type (Task vs Workflow)
+  # - Class name for identification
+  # - Unique task instance ID
+  # - Associated tags for categorization
+  #
+  # @example Basic serialization
+  #   class ProcessOrderTask < CMDx::Task
+  #     task_settings!(tags: [:order, :payment])
+  #   end
+  #
+  #   task = ProcessOrderTask.call(order_id: 123)
+  #   TaskSerializer.call(task)
+  #   #=> {
+  #   #     index: 1,
+  #   #     chain_id: "abc123...",
+  #   #     type: "Task",
+  #   #     class: "ProcessOrderTask",
+  #   #     id: "def456...",
+  #   #     tags: [:order, :payment]
+  #   #   }
+  #
+  # @example Workflow serialization
+  #   class OrderProcessingWorkflow < CMDx::Workflow
+  #     task_settings!(tags: [:workflow, :orders])
+  #   end
+  #
+  #   workflow = OrderProcessingWorkflow.call(orders: [...])
+  #   TaskSerializer.call(workflow)
+  #   #=> {
+  #   #     index: 1,
+  #   #     chain_id: "abc123...",
+  #   #     type: "Workflow",
+  #   #     class: "OrderProcessingWorkflow",
+  #   #     id: "ghi789...",
+  #   #     tags: [:workflow, :orders]
+  #   #   }
+  #
+  # @see Task Task class for execution context
+  # @see Workflow Workflow class for multi-task execution
+  # @see Chain Chain class for execution grouping
+  # @since 1.0.0
   module TaskSerializer
 
     module_function
 
+    ##
+    # Serializes a task instance into a hash representation containing
+    # essential metadata for identification and tracking.
+    #
+    # @param task [Task, Workflow] the task instance to serialize
+    # @return [Hash] serialized task data with the following keys:
+    #   - :index [Integer] position within the execution chain
+    #   - :chain_id [String] identifier of the containing chain
+    #   - :type [String] "Task" or "Workflow" based on instance type
+    #   - :class [String] class name of the task
+    #   - :id [String] unique identifier for this task instance
+    #   - :tags [Array] array of tags associated with the task
+    #
+    # @example Serializing a task
+    #   task = MyTask.call(param: "value")
+    #   data = TaskSerializer.call(task)
+    #   data[:class] #=> "MyTask"
+    #   data[:type] #=> "Task"
+    #   data[:id] #=> "550e8400-e29b-41d4-a716-446655440000"
+    #
+    # @example Using serialized data for logging
+    #   task_data = TaskSerializer.call(task)
+    #   logger.info("Task executed", task_data)
     def call(task)
       {
         index: task.result.index,
-        run_id: task.run.id,
-        type: task.is_a?(Batch) ? "Batch" : "Task",
+        chain_id: task.chain.id,
+        type: task.is_a?(Workflow) ? "Workflow" : "Task",
         class: task.class.name,
         id: task.id,
         tags: task.task_setting(:tags)