cmdx 1.1.2 → 1.5.0

data/lib/cmdx/task.rb

@@ -1,438 +1,266 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Core task implementation providing executable units of work with parameter 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.
+  # Represents a task that can be executed within the CMDx framework.
+  # Tasks define attributes, callbacks, and execution logic that can be
+  # chained together to form workflows.
   class Task
 
-    cmdx_attr_setting :cmd_settings,
-                      default: -> { CMDx.configuration.to_h.slice(:logger, :task_halt, :workflow_halt).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 }
+    extend Forwardable
 
-    cmdx_attr_delegator :cmd_middlewares, :cmd_callbacks, :cmd_parameters,
-                        :cmd_settings, :cmd_setting, :cmd_setting?,
-                        to: :class
-    cmdx_attr_delegator :skip!, :fail!, :throw!,
-                        to: :result
-
-    # @return [Context] parameter context for this task execution
-    attr_reader :context
-
-    # @return [Errors] collection of validation and execution errors
-    attr_reader :errors
-
-    # @return [String] unique identifier for this task instance
-    attr_reader :id
-
-    # @return [Result] execution result tracking state and status
-    attr_reader :result
-
-    # @return [Chain] execution chain containing this task and related executions
-    attr_reader :chain
-
-    # @return [Context] alias for context
+    attr_reader :attributes, :errors, :id, :context, :result, :chain
     alias ctx context
-
-    # @return [Result] alias for result
     alias res result
 
-    # Creates a new task instance with the given execution context.
-    #
-    # 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.
-    #
-    # @param context [Hash, Context, Object] initial execution context and parameters
+    def_delegators :result, :skip!, :fail!, :throw!
+
+    # @param context [Hash, Context] The initial context for the task
     #
-    # @return [Task] the newly created task instance
+    # @option context [Object] :* Any key-value pairs to initialize the context
     #
-    # @example Create task with hash context
-    #   task = MyTask.new(user_id: 123, action: "process")
-    #   task.context.user_id #=> 123
+    # @return [Task] A new task instance
     #
-    # @example Create task with existing context
-    #   existing_context = OtherTask.call(status: "active")
-    #   task = MyTask.new(existing_context)
-    #   task.context.status #=> "active"
+    # @raise [DeprecationError] If the task class is deprecated
     #
-    # @example Create task with empty context
-    #   task = MyTask.new
-    #   task.context #=> empty Context instance
+    # @example
+    #   task = MyTask.new(name: "example", priority: :high)
+    #   task = MyTask.new(Context.build(name: "example"))
     def initialize(context = {})
-      context  = context.context if context.respond_to?(:context)
+      Deprecator.restrict(self)
 
-      @context = Context.build(context)
-      @errors  = Errors.new
-      @id      = CMDx::Correlator.generate
-      @result  = Result.new(self)
-      @chain   = Chain.build(@result)
+      @attributes = {}
+      @errors = Errors.new
 
-      TaskDeprecator.call(self)
+      @id = Identifier.generate
+      @context = Context.build(context)
+      @result = Result.new(self)
+      @chain = Chain.build(@result)
     end
 
     class << self
 
-      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 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, String] the configuration setting key to retrieve
+      # @param options [Hash] Configuration options to merge with existing settings
+      # @option options [AttributeRegistry] :attributes Registry for task attributes
+      # @option options [Boolean] :deprecate Whether the task is deprecated
+      # @option options [Array<Symbol>] :tags Tags associated with the task
       #
-      # @return [Object] the configuration value, or nil if key doesn't exist
+      # @return [Hash] The merged settings hash
       #
-      # @example Get logger setting
-      #   MyTask.cmd_setting(:logger) #=> Logger instance
-      #
-      # @example Get custom setting
-      #   MyTask.cmd_settings!(timeout: 30)
-      #   MyTask.cmd_setting(:timeout) #=> 30
-      def cmd_setting(key)
-        cmdx_yield(cmd_settings[key])
-      end
+      # @example
+      #   class MyTask < Task
+      #     settings deprecate: true, tags: [:experimental]
+      #   end
+      def settings(**options)
+        @settings ||= begin
+          hash =
+            if superclass.respond_to?(:settings)
+              superclass.settings
+            else
+              CMDx.configuration.to_h.except(:logger)
+            end.transform_values(&:dup)
 
-      # Checks if a configuration setting exists.
-      #
-      # @param key [Symbol, String] the configuration setting key to check
-      #
-      # @return [Boolean] true if the setting key exists, false otherwise
-      #
-      # @example Check for existing setting
-      #   MyTask.cmd_setting?(:logger) #=> true
-      #
-      # @example Check for non-existing setting
-      #   MyTask.cmd_setting?(:nonexistent) #=> false
-      def cmd_setting?(key)
-        cmd_settings.key?(key)
+          hash[:attributes] ||= AttributeRegistry.new
+          hash[:deprecate] ||= false
+          hash[:tags] ||= []
+
+          hash.merge!(options)
+        end
       end
 
