cmdx 1.0.1 → 1.1.0

data/lib/cmdx/callback.rb

@@ -1,67 +1,47 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Base class for CMDx callbacks that provides lifecycle execution points.
+  # Base class for implementing callback functionality in task execution.
   #
-  # Callback components can wrap or observe task execution at specific lifecycle
-  # points like before validation, on success, after execution, etc.
-  # Each callback must implement the `call` method which receives the
-  # task instance and callback context.
-  #
-  # @example Basic callback implementation
-  #   class LoggingCallback < CMDx::Callback
-  #     def call(task, callback_type)
-  #       puts "Executing #{callback_type} callback for #{task.class.name}"
-  #       task.logger.info("Callback executed: #{callback_type}")
-  #     end
-  #   end
-  #
-  # @example Callback with initialization parameters
-  #   class NotificationCallback < CMDx::Callback
-  #     def initialize(channels)
-  #       @channels = channels
-  #     end
-  #
-  #     def call(task, callback_type)
-  #       return unless callback_type == :on_success
-  #
-  #       @channels.each do |channel|
-  #         NotificationService.send(channel, "Task #{task.class.name} completed")
-  #       end
-  #     end
-  #   end
-  #
-  # @example Conditional callback execution
-  #   class ErrorReportingCallback < CMDx::Callback
-  #     def call(task, callback_type)
-  #       return unless callback_type == :on_failure
-  #       return unless task.result.failed?
-  #
-  #       ErrorReporter.notify(
-  #         task.errors.full_messages.join(", "),
-  #         context: task.context.to_h
-  #       )
-  #     end
-  #   end
-  #
-  # @see CallbackRegistry Callback management
-  # @see Task Callback integration
-  # @since 1.0.0
+  # Callbacks are executed at specific points during task lifecycle to
+  # provide hooks for custom behavior, logging, validation, or cleanup.
+  # All callback implementations must inherit from this class and implement
+  # the abstract call method.
   class Callback
 
-    ##
-    # Executes the callback logic.
+    # Executes a callback by creating a new instance and calling it.
+    #
+    # @param task [Task] the task instance executing the callback
+    # @param type [Symbol] the callback type identifier
+    #
+    # @return [Object] the result of the callback execution
+    #
+    # @raise [UndefinedCallError] when the callback subclass doesn't implement call
+    #
+    # @example Execute a callback on a task
+    #   MyCallback.call(task, :before)
+    def self.call(task, type)
+      new.call(task, type)
+    end
+
+    # Abstract method that must be implemented by callback subclasses.
+    #
+    # This method contains the actual callback logic to be executed.
+    # Subclasses must override this method to provide their specific
+    # callback implementation.
+    #
+    # @param _task [Task] the task instance executing the callback
+    # @param _type [Symbol] the callback type identifier
+    #
+    # @return [Object] the result of the callback execution
     #
-    # This method must be implemented by subclasses to define the callback
-    # behavior. The method receives the task instance and the callback type
-    # being executed.
+    # @raise [UndefinedCallError] always raised in the base class
     #
-    # @param task [Task] the task instance being executed
-    # @param callback_type [Symbol] the type of callback being executed
-    # @return [void]
-    # @abstract Subclasses must implement this method
-    def call(_task, _callback_type)
+    # @example Implement in a subclass
+    #   def call(task, type)
+    #     puts "Executing #{type} callback for #{task.class.name}"
+    #   end
+    def call(_task, _type)
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end
 

data/lib/cmdx/callback_registry.rb

@@ -1,106 +1,115 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # The CallbackRegistry collection provides a lifecycle callback system that executes
-  # registered callbacks at specific points during task execution. Callbacks can be
-  # conditionally executed based on task state and support both method references
-  # and callable objects.
+  # Registry for managing callback definitions and execution within tasks.
   #
