cmdx 1.0.0 → 1.1.0

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 execution chains.
   #
-  # 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
+  # This module formats chain execution information into a human-readable string
+  # representation, including the chain ID, individual task results, and summary
+  # information about the chain's final state.
   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.
-    #
-    # 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
+    # Formats a chain into a human-readable inspection string.
     #
-    # @param chain [CMDx::Chain] The chain instance to inspect
-    # @return [String] Formatted chain summary with task details and statistics
+    # Creates a formatted display showing the chain ID, individual task results,
+    # and summary footer with execution state information. The output includes
+    # visual separators and structured formatting for easy reading.
     #
-    # @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
-    #   #   "
+    # @param chain [CMDx::Chain] the chain object to inspect
     #
-    # @example Multi-task chain
-    #   class ParentTask < CMDx::Task
-    #     def call
-    #       ChildTask1.call(context)
-    #       ChildTask2.call(context)
-    #     end
-    #   end
+    # @return [String] formatted multi-line string representation of the chain
     #
-    #   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
-    #   #   "
+    # @raise [NoMethodError] if chain doesn't respond to required methods (id, results, state, status, outcome, runtime)
     #
-    # @example Failed chain inspection
-    #   failed_chain = FailingTask.call.chain
-    #   ChainInspector.call(failed_chain)
-    #   # => "
-    #   #   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
-    #   #   ================================================
+    # @example Inspect a simple chain
+    #   chain = CMDx::Chain.new(id: "abc123")
+    #   result = CMDx::Result.new(task)
+    #   chain.results << result
+    #   puts CMDx::ChainInspector.call(chain)
+    #   # Output:
+    #   # chain: abc123
+    #   # ===================
     #   #
-    #   #   { class: "FailingTask", state: "interrupted", status: "failed", metadata: { reason: "Error" }, ... }
+    #   # {:state=>"complete", :status=>"success", ...}
     #   #
-    #   #   ================================================
-    #   #   state: interrupted | status: failed | outcome: failed | runtime: 0.1
-    #   #   "
+    #   # ===================
+    #   # state: complete | status: success | outcome: success | runtime: 0.001
     def call(chain)
       header = "\nchain: #{chain.id}"
       footer = FOOTER_KEYS.map { |key| "#{key}: #{chain.send(key)}" }.join(" | ")

data/lib/cmdx/chain_serializer.rb

@@ -1,164 +1,33 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Chain serialization utility for converting Chain objects to hash representations.
-  #
-  # The ChainSerializer module provides functionality to serialize Chain instances
-  # into structured hash representations suitable for inspection, logging,
-  # debugging, and data interchange. It creates comprehensive data structures
-  # that include chain metadata and all associated task results.
-  #
-  # @example Basic chain serialization
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   chain = result.chain
-  #
-  #   ChainSerializer.call(chain)
-  #   # => {
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   state: "complete",
-  #   #   status: "success",
-  #   #   outcome: "success",
-  #   #   runtime: 0.5,
-  #   #   results: [
-  #   #     {
-  #   #       class: "ProcessOrderTask",
-  #   #       type: "Task",
-  #   #       index: 0,
-  #   #       id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #       chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #       tags: [],
-  #   #       state: "complete",
-  #   #       status: "success",
-  #   #       outcome: "success",
-  #   #       metadata: {},
-  #   #       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
-  #   chain = result.chain
-  #
-  #   ChainSerializer.call(chain)
-  #   # => {
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   state: "complete",
-  #   #   status: "success",
-  #   #   outcome: "success",
-  #   #   runtime: 1.2,
-  #   #   results: [
-  #   #     { class: "ComplexTask", index: 0, state: "complete", status: "success", ... },
-  #   #     { class: "SubTask1", index: 1, state: "complete", status: "success", ... },
-  #   #     { class: "SubTask2", index: 2, state: "complete", status: "success", ... }
-  #   #   ]
-  #   # }
-  #
-  # @example Failed chain serialization
-  #   failed_result = FailingTask.call
-  #   failed_chain = failed_result.chain
-  #
-  #   ChainSerializer.call(failed_chain)
-  #   # => {
-  #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-  #   #   state: "interrupted",
-  #   #   status: "failed",
-  #   #   outcome: "failed",
-  #   #   runtime: 0.1,
-  #   #   results: [
-  #   #     {
-  #   #       class: "FailingTask",
-  #   #       state: "interrupted",
-  #   #       status: "failed",
-  #   #       outcome: "failed",
-  #   #       metadata: { reason: "Something went wrong" },
-  #   #       runtime: 0.1,
-  #   #       ...
-  #   #     }
-  #   #   ]
-  #   # }
-  #
-  # @see CMDx::Chain Chain execution context and result tracking
-  # @see CMDx::ResultSerializer Individual result serialization
-  # @see CMDx::ChainInspector Human-readable chain formatting
+  # Serializes Chain objects into hash representations for external consumption.
+  # Provides a consistent interface for converting chain execution data into
+  # structured format suitable for logging, API responses, or persistence.
   module ChainSerializer
 
     module_function
 
