cmdx 0.4.0 → 1.0.0

data/lib/cmdx/chain.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Thread-local chain that tracks task execution results within a correlation context.
+  #
+  # 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
+  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
+
+    # @!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
+
+    # Creates a new chain instance.
+    #
+    # @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.
+    #
+    # @example Create chain with default ID
+    #   chain = CMDx::Chain.new
+    #   chain.id  #=> "018c2b95-b764-7615-a924-cc5b910ed1e5"
+    #
+    # @example Create chain with custom ID
+    #   chain = CMDx::Chain.new(id: "user-session-123")
+    #   chain.id  #=> "user-session-123"
+    def initialize(attributes = {})
+      @id      = attributes[:id] || CMDx::Correlator.id || CMDx::Correlator.generate
+      @results = []
+    end
+
+    class << self
+
+      # Returns the current thread-local chain.
+      #
+      # @return [CMDx::Chain, nil] the chain for the current thread, or nil if none exists
+      #
+      # @example
+      #   CMDx::Chain.current  #=> nil (no chain set)
+      #
+      #   MyTask.call(data: "test")
+      #   CMDx::Chain.current  #=> #<CMDx::Chain:0x... @id="018c2b95...">
+      def current
+        Thread.current[THREAD_KEY]
+      end
+
+      # Sets the current thread-local chain.
+      #
+      # @param chain [CMDx::Chain, nil] the chain to set for the current thread
+      # @return [CMDx::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"
+      def current=(chain)
+        Thread.current[THREAD_KEY] = chain
+      end
+
+      # Clears the current thread-local chain.
+      #
+      # @return [nil]
+      #
+      # @example
+      #   CMDx::Chain.current  #=> #<CMDx::Chain:0x...>
+      #   CMDx::Chain.clear
+      #   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.
+      #
+      # 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 task result to add to the chain
+      # @return [CMDx::Chain] the chain containing the result
+      #
+      # @api private
+      def build(result)
+        raise TypeError, "must be a Result" unless result.is_a?(Result)
+
+        self.current ||= new
+        current.results << result
+        current
+      end
+
+    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.
+    #
+    # @return [Hash] Structured 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", ... }
+    #   #   ]
+    #   # }
+    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.
+    #
+    # @return [String] Formatted chain summary with task details
+    #
+    # @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
+    #   #   "
+    def to_s
+      ChainInspector.call(self)
+    end
+
+  end
+end

data/lib/cmdx/chain_inspector.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Chain inspection utility for generating comprehensive chain summaries.
+  #
+  # 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
+  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
+    #
+    # @param chain [CMDx::Chain] The chain instance to inspect
+    # @return [String] Formatted chain summary with task details and statistics
+    #
+    # @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
+    #   #   "
+    #
+    # @example Failed chain inspection
+    #   failed_chain = FailingTask.call.chain
+    #   ChainInspector.call(failed_chain)
+    #   # => "
+    #   #   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
+    #   #   ================================================
+    #   #
+    #   #   { class: "FailingTask", state: "interrupted", status: "failed", metadata: { reason: "Error" }, ... }
+    #   #
+    #   #   ================================================
+    #   #   state: interrupted | status: failed | outcome: failed | runtime: 0.1
+    #   #   "
+    def call(chain)
+      header = "\nchain: #{chain.id}"
+      footer = FOOTER_KEYS.map { |key| "#{key}: #{chain.send(key)}" }.join(" | ")
+      spacer = "=" * [header.size, footer.size].max
+
+      chain
+        .results
+        .map { |r| r.to_h.except(:chain_id).pretty_inspect }
+        .unshift(header, "#{spacer}\n")
+        .push(spacer, "#{footer}\n\n")
+        .join("\n")
+    end
+
+  end
+end

data/lib/cmdx/chain_serializer.rb

@@ -0,0 +1,175 @@
+# 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
+  module ChainSerializer
+
+    module_function
+
+    # Converts a Chain object to a hash representation.
+    #
+    # 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 [CMDx::Chain] The chain object to serialize
+    # @return [Hash] Structured hash representation of the chain and all 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
+    #
+    #   chain = ParentTask.call.chain
+    #   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: []
+    #   # }
+    def call(chain)
+      {
+        id: chain.id,
+        state: chain.state,
+        status: chain.status,
+        outcome: chain.outcome,
+        runtime: chain.runtime,
+        results: chain.results.map(&:to_h)
+      }
+    end
+
+  end
+end

data/lib/cmdx/coercions/array.rb

@@ -2,10 +2,47 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Array type.
+    #
+    # The Array coercion converts parameter values to Array objects,
+    # with special handling for JSON-formatted strings and general
+    # array conversion using Ruby's Array() method.
+    #
+    # @example Basic array coercion
+    #   class ProcessOrderTask < CMDx::Task
+    #     optional :tags, type: :array, default: []
+    #     optional :item_ids, type: :array
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::Array.call([1, 2, 3])      # => [1, 2, 3]
+    #   Coercions::Array.call("hello")        # => ["hello"]
+    #   Coercions::Array.call('["a","b"]')    # => ["a", "b"] (JSON)
+    #   Coercions::Array.call('[1,2,3]')      # => [1, 2, 3] (JSON)
+    #   Coercions::Array.call(nil)            # => []
+    #   Coercions::Array.call(42)             # => [42]
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module Array
 
       module_function
 