-  # The CallbackRegistry collection extends Hash to provide specialized functionality for
-  # managing collections of callback definitions within CMDx tasks. It handles
-  # callback registration, conditional execution, and inspection.
-  #
-  # @example Basic callback usage
-  #   callback_registry = CallbackRegistry.new
-  #   callback_registry.register(:before_validation, :check_permissions)
-  #   callback_registry.register(:on_success, :log_success, if: :important?)
-  #   callback_registry.register(:on_failure, proc { alert_admin }, unless: :test_env?)
-  #
-  #   callback_registry.call(task, :before_validation)
-  #
-  # @example Hash-like operations
-  #   callback_registry[:before_validation] = [[:check_permissions, {}]]
-  #   callback_registry.keys  # => [:before_validation]
-  #   callback_registry.empty?  # => false
-  #   callback_registry.each { |callback_name, callbacks| puts "#{callback_name}: #{callbacks}" }
-  #
-  # @see Callback Base callback execution class
-  # @see Task Task lifecycle callbacks
-  # @since 1.0.0
-  class CallbackRegistry < Hash
+  # This registry handles the registration and execution of callbacks at various
+  # points in the task lifecycle, including validation, execution, and outcome
+  # handling phases.
+  class CallbackRegistry
+
+    TYPES = [
+      :before_validation,
+      :after_validation,
+      :before_execution,
+      :after_execution,
+      :on_executed,
+      :on_good,
+      :on_bad,
+      *Result::STATUSES.map { |s| :"on_#{s}" },
+      *Result::STATES.map { |s| :"on_#{s}" }
+    ].freeze
 
-    ##
-    # Initializes a new CallbackRegistry.
+    # The internal hash storing callback definitions.
     #
-    # @param registry [CallbackRegistry, Hash, nil] Optional registry to copy from
+    # @return [Hash] hash containing callback type keys and callback definition arrays
+    attr_reader :registry
+
+    # Initializes a new callback registry.
     #
-    # @example Initialize empty registry
-    #   registry = CallbackRegistry.new
+    # @param registry [Hash] initial registry hash with callback definitions
     #
-    # @example Initialize with existing registry
-    #   global_callbacks = CallbackRegistry.new
-    #   task_callbacks = CallbackRegistry.new(global_callbacks)
-    def initialize(registry = nil)
-      super()
-
-      registry&.each do |callback_type, callback_definitions|
-        self[callback_type] = callback_definitions.dup
-      end
+    # @return [CallbackRegistry] a new callback registry instance
+    #
+    # @example Creating an empty registry
+    #   CallbackRegistry.new
+    #
+    # @example Creating a registry with initial callbacks
+    #   CallbackRegistry.new(before_execution: [[:my_callback, {}]])
+    def initialize(registry = {})
+      @registry = registry.to_h
     end
 
-    # Registers a callback for the given callback type.
+    # Registers one or more callbacks for a specific type.
     #
-    # @param callback [Symbol] The callback type (e.g., :before_validation, :on_success)
-    # @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 [CallbackRegistry] self for method chaining
+    # @param type [Symbol] the callback type to register
+    # @param callables [Array<Object>] callable objects to register
+    # @param options [Hash] options for conditional callback execution
+    # @param block [Proc] optional block to register as a callback
     #
-    # @example Register method callback
-    #   registry.register(:before_validation, :check_permissions)
+    # @return [CallbackRegistry] returns self for method chaining
     #
-    # @example Register conditional callback
-    #   registry.register(:on_failure, :alert_admin, if: :critical?)
+    # @example Registering a symbol callback
+    #   registry.register(:before_execution, :setup_database)
     #
-    # @example Register proc callback
-    #   registry.register(:on_success, proc { log_completion })
-    def register(callback, *callables, **options, &block)
+    # @example Registering a Proc callback
+    #   registry.register(:on_good, ->(task) { puts "Task completed: #{task.name}" })
+    #
+    # @example Registering a Callback class
+    #   registry.register(:after_validation, NotificationCallback)
+    #
+    # @example Registering multiple callbacks with options
+    #   registry.register(:on_good, :send_notification, :log_success, if: -> { Rails.env.production? })
+    #
+    # @example Registering a block callback
+    #   registry.register(:after_validation) { |task| puts "Validation complete" }
+    def register(type, *callables, **options, &block)
       callables << block if block_given?