-    # Converts a Chain object to a hash representation.
+    # Converts a chain object into a hash representation containing execution metadata.
+    # Extracts key chain attributes and serializes all contained results for complete
+    # execution state capture.
     #
-    # Serializes a Chain instance into a structured hash containing chain metadata
-    # and all associated task results. The chain-level data is derived from the
-    # first result in the collection, while all individual results are included
-    # in their full serialized form.
+    # @param chain [Chain] the chain instance to serialize
     #
-    # @param chain [CMDx::Chain] The chain object to serialize
-    # @return [Hash] Structured hash representation of the chain and all results
+    # @return [Hash] hash containing chain metadata and serialized results
     #
-    # @example Simple chain serialization
-    #   chain = SimpleTask.call.chain
-    #   ChainSerializer.call(chain)
-    #   # => {
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "complete",
-    #   #   status: "success",
-    #   #   outcome: "success",
-    #   #   runtime: 0.1,
-    #   #   results: [
-    #   #     {
-    #   #       class: "SimpleTask",
-    #   #       type: "Task",
-    #   #       index: 0,
-    #   #       id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #       chain_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #       tags: [],
-    #   #       state: "complete",
-    #   #       status: "success",
-    #   #       outcome: "success",
-    #   #       metadata: {},
-    #   #       runtime: 0.1
-    #   #     }
-    #   #   ]
-    #   # }
-    #
-    # @example Multi-task chain serialization
-    #   class ParentTask < CMDx::Task
-    #     def call
-    #       ChildTask.call(context)
-    #     end
-    #   end
+    # @raise [NoMethodError] if chain doesn't respond to required methods
     #
-    #   chain = ParentTask.call.chain
+    # @example Serializing a workflow chain
+    #   chain = UserWorkflow.call(user_id: 123)
     #   ChainSerializer.call(chain)
     #   # => {
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "complete",      # From first result (ParentTask)
-    #   #   status: "success",      # From first result (ParentTask)
-    #   #   outcome: "success",     # From first result (ParentTask)
-    #   #   runtime: 0.5,          # From first result (ParentTask)
-    #   #   results: [
-    #   #     { class: "ParentTask", index: 0, ... },
-    #   #     { class: "ChildTask", index: 1, ... }
-    #   #   ]
-    #   # }
-    #
-    # @example Empty chain serialization
-    #   empty_chain = Chain.new
-    #   ChainSerializer.call(empty_chain)
-    #   # => {
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: nil,
-    #   #   status: nil,
-    #   #   outcome: nil,
-    #   #   runtime: nil,
-    #   #   results: []
+    #   #   id: "abc123",
+    #   #   state: :complete,
+    #   #   status: :success,
+    #   #   outcome: :good,
+    #   #   runtime: 0.045,
+    #   #   results: [...]
     #   # }
     def call(chain)
       {

data/lib/cmdx/coercion.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Base class for implementing type coercion functionality in parameter processing.
+  #
+  # Coercions are used to convert parameter values from one type to another,
+  # supporting both built-in types and custom coercion logic. All coercion
+  # implementations must inherit from this class and implement the abstract call method.
+  class Coercion
+
+    # Executes a coercion by creating a new instance and calling it.
+    #
+    # @param value [Object] the value to be coerced
+    # @param options [Hash] additional options for the coercion
+    #
+    # @return [Object] the coerced value
+    #
+    # @raise [UndefinedCallError] when the coercion subclass doesn't implement call
+    #
+    # @example Execute a coercion on a value
+    #   IntegerCoercion.call("42")
+    #   # => 42
+    def self.call(value, options = {})
+      new.call(value, options)
+    end
+
+    # Abstract method that must be implemented by coercion subclasses.
+    #
+    # This method contains the actual coercion logic to convert the input
+    # value to the desired type. Subclasses must override this method to
+    # provide their specific coercion implementation.
+    #
+    # @param _value [Object] the value to be coerced
+    # @param _options [Hash] additional options for the coercion
+    #
+    # @return [Object] the coerced value
+    #
+    # @raise [UndefinedCallError] always raised in the base class
+    #
+    # @example Implement in a subclass
+    #   def call(value, options = {})
+    #     Integer(value)
+    #   end
+    def call(_value, _options = {})
+      raise UndefinedCallError, "call method not defined in #{self.class.name}"
+    end
+
+  end
+end