+      # Coerce a value to Array.
+      #
+      # If the value is a JSON-formatted string (starts with '['), it will
+      # be parsed as JSON. Otherwise, it uses Ruby's Array() method for
+      # general array conversion.
+      #
+      # @param value [Object] value to coerce to array
+      # @param _options [Hash] coercion options (unused)
+      # @return [Array] coerced array value
+      # @raise [JSON::ParserError] if JSON parsing fails
+      #
+      # @example
+      #   Coercions::Array.call("test")         # => ["test"]
+      #   Coercions::Array.call('["a","b"]')    # => ["a", "b"]
+      #   Coercions::Array.call([1, 2])         # => [1, 2]
       def call(value, _options = {})
         if value.is_a?(::String) && value.start_with?("[")
           JSON.parse(value)

data/lib/cmdx/coercions/big_decimal.rb

@@ -2,12 +2,45 @@
 
 module CMDx
   module Coercions
+    # Coerces values to BigDecimal type.
+    #
+    # The BigDecimal coercion converts parameter values to BigDecimal objects
+    # for high-precision decimal arithmetic. Supports configurable precision
+    # and handles various numeric input formats.
+    #
+    # @example Basic BigDecimal coercion
+    #   class ProcessOrderTask < CMDx::Task
+    #     required :total_amount, type: :big_decimal
+    #     optional :tax_rate, type: :big_decimal, precision: 4
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::BigDecimal.call("123.45")          # => #<BigDecimal:...,'0.12345E3',18(27)>
+    #   Coercions::BigDecimal.call(42)                # => #<BigDecimal:...,'0.42E2',9(18)>
+    #   Coercions::BigDecimal.call("0.333333", precision: 6)  # Custom precision
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module BigDecimal
 
+      # Default precision for BigDecimal calculations
+      # @return [Integer] default precision value
       DEFAULT_PRECISION = 14
 
       module_function
 
+      # Coerce a value to BigDecimal.
+      #
+      # @param value [Object] value to coerce to BigDecimal
+      # @param options [Hash] coercion options
+      # @option options [Integer] :precision decimal precision (default: 14)
+      # @return [BigDecimal] coerced BigDecimal value
+      # @raise [CoercionError] if coercion fails
+      #
+      # @example
+      #   Coercions::BigDecimal.call("123.45")                    # => BigDecimal with default precision
+      #   Coercions::BigDecimal.call("0.333", precision: 10)      # => BigDecimal with custom precision
+      #   Coercions::BigDecimal.call(42.5)                        # => BigDecimal from float
       def call(value, options = {})
         BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/boolean.rb

@@ -2,15 +2,55 @@
 
 module CMDx
   module Coercions
+    # Coerces values to Boolean type (true/false).
+    #
+    # The Boolean coercion converts parameter values to true or false
+    # based on string pattern matching for common boolean representations.
+    # It handles various textual representations of true and false values.
+    #
+    # @example Basic boolean coercion
+    #   class ProcessOrderTask < CMDx::Task
+    #     optional :send_email, type: :boolean, default: true
+    #     optional :is_urgent, type: :boolean, default: false
+    #   end
+    #
+    # @example Coercion behavior
+    #   Coercions::Boolean.call("true")     # => true
+    #   Coercions::Boolean.call("yes")      # => true
+    #   Coercions::Boolean.call("1")        # => true
+    #   Coercions::Boolean.call("false")    # => false
+    #   Coercions::Boolean.call("no")       # => false
+    #   Coercions::Boolean.call("0")        # => false
+    #   Coercions::Boolean.call("invalid")  # => raises CoercionError
+    #
+    # @see ParameterValue Parameter value coercion
+    # @see Parameter Parameter type definitions
     module Boolean
 
+      # Pattern matching false-like values (case insensitive)
+      # @return [Regexp] regex for falsey string values
       FALSEY = /^(false|f|no|n|0)$/i
+
+      # Pattern matching true-like values (case insensitive)
+      # @return [Regexp] regex for truthy string values
       TRUTHY = /^(true|t|yes|y|1)$/i
 
       module_function
 
+      # Coerce a value to Boolean.
+      #
+      # @param value [Object] value to coerce to boolean
+      # @param _options [Hash] coercion options (unused)
+      # @return [Boolean] coerced boolean value (true or false)
+      # @raise [CoercionError] if value cannot be coerced to boolean
+      #
+      # @example
+      #   Coercions::Boolean.call("yes")    # => true
+      #   Coercions::Boolean.call("False")  # => false
+      #   Coercions::Boolean.call("1")      # => true
+      #   Coercions::Boolean.call("0")      # => false
       def call(value, _options = {})
-        case value.to_s
+        case value.to_s.downcase
         when FALSEY then false
         when TRUTHY then true
         else