-      (self[callback] ||= []).push([callables, options]).uniq!
+      (registry[type] ||= []).push([callables, options]).uniq!
       self
     end
 
-    # Executes all callbacks registered for a specific callback type on the given task.
-    # Each callback is evaluated for its conditions (if/unless) before execution.
+    # Executes all registered callbacks for a specific type.
+    #
+    # @param task [Task] the task instance to execute callbacks on
+    # @param type [Symbol] the callback type to execute
     #
-    # @param task [Task] The task instance to execute callbacks on
-    # @param callback [Symbol] The callback type to execute (e.g., :before_validation, :on_success)
     # @return [void]
     #
-    # @example Execute callbacks
+    # @raise [UnknownCallbackError] when the callback type is not recognized
+    #
+    # @example Executing before_validation callbacks
     #   registry.call(task, :before_validation)
     #
-    # @example Execute conditional callbacks
-    #   # Only executes if task.critical? returns true
-    #   registry.call(task, :on_failure) # where registry has on_failure :alert, if: :critical?
-    def call(task, callback)
-      return unless key?(callback)
+    # @example Executing outcome callbacks
+    #   registry.call(task, :on_good)
+    def call(task, type)
+      raise UnknownCallbackError, "unknown callback #{type}" unless TYPES.include?(type)
 
-      Array(self[callback]).each do |callables, options|
-        next unless task.__cmdx_eval(options)
+      Array(registry[type]).each do |callables, options|
+        next unless task.cmdx_eval(options)
 
-        Array(callables).each do |c|
-          if c.is_a?(Callback)
-            c.call(task, callback)
+        Array(callables).each do |callable|
+          case callable
+          when Symbol, String, Proc
+            task.cmdx_try(callable)
           else
-            task.__cmdx_try(c)
+            callable.call(task)
           end
         end
       end
     end
 
+    # Returns a hash representation of the registry.
+    #
+    # @return [Hash] a deep copy of the registry hash
+    #
+    # @example Getting registry contents
+    #   registry.to_h
+    #   # => { before_execution: [[:setup, {}]], on_good: [[:notify, { if: -> { true } }]] }
+    def to_h
+      registry.transform_values(&:dup)
+    end
+
   end
 end

data/lib/cmdx/chain.rb

@@ -1,79 +1,42 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Thread-local chain that tracks task execution results within a correlation context.
+  # Manages execution chains for task results with thread-local storage support.
   #
-  # A Chain represents a sequence of task executions that are logically related,
-  # typically within the same request or operation flow. It provides thread-local
-  # storage to ensure that tasks executing in the same thread share the same chain
-  # while maintaining isolation across different threads.
-  #
-  # @example Basic usage with automatic chain creation
-  #   # Chain is automatically created when first task runs
-  #   result1 = MyTask.call(data: "first")
-  #   result2 = MyTask.call(data: "second")
-  #
-  #   result1.chain.id == result2.chain.id  #=> true
-  #   result1.index                         #=> 0
-  #   result2.index                         #=> 1
-  #
-  # @example Using custom chain ID
-  #   chain = CMDx::Chain.new(id: "custom-correlation-123")
-  #   CMDx::Chain.current = chain
-  #
-  #   result = MyTask.call(data: "test")
-  #   result.chain.id  #=> "custom-correlation-123"
-  #
-  # @example Thread isolation
-  #   # Each thread gets its own chain
-  #   Thread.new do
-  #     result = MyTask.call(data: "thread1")
-  #     result.chain.id  #=> unique ID for this thread
-  #   end
-  #
-  #   Thread.new do
-  #     result = MyTask.call(data: "thread2")
-  #     result.chain.id  #=> different unique ID
-  #   end
-  #
-  # @example Temporary chain context
-  #   CMDx::Chain.use(id: "temp-correlation") do
-  #     result = MyTask.call(data: "test")
-  #     result.chain.id  #=> "temp-correlation"
-  #   end
-  #   # Original chain is restored after block
-  #
-  # @see CMDx::Correlator
-  # @since 1.0.0
+  # Chain provides a mechanism to track and correlate multiple task executions
+  # within a single logical operation. It maintains a collection of results
+  # and provides thread-local storage for tracking the current execution chain.
+  # The chain automatically delegates common methods to its results collection
+  # and the first result for convenient access to execution state.
   class Chain
 
