cmdx 1.0.1 → 1.1.1

data/lib/cmdx/callback_registry.rb

@@ -1,106 +1,113 @@
 # 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.
+    # @return [Hash] hash containing callback type keys and callback definition arrays
+    attr_reader :registry
+
+    # Initializes a new callback registry.
     #
-    # @param registry [CallbackRegistry, Hash, nil] Optional registry to copy from
+    # @param registry [Hash] initial registry hash with callback definitions
     #
-    # @example Initialize empty registry
-    #   registry = CallbackRegistry.new
+    # @return [CallbackRegistry] a new callback registry instance
     #
-    # @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
+    # @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

data/lib/cmdx/chain_inspector.rb

@@ -1,137 +1,44 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Chain inspection utility for generating comprehensive chain summaries.
+  # Provides formatted inspection and display functionality for chain execution results.
   #
-  # The ChainInspector module provides functionality to convert Chain instances
-  # into detailed, human-readable string representations. It creates formatted
-  # summaries that include chain metadata, all task results, and summary statistics
-  # with visual separators for easy debugging and monitoring.
-  #
-  # @example Basic chain inspection
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   chain = result.chain
-  #
-  #   ChainInspector.call(chain)
-  #   # => "
-  #   #   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
-  #   #   ================================================
-  #   #
-  #   #   {
-  #   #     class: "ProcessOrderTask",
-  #   #     type: "Task",
-  #   #     index: 0,
-  #   #     id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #     tags: [],
-  #   #     state: "complete",
-  #   #     status: "success",
-  #   #     outcome: "success",
-  #   #     metadata: {},
-  #   #     runtime: 0.5
-  #   #   }
-  #   #
-  #   #   ================================================
-  #   #   state: complete | status: success | outcome: success | runtime: 0.5
-  #   #   "
-  #
-  # @example Chain with multiple tasks
-  #   class ComplexTask < CMDx::Task
-  #     def call
-  #       SubTask1.call(context)
-  #       SubTask2.call(context)
-  #     end
-  #   end
-  #
-  #   result = ComplexTask.call
-  #   ChainInspector.call(result.chain)
-  #   # => Shows formatted output with all three task results and summary
-  #
-  # @example Failed chain inspection
-  #   # When a chain contains failed tasks, the summary reflects the failure state
-  #   ChainInspector.call(failed_chain)
-  #   # => Shows all task results with failure information and failed summary
-  #
-  # @see CMDx::Chain Chain execution context and result tracking
-  # @see CMDx::Result Individual result inspection via to_h
+  # ChainInspector creates human-readable string representations of execution chains,
+  # displaying chain metadata, individual task results, and execution summary information
+  # in a formatted layout. The inspector processes chain data to provide comprehensive
+  # debugging and monitoring output for task execution sequences.
   module ChainInspector
 
-    # Keys to display in the chain summary footer.
-    #
-    # These keys represent the most important chain-level information
-    # that should be displayed in the summary footer for quick reference.
     FOOTER_KEYS = %i[
       state status outcome runtime
     ].freeze
 
     module_function
 
-    # Converts a Chain instance to a comprehensive string representation.
+    # Formats a chain into a human-readable inspection string with headers, results, and summary.
     #
-    # Creates a formatted summary that includes:
-    # - Chain header with unique ID
-    # - Visual separator line
-    # - Pretty-printed hash representation of each result
-    # - Visual separator line
-    # - Summary footer with key chain statistics
+    # Creates a comprehensive string representation of the execution chain including
+    # a header with the chain ID, formatted individual task results, and a footer
+    # summary with key execution metadata. The output uses visual separators for
+    # clear section delineation and consistent formatting.
     #
-    # @param chain [CMDx::Chain] The chain instance to inspect
-    # @return [String] Formatted chain summary with task details and statistics
+    # @param chain [Chain] the execution chain to format and inspect
     #
-    # @example Single task chain
-    #   chain = SimpleTask.call.chain
-    #   ChainInspector.call(chain)
-    #   # => "
-    #   #   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
-    #   #   ================================================
-    #   #
-    #   #   {
-    #   #     class: "SimpleTask",
-    #   #     type: "Task",
-    #   #     index: 0,
-    #   #     state: "complete",
-    #   #     status: "success",
-    #   #     outcome: "success",
-    #   #     runtime: 0.1
-    #   #   }
-    #   #
-    #   #   ================================================
-    #   #   state: complete | status: success | outcome: success | runtime: 0.1
-    #   #   "
-    #
-    # @example Multi-task chain
-    #   class ParentTask < CMDx::Task
-    #     def call
-    #       ChildTask1.call(context)
-    #       ChildTask2.call(context)
-    #     end
-    #   end
-    #
-    #   chain = ParentTask.call.chain
-    #   ChainInspector.call(chain)
-    #   # => "
-    #   #   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
-    #   #   ================================================
-    #   #
-    #   #   { class: "ParentTask", index: 0, state: "complete", status: "success", ... }
-    #   #   { class: "ChildTask1", index: 1, state: "complete", status: "success", ... }
-    #   #   { class: "ChildTask2", index: 2, state: "complete", status: "success", ... }
-    #   #
-    #   #   ================================================
-    #   #   state: complete | status: success | outcome: success | runtime: 0.5
-    #   #   "
+    # @return [String] formatted multi-line string representation of the chain execution
     #
-    # @example Failed chain inspection
-    #   failed_chain = FailingTask.call.chain
-    #   ChainInspector.call(failed_chain)
-    #   # => "
-    #   #   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
-    #   #   ================================================
+    # @example Format a simple chain
+    #   chain = MyWorkflow.call(user_id: 123)
+    #   output = ChainInspector.call(chain.chain)
+    #   puts output
+    #   # =>
+    #   # chain: abc123-def456-789
+    #   # ===============================
     #   #
-    #   #   { class: "FailingTask", state: "interrupted", status: "failed", metadata: { reason: "Error" }, ... }
+    #   # {:task=>"MyTask", :state=>"complete", :status=>"success"}
+    #   # {:task=>"OtherTask", :state=>"complete", :status=>"success"}
     #   #
-    #   #   ================================================
-    #   #   state: interrupted | status: failed | outcome: failed | runtime: 0.1
-    #   #   "
+    #   # ===============================
+    #   # state: complete | status: success | outcome: good | runtime: 0.025
     def call(chain)
       header = "\nchain: #{chain.id}"
       footer = FOOTER_KEYS.map { |key| "#{key}: #{chain.send(key)}" }.join(" | ")