-      # Updates task configuration settings with the provided options.
+      # @param type [Symbol] The type of registry to register with
+      # @param object [Object] The object to register
+      # @param args [Array] Additional arguments for registration
       #
-      # Merges the given options into the existing configuration settings,
-      # allowing tasks to customize their execution behavior.
+      # @raise [RuntimeError] If the registry type is unknown
       #
-      # @param options [Hash] configuration options to merge
-      #
-      # @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"])
-      def cmd_settings!(**options)
-        cmd_settings.merge!(options)
+      # @example
+      #   register(:attribute, MyAttribute.new)
+      #   register(:callback, :before, -> { puts "before" })
+      def register(type, object, ...)
+        case type
+        when :attribute then settings[:attributes].register(object, ...)
+        when :callback then settings[:callbacks].register(object, ...)
+        when :coercion then settings[:coercions].register(object, ...)
+        when :middleware then settings[:middlewares].register(object, ...)
+        when :validator then settings[:validators].register(object, ...)
+        else raise "unknown registry type #{type.inspect}"
+        end
       end
 
-      # Registers middleware, callbacks, validators, or coercions with the task.
-      #
-      # 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
+      # @param type [Symbol] The type of registry to deregister from
+      # @param object [Object] The object to deregister
+      # @param args [Array] Additional arguments for deregistration
       #
-      # @example Register middleware
-      #   class MyTask < CMDx::Task
-      #     use :middleware, CMDx::Middlewares::Timeout.new(seconds: 30)
-      #   end
+      # @raise [RuntimeError] If the registry type is unknown
       #
-      # @example Register callback
-      #   class MyTask < CMDx::Task
-      #     use :callback, :before, LogCallback.new
-      #   end
-      def use(type, object, ...)
+      # @example
+      #   deregister(:attribute, :name)
+      #   deregister(:callback, :before, MyCallback)
+      def deregister(type, object, ...)
         case type
-        when :middleware
-          cmd_middlewares.register(object, ...)
-        when :callback
-          cmd_callbacks.register(type, object, ...)
-        when :validator
-          cmd_validators.register(type, object, ...)
-        when :coercion
-          cmd_coercions.register(type, object, ...)
+        when :attribute then settings[:attributes].deregister(object, ...)
+        when :callback then settings[:callbacks].deregister(object, ...)
+        when :coercion then settings[:coercions].deregister(object, ...)
+        when :middleware then settings[:middlewares].deregister(object, ...)
+        when :validator then settings[:validators].deregister(object, ...)
+        else raise "unknown registry type #{type.inspect}"
         end
       end
 
-      # 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 args [Array] Arguments to build the attribute with
       #
-      # @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 [Array<Parameter>] the created parameter definitions
-      #
-      # @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
-      #   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)
+      # @example
+      #   attributes :name, :email
+      #   attributes :age, type: Integer, default: 18
+      def attributes(...)
+        register(:attribute, Attribute.build(...))
       end
+      alias attribute attributes
 
-      # 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
+      # @param args [Array] Arguments to build the optional attribute with
       #
-      # @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 parameter with validation
-      #   class MyTask < CMDx::Task
-      #     required :email, type: :string, validates: { format: /@/ }
-      #   end
-      #
-      # @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)
+      # @example
+      #   optional :description, :notes
+      #   optional :priority, type: Symbol, default: :normal
+      def optional(...)
+        register(:attribute, Attribute.optional(...))
       end
 
-      # Executes a task instance and returns the result without raising exceptions.
+      # @param args [Array] Arguments to build the required attribute with
       #
-      # 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 task constructor
-      #
-      # @return [Result] the execution result containing state, status, and metadata
+      # @example
+      #   required :name, :email
+      #   required :age, type: Integer, min: 0
+      def required(...)
+        register(:attribute, Attribute.required(...))
+      end
+
+      # @param names [Array<Symbol>] Names of attributes to remove
       #
-      # @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
+      # @example
+      #   remove_attributes :old_field, :deprecated_field
+      def remove_attributes(*names)
+        deregister(:attribute, names)
       end
+      alias remove_attribute remove_attributes
 