-    # Thread-local storage key for the current chain
     THREAD_KEY = :cmdx_correlation_chain
 
-    __cmdx_attr_delegator :index, :first, :last, :size,
-                          to: :results
-    __cmdx_attr_delegator :state, :status, :outcome, :runtime,
-                          to: :first
+    cmdx_attr_delegator :index, :first, :last, :size,
+                        to: :results
+    cmdx_attr_delegator :state, :status, :outcome, :runtime,
+                        to: :first
 
-    # @!attribute [r] id
-    #   @return [String] the unique identifier for this chain
-    # @!attribute [r] results
-    #   @return [Array<CMDx::Result>] the collection of task results in this chain
-    attr_reader :id, :results
+    # @return [String] the unique identifier for this chain
+    attr_reader :id
 
-    # Creates a new chain instance.
+    # @return [Array<CMDx::Result>] the collection of task results in this chain
+    attr_reader :results
+
+    # Creates a new execution chain with optional attributes.
+    #
+    # @param attributes [Hash] optional attributes for chain initialization
+    # @option attributes [String] :id custom chain identifier, defaults to current correlation ID or generates new one
     #
-    # @param attributes [Hash] configuration options for the chain
-    # @option attributes [String] :id custom identifier for the chain.
-    #   If not provided, uses the current correlator ID or generates a new UUID.
+    # @return [Chain] the newly created chain instance
     #
-    # @example Create chain with default ID
+    # @example Create a chain with default ID
     #   chain = CMDx::Chain.new
-    #   chain.id  #=> "018c2b95-b764-7615-a924-cc5b910ed1e5"
+    #   chain.id #=> "generated-uuid"
     #
-    # @example Create chain with custom ID
-    #   chain = CMDx::Chain.new(id: "user-session-123")
-    #   chain.id  #=> "user-session-123"
+    # @example Create a chain with custom ID
+    #   chain = CMDx::Chain.new(id: "custom-123")
+    #   chain.id #=> "custom-123"
     def initialize(attributes = {})
       @id      = attributes[:id] || CMDx::Correlator.id || CMDx::Correlator.generate
       @results = []
@@ -81,53 +44,55 @@ module CMDx
 
     class << self
 
-      # Returns the current thread-local chain.
+      # Gets the current execution chain from thread-local storage.
       #
-      # @return [CMDx::Chain, nil] the chain for the current thread, or nil if none exists
+      # @return [Chain, nil] the current chain or nil if none is set
       #
-      # @example
-      #   CMDx::Chain.current  #=> nil (no chain set)
-      #
-      #   MyTask.call(data: "test")
-      #   CMDx::Chain.current  #=> #<CMDx::Chain:0x... @id="018c2b95...">
+      # @example Access current chain
+      #   chain = CMDx::Chain.current
+      #   chain.id if chain #=> "current-chain-id"
       def current
         Thread.current[THREAD_KEY]
       end
 
-      # Sets the current thread-local chain.
+      # Sets the current execution chain in thread-local storage.
+      #
+      # @param chain [Chain, nil] the chain to set as current
       #
-      # @param chain [CMDx::Chain, nil] the chain to set for the current thread
-      # @return [CMDx::Chain, nil] the chain that was set
+      # @return [Chain, nil] the chain that was set
       #
