cmdx 1.0.1 → 1.1.0

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

data/lib/cmdx/coercion_registry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry for managing type coercion definitions and execution within tasks.
+  #
+  # This registry handles the registration and execution of coercions that convert
+  # parameter values from one type to another, supporting both built-in types and
+  # custom coercion logic.
+  class CoercionRegistry
+
+    # The internal hash storing coercion definitions.
+    #
+    # @return [Hash] hash containing coercion type keys and coercion class/callable values
+    attr_reader :registry
+
+    # Initializes a new coercion registry with default type coercions.
+    #
+    # Sets up the registry with built-in coercions for standard Ruby types
+    # including primitives, numerics, dates, and collections.
+    #
+    # @return [CoercionRegistry] a new coercion registry instance
+    #
+    # @example Creating a new registry
+    #   registry = CoercionRegistry.new
+    #   registry.registry[:string] # => Coercions::String
+    def initialize
+      @registry = {
+        array: Coercions::Array,
+        big_decimal: Coercions::BigDecimal,
+        boolean: Coercions::Boolean,
+        complex: Coercions::Complex,
+        date: Coercions::Date,
+        datetime: Coercions::DateTime,
+        float: Coercions::Float,
+        hash: Coercions::Hash,
+        integer: Coercions::Integer,
+        rational: Coercions::Rational,
+        string: Coercions::String,
+        time: Coercions::Time,
+        virtual: Coercions::Virtual
+      }
+    end
+
+    # Registers a custom coercion for a specific type.
+    #
+    # @param type [Symbol] the type identifier for the coercion
+    # @param coercion [Object] the coercion callable (class, proc, symbol, or string)
+    #
+    # @return [CoercionRegistry] returns self for method chaining
+    #
+    # @example Registering a custom coercion class
+    #   registry.register(:uuid, UUIDCoercion)
+    #
+    # @example Registering a proc coercion
+    #   registry.register(:upcase, ->(value, options) { value.to_s.upcase })
+    #
+    # @example Chaining registrations
+    #   registry.register(:custom1, MyCoercion).register(:custom2, AnotherCoercion)
+    def register(type, coercion)
+      registry[type] = coercion
+      self
+    end
+
+    # Executes a coercion for the specified type and value.
+    #
+    # @param task [Task] the task instance executing the coercion
+    # @param type [Symbol] the coercion type to execute
+    # @param value [Object] the value to be coerced
+    # @param options [Hash] additional options for the coercion
+    #
+    # @return [Object] the coerced value
+    #
+    # @raise [UnknownCoercionError] when the coercion type is not registered
+    #
+    # @example Coercing a string to integer
+    #   registry.call(task, :integer, "42")
+    #   # => 42
+    #
+    # @example Coercing with options
+    #   registry.call(task, :array, "a,b,c", delimiter: ",")
+    #   # => ["a", "b", "c"]
+    def call(task, type, value, options = {})
+      raise UnknownCoercionError, "unknown coercion #{type}" unless registry.key?(type)
+
+      case coercion = registry[type]
+      when Symbol, String, Proc
+        task.cmdx_try(coercion, value, options)
+      else
+        coercion.call(value, options)
+      end
+    end
+
+  end
+end

data/lib/cmdx/coercions/array.rb

@@ -2,47 +2,29 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Array type.
+    # Coercion class for converting values to arrays.
     #
-    # 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
+    # This coercion handles conversion of various types to arrays, with special
+    # handling for JSON-formatted strings that start with "[".
+    class Array < Coercion
 
-      module_function
-
-      # Coerce a value to Array.
+      # Converts the given value to an array.
+      #
+      # @param value [Object] the value to convert to an array
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Array] the converted array value
       #
-      # 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.
+      # @raise [JSON::ParserError] if value is a JSON string that cannot be parsed
+      # @raise [TypeError] if the value cannot be converted to an array
       #
-      # @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 Converting a JSON string
+      #   Coercions::Array.call('["a", "b", "c"]') #=> ["a", "b", "c"]
       #
-      # @example
-      #   Coercions::Array.call("test")         # => ["test"]
-      #   Coercions::Array.call('["a","b"]')    # => ["a", "b"]
-      #   Coercions::Array.call([1, 2])         # => [1, 2]
+      # @example Converting other values
+      #   Coercions::Array.call("hello") #=> ["hello"]
+      #   Coercions::Array.call(123) #=> [123]
+      #   Coercions::Array.call(nil) #=> []
       def call(value, _options = {})
         if value.is_a?(::String) && value.start_with?("[")
           JSON.parse(value)

data/lib/cmdx/coercions/big_decimal.rb

@@ -2,45 +2,33 @@
 
 module CMDx
   module Coercions
-    # Coerces values to BigDecimal type.
+    # Coercion class for converting values to BigDecimal.
     #
-    # 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
+    # This coercion handles conversion of various types to BigDecimal with
+    # configurable precision. It provides precise decimal arithmetic capabilities
+    # for financial calculations and other use cases requiring exact decimal representation.
+    class BigDecimal < Coercion
 
-      # Default precision for BigDecimal calculations
-      # @return [Integer] default precision value
       DEFAULT_PRECISION = 14
 
-      module_function
-
-      # Coerce a value to BigDecimal.
+      # Converts the given value to a BigDecimal.
+      #
+      # @param value [Object] the value to convert to a BigDecimal
+      # @param options [Hash] optional configuration
+      # @option options [Integer] :precision the precision for the BigDecimal (defaults to 14)
+      #
+      # @return [BigDecimal] the converted BigDecimal value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a BigDecimal
+      #
+      # @example Converting a string
+      #   Coercions::BigDecimal.call('123.45') #=> #<BigDecimal:...,'0.12345E3',18(27)>
       #
-      # @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 Converting with custom precision
+      #   Coercions::BigDecimal.call('123.456789', precision: 10) #=> #<BigDecimal:...,'0.123456789E3',18(27)>
       #
-      # @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
+      # @example Converting an integer
+      #   Coercions::BigDecimal.call(100) #=> #<BigDecimal:...,'0.1E3',9(18)>
       def call(value, options = {})
         BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
       rescue ArgumentError, TypeError