-      # Executes a task instance and returns the result, raising exceptions on failure.
+      CallbackRegistry::TYPES.each do |callback|
+        # @param callables [Array] Callable objects to register as callbacks
+        # @param options [Hash] Options for the callback registration
+        # @option options [Symbol] :priority Priority of the callback
+        # @option options [Boolean] :async Whether the callback should run asynchronously
+        # @param block [Proc] Block to register as a callback
+        #
+        # @example
+        #   before { puts "before execution" }
+        #   after :cleanup, priority: :high
+        #   around ->(task) { task.logger.info("starting") }
+        define_method(callback) do |*callables, **options, &block|
+          register(:callback, callback, *callables, **options, &block)
+        end
+      end
+
+      # @param args [Array] Arguments to pass 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 execution result
       #
-      # @param args [Array] arguments passed to task constructor
+      # @example
+      #   result = MyTask.execute(name: "example")
+      #   if result.success?
+      #     puts "Task completed successfully"
+      #   end
+      def execute(...)
+        task = new(...)
+        task.execute(raise: false)
+        task.result
+      end
+
+      # @param args [Array] Arguments to pass to the task constructor
       #
-      # @return [Result] the execution result containing state, status, and metadata
+      # @return [Result] The execution result
       #
-      # @raise [Failed] when task execution fails
-      # @raise [Skipped] when task execution is skipped
+      # @raise [ExecutionError] If the task execution fails
       #
-      # @example Execute task
-      #   begin
-      #     result = MyTask.call!(user_id: 123)
-      #     puts "Success: #{result.status}"
-      #   rescue CMDx::Failed => e
-      #     puts "Task failed: #{e.message}"
-      #   end
-      def call!(...)
-        instance = new(...)
-        instance.process!
-        instance.result
+      # @example
+      #   result = MyTask.execute!(name: "example")
+      #   # Will raise an exception if execution fails
+      def execute!(...)
+        task = new(...)
+        task.execute(raise: true)
+        task.result
       end
 
     end
 
-    # Abstract method that must be implemented by task subclasses.
-    #
-    # 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.
+    # @param raise [Boolean] Whether to raise exceptions on failure
     #
-    # @return [void]
+    # @return [Result] The execution result
     #
-    # @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
-    #       user = User.find(context.user_id)
-    #       skip!(reason: "User already processed") if user.processed?
+    # @example
+    #   result = task.execute
+    #   result = task.execute(raise: true)
+    def execute(raise: false)
+      Worker.execute(self, raise:)
+    end
+
+    # @raise [UndefinedMethodError] Always raised as this method must be overridden
     #
-    #       user.process!
-    #       context.processed_at = Time.now
+    # @example
+    #   class MyTask < Task
+    #     def work
+    #       # Custom work logic here
+    #       puts "Performing work..."
     #     end
     #   end
-    def call
-      raise UndefinedCallError, "call method not defined in #{self.class.name}"
+    def work
+      raise UndefinedMethodError, "undefined method #{self.class.name}#work"
     end
 
-    # 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]
+    # @return [Logger] The logger instance for this task
     #
-    # @example Process a task instance
-    #   task = MyTask.new(data: "input")
-    #   task.process
-    #   puts task.result.status #=> "success", "failed", or "skipped"
-    def process
-      cmd_middlewares.call(self) { |task| TaskProcessor.call(task) }
+    # @example
+    #   logger.info "Starting task execution"
+    #   logger.error "Task failed", error: exception
+    def logger
+      @logger ||= begin
+        logger = self.class.settings[:logger] || CMDx.configuration.logger
+        logger.level = self.class.settings[:log_level] || logger.level
+        logger.formatter = self.class.settings[:log_formatter] || logger.formatter
+        logger
+      end
     end
 
-    # 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 [Hash] A hash representation of the task
     #
-    # @return [void]
+    # @option return [Integer] :index The result index
+    # @option return [String] :chain_id The chain identifier
+    # @option return [String] :type The task type ("Task" or "Workflow")
+    # @option return [Array<Symbol>] :tags The task tags
+    # @option return [String] :class The task class name
+    # @option return [String] :id The task identifier
     #
-    # @raise [Failed] when task execution fails
-    # @raise [Skipped] when task execution is skipped
-    #
-    # @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) }
+    # @example
+    #   task_hash = task.to_h
+    #   puts "Task type: #{task_hash[:type]}"
+    #   puts "Task tags: #{task_hash[:tags].join(', ')}"
+    def to_h
+      {
+        index: result.index,
+        chain_id: chain.id,
+        type: self.class.include?(Workflow) ? "Workflow" : "Task",
+        tags: self.class.settings[:tags],
+        class: self.class.name,
+        id:
+      }
     end
 
-    # Creates a 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.
+    # @return [String] A string representation of the task
     #
-    # @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)
+    # @example
+    #   puts task.to_s
+    #   # Output: "Task[MyTask] tags: [:important] id: abc123"
+    def to_s
+      Utils::Format.to_str(to_h)
     end
 
   end