-      # @example
-      #   chain = CMDx::Chain.new(id: "custom-id")
-      #   CMDx::Chain.current = chain
-      #   CMDx::Chain.current.id  #=> "custom-id"
+      # @example Set current chain
+      #   new_chain = CMDx::Chain.new
+      #   CMDx::Chain.current = new_chain
+      #   CMDx::Chain.current.id #=> new_chain.id
       def current=(chain)
         Thread.current[THREAD_KEY] = chain
       end
 
-      # Clears the current thread-local chain.
+      # Clears the current execution chain from thread-local storage.
       #
-      # @return [nil]
+      # @return [nil] always returns nil
       #
-      # @example
-      #   CMDx::Chain.current  #=> #<CMDx::Chain:0x...>
+      # @example Clear current chain
       #   CMDx::Chain.clear
-      #   CMDx::Chain.current  #=> nil
+      #   CMDx::Chain.current #=> nil
       def clear
         Thread.current[THREAD_KEY] = nil
       end
 
-      # Adds a result to the current chain, creating a new chain if none exists.
+      # Builds or extends the current execution chain with a new result.
       #
-      # This method is typically called internally by the task execution framework
-      # and should not be used directly in application code.
+      # @param result [CMDx::Result] the result to add to the chain
       #
-      # @param result [CMDx::Result] the task result to add to the chain
-      # @return [CMDx::Chain] the chain containing the result
+      # @return [Chain] the current chain with the result added
       #
-      # @api private
+      # @raise [TypeError] if result is not a Result instance
+      #
+      # @example Build chain with result
+      #   task = MyTask.new
+      #   result = CMDx::Result.new(task)
+      #   chain = CMDx::Chain.build(result)
+      #   chain.results.size #=> 1
       def build(result)
         raise TypeError, "must be a Result" unless result.is_a?(Result)
 
@@ -138,50 +103,28 @@ module CMDx
 
     end
 
-    # Converts the chain to a hash representation.
-    #
-    # Serializes the chain and all its results into a structured hash
-    # suitable for logging, debugging, and data interchange.
+    # Converts the chain to a hash representation using the serializer.
     #
-    # @return [Hash] Structured hash representation of the chain
+    # @return [Hash] serialized hash representation of the chain
     #
-    # @example
-    #   chain.to_h
-    #   # => {
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "complete",
-    #   #   status: "success",
-    #   #   outcome: "success",
-    #   #   runtime: 0.5,
-    #   #   results: [
-    #   #     { class: "ProcessOrderTask", state: "complete", status: "success", ... },
-    #   #     { class: "SendEmailTask", state: "complete", status: "success", ... }
-    #   #   ]
-    #   # }
+    # @example Convert to hash
+    #   chain.to_h #=> { id: "abc123", results: [...], state: "complete" }
     def to_h
       ChainSerializer.call(self)
     end
     alias to_a to_h
 
-    # Converts the chain to a string representation for inspection.
-    #
-    # Creates a comprehensive, human-readable summary of the chain including
-    # all task results with formatted headers and footers.
+    # Converts the chain to a formatted string representation.
     #
-    # @return [String] Formatted chain summary with task details
+    # @return [String] formatted string representation of the chain
     #
-    # @example
-    #   chain.to_s
-    #   # => "
-    #   #   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
-    #   #   ================================================
-    #   #
-    #   #   ProcessOrderTask: index=0 state=complete status=success ...
-    #   #   SendEmailTask: index=1 state=complete status=success ...
-    #   #
-    #   #   ================================================
-    #   #   state: complete | status: success | outcome: success | runtime: 0.5
-    #   #   "
+    # @example Convert to string
+    #   puts chain.to_s
+    #   # chain: abc123
+    #   # ===================
+    #   # {...}
+    #   # ===================
+    #   # state: complete | status: success | outcome: success | runtime: 0.001
     def to_s
       ChainInspector.call(self)
     end