cmdx 1.1.2 → 1.5.0

data/lib/cmdx/chain.rb

@@ -1,100 +1,80 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Manages execution chains for task results with thread-local storage support.
-  #
-  # 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.
+  # Manages a collection of task execution results in a thread-safe manner.
+  # Chains provide a way to track related task executions and their outcomes
+  # within the same execution context.
   class Chain
 
-    THREAD_KEY = :cmdx_correlation_chain
+    extend Forwardable
 
-    cmdx_attr_delegator :index, :first, :last, :size,
-                        to: :results
-    cmdx_attr_delegator :state, :status, :outcome, :runtime,
-                        to: :first
+    THREAD_KEY = :cmdx_chain
 
-    # @return [String] the unique identifier for this chain
-    attr_reader :id
+    attr_reader :id, :results
 
-    # @return [Array<CMDx::Result>] the collection of task results in this chain
-    attr_reader :results
+    def_delegators :results, :index, :first, :last, :size
+    def_delegators :first, :state, :status, :outcome, :runtime
 
-    # Creates a new execution chain with optional attributes.
+    # Creates a new chain with a unique identifier and empty results collection.
     #
-    # @param attributes [Hash] optional attributes for chain initialization
-    # @option attributes [String] :id custom chain identifier, defaults to current correlation ID or generates new one
-    #
-    # @return [Chain] the newly created chain instance
-    #
-    # @example Create a chain with default ID
-    #   chain = CMDx::Chain.new
-    #   chain.id #=> "generated-uuid"
-    #
-    # @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
+    # @return [Chain] A new chain instance
+    def initialize
+      @id = Identifier.generate
       @results = []
     end
 
     class << self
 
-      # Gets the current execution chain from thread-local storage.
+      # Retrieves the current chain for the current thread.
       #
-      # @return [Chain, nil] the current chain or nil if none is set
+      # @return [Chain, nil] The current chain or nil if none exists
       #
-      # @example Access current chain
-      #   chain = CMDx::Chain.current
-      #   chain.id if chain #=> "current-chain-id"
+      # @example
+      #   chain = Chain.current
+      #   if chain
+      #     puts "Current chain: #{chain.id}"
+      #   end
       def current
         Thread.current[THREAD_KEY]
       end
 
-      # Sets the current execution chain in thread-local storage.
+      # Sets the current chain for the current thread.
       #
-      # @param chain [Chain, nil] the chain to set as current
+      # @param chain [Chain] The chain to set as current
       #
-      # @return [Chain, nil] the chain that was set
+      # @return [Chain] The set chain
       #
-      # @example Set current chain
-      #   new_chain = CMDx::Chain.new
-      #   CMDx::Chain.current = new_chain
-      #   CMDx::Chain.current.id #=> new_chain.id
+      # @example
+      #   Chain.current = my_chain
       def current=(chain)
         Thread.current[THREAD_KEY] = chain
       end
 
-      # Clears the current execution chain from thread-local storage.
+      # Clears the current chain for the current thread.
       #
-      # @return [nil] always returns nil
+      # @return [nil] Always returns nil
       #
-      # @example Clear current chain
-      #   CMDx::Chain.clear
-      #   CMDx::Chain.current #=> nil
+      # @example
+      #   Chain.clear
       def clear
         Thread.current[THREAD_KEY] = nil
       end
 
-      # Builds or extends the current execution chain with a new result.
+      # Builds or extends the current chain by adding a result.
+      # Creates a new chain if none exists, otherwise appends to the current one.
       #
-      # @param result [CMDx::Result] the result to add to the chain
+      # @param result [Result] The task execution result to add
       #
-      # @return [Chain] the current chain with the result added
+      # @return [Chain] The current chain (newly created or existing)
       #
-      # @raise [TypeError] if result is not a Result instance
+      # @raise [TypeError] If result is not a CMDx::Result instance
       #
-      # @example Build chain with result
-      #   task = MyTask.new
-      #   result = CMDx::Result.new(task)
-      #   chain = CMDx::Chain.build(result)
-      #   chain.results.size #=> 1
+      # @example
+      #   result = task.execute
+      #   chain = Chain.build(result)
+      #   puts "Chain size: #{chain.size}"
       def build(result)
-        raise TypeError, "must be a Result" unless result.is_a?(Result)
+        raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
         self.current ||= new
         current.results << result
@@ -103,30 +83,33 @@ module CMDx
 
     end
 
-    # Converts the chain to a hash representation using the serializer.
+    # Converts the chain to a hash representation.
+    #
+    # @return [Hash] Hash containing chain id and serialized results
+    #
+    # @option return [String] :id The chain identifier
     #
-    # @return [Hash] serialized hash representation of the chain
+    # @option return [Array<Hash>] :results Array of result hashes
     #
-    # @example Convert to hash
-    #   chain.to_h #=> { id: "abc123", results: [...], state: "complete" }
+    # @example
+    #   chain_hash = chain.to_h
+    #   puts chain_hash[:id]
+    #   puts chain_hash[:results].size
     def to_h
-      ChainSerializer.call(self)
+      {
+        id: id,
+        results: results.map(&:to_h)
+      }
     end
-    alias to_a to_h
 
-    # Converts the chain to a formatted string representation.
+    # Converts the chain to a string representation.
     #
-    # @return [String] formatted string representation of the chain
+    # @return [String] Formatted string representation of the chain
     #
-    # @example Convert to string
+    # @example
     #   puts chain.to_s
-    #   # chain: abc123
-    #   # ===================
-    #   # {...}
-    #   # ===================
-    #   # state: complete | status: success | outcome: success | runtime: 0.001
     def to_s
-      ChainInspector.call(self)
+      Utils::Format.to_str(to_h)
     end
 
   end

data/lib/cmdx/coercion_registry.rb

@@ -1,33 +1,24 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Registry for managing parameter type coercion functionality.
+  # Registry for managing type coercion handlers.
   #
-  # CoercionRegistry provides a centralized system for storing, accessing, and
-  # executing type coercions during task parameter processing. It maintains an
-  # internal registry of coercion type keys mapped to their corresponding coercion
-  # classes or callables, supporting both built-in framework coercions and custom
-  # user-defined coercions for flexible type conversion during task execution.
+  # Provides a centralized way to register, deregister, and execute type coercions
+  # for various data types including arrays, numbers, dates, and other primitives.
   class CoercionRegistry
 
-    # @return [Hash] hash containing coercion type keys and coercion class/callable values
     attr_reader :registry
+    alias to_h registry
 
-    # Creates a new coercion registry with built-in coercion types.
+    # Initialize a new coercion registry.
     #
-    # Initializes the registry with all standard framework coercions including
-    # primitive types (string, integer, float, boolean), date/time types,
-    # collection types (array, hash), numeric types (big_decimal, rational, complex),
-    # and the virtual coercion type for parameter definitions without type conversion.
+    # @param registry [Hash<Symbol, Class>, nil] optional initial registry hash
     #
-    # @return [CoercionRegistry] a new registry instance with built-in coercions
-    #
-    # @example Create a new coercion registry
+    # @example
     #   registry = CoercionRegistry.new
-    #   registry.registry.keys
-    #   #=> [:array, :big_decimal, :boolean, :complex, :date, :datetime, :float, :hash, :integer, :rational, :string, :time, :virtual]
-    def initialize
-      @registry = {
+    #   registry = CoercionRegistry.new(custom: CustomCoercion)
+    def initialize(registry = nil)
+      @registry = registry || {
         array: Coercions::Array,
         big_decimal: Coercions::BigDecimal,
         boolean: Coercions::Boolean,
@@ -39,74 +30,67 @@ module CMDx
         integer: Coercions::Integer,
         rational: Coercions::Rational,
         string: Coercions::String,
-        time: Coercions::Time,
-        virtual: Coercions::Virtual
+        time: Coercions::Time
       }
     end
 
-    # Registers a new coercion type in the registry.
-    #
-    # Adds or overwrites a coercion type mapping in the registry, allowing custom
-    # coercions to be used during task parameter processing. The coercion can be
-    # a class that responds to `call`, a callable object, or a symbol/string
-    # representing a method to invoke on the task instance.
+    # Create a duplicate of this registry.
     #
-    # @param type [Symbol] the coercion type identifier to register
-    # @param coercion [Class, Proc, Symbol, String] the coercion implementation
+    # @return [CoercionRegistry] a new instance with duplicated registry hash
     #
-    # @return [CoercionRegistry] self for method chaining
+    # @example
+    #   new_registry = registry.dup
+    def dup
+      self.class.new(registry.dup)
+    end
+
+    # Register a new coercion handler for a type.
     #
-    # @example Register a custom coercion class
-    #   registry.register(:temperature, TemperatureCoercion)
+    # @param name [Symbol, String] the type name to register
+    # @param coercion [Class] the coercion class to handle this type
     #
-    # @example Register a coercion proc
-    #   registry.register(:upcase, proc { |value, options| value.to_s.upcase })
+    # @return [CoercionRegistry] self for method chaining
     #
-    # @example Register a method symbol
-    #   registry.register(:custom_parse, :parse_custom_format)
-    def register(type, coercion)
-      registry[type] = coercion
+    # @example
+    #   registry.register(:custom_type, CustomCoercion)
+    #   registry.register("another_type", AnotherCoercion)
+    def register(name, coercion)
+      registry[name.to_sym] = coercion
       self
     end
 
-    # Executes a coercion by type on the provided value.
+    # Remove a coercion handler for a type.
     #
-    # Looks up and executes the coercion implementation for the specified type,
-    # applying it to the provided value with optional configuration. Handles
-    # different coercion implementation types including callable objects,
-    # method symbols/strings, and coercion classes.
+    # @param name [Symbol, String] the type name to deregister
     #
-    # @param task [CMDx::Task] the task instance for context when calling methods
-    # @param type [Symbol] the coercion type to execute
-    # @param value [Object] the value to be coerced
-    # @param options [Hash] additional options passed to the coercion
-    # @option options [Object] any any additional configuration for the coercion
+    # @return [CoercionRegistry] self for method chaining
     #
-    # @return [Object] the coerced value
+    # @example
+    #   registry.deregister(:custom_type)
+    #   registry.deregister("another_type")
+    def deregister(name)
+      registry.delete(name.to_sym)
+      self
+    end
+
+    # Coerce a value to the specified type using the registered handler.
     #
-    # @raise [UnknownCoercionError] when the specified coercion type is not registered
-    # @raise [CoercionError] when the coercion fails to convert the value
+    # @param type [Symbol] the type to coerce to
+    # @param task [Object] the task context for the coercion
+    # @param value [Object] the value to coerce
+    # @param options [Hash] additional options for the coercion
     #
-    # @example Execute a built-in coercion
-    #   registry.call(task, :integer, "123")
-    #   #=> 123
+    # @return [Object] the coerced value
     #
-    # @example Execute with options
-    #   registry.call(task, :date, "2024-01-15", format: "%Y-%m-%d")
-    #   #=> #<Date: 2024-01-15>
+    # @raise [TypeError] when the type is not registered
     #
-    # @example Handle unknown coercion type
-    #   registry.call(task, :unknown_type, "value")
-    #   #=> raises UnknownCoercionError
-    def call(task, type, value, options = {})
-      raise UnknownCoercionError, "unknown coercion #{type}" unless registry.key?(type)
+    # @example
+    #   result = registry.coerce(:integer, task, "42")
+    #   result = registry.coerce(:boolean, task, "true", strict: true)
+    def coerce(type, task, value, options = {})
+      raise TypeError, "unknown coercion type #{type.inspect}" unless registry.key?(type)
 
-      case coercion = registry[type]
-      when Symbol, String, Proc
-        task.cmdx_try(coercion, value, options)
-      else
-        coercion.call(value, options)
-      end
+      Utils::Call.invoke(task, registry[type], value, options)
     end
 
   end

data/lib/cmdx/coercions/array.rb

@@ -2,30 +2,31 @@
 
 module CMDx
   module Coercions
-    # Coercion class for converting values to arrays.
+    # Converts various input types to Array format
     #
-    # This coercion handles conversion of various types to arrays, with special
-    # handling for JSON-formatted strings that start with "[".
-    class Array < Coercion
+    # Handles conversion from strings that look like JSON arrays and other
+    # values that can be converted to arrays using Ruby's Array() method.
+    module 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)
+      extend self
+
+      # Converts a value to an Array
       #
-      # @return [Array] the converted array value
+      # @param value [Object] The value to convert to an array
+      # @param options [Hash] Optional configuration parameters (currently unused)
+      # @option options [Object] :unused Currently no options are used
       #
-      # @raise [JSON::ParserError] if value is a JSON string that cannot be parsed
-      # @raise [TypeError] if the value cannot be converted to an array
+      # @return [Array] The converted array value
       #
-      # @example Converting a JSON string
-      #   Coercions::Array.call('["a", "b", "c"]') #=> ["a", "b", "c"]
+      # @raise [JSON::ParserError] If the string value contains invalid JSON
       #
-      # @example Converting other values
-      #   Coercions::Array.call("hello") #=> ["hello"]
-      #   Coercions::Array.call(123) #=> [123]
-      #   Coercions::Array.call(nil) #=> []
-      def call(value, _options = {})
+      # @example Convert a JSON-like string to an array
+      #   Array.call("[1, 2, 3]") # => [1, 2, 3]
+      # @example Convert other values using Array()
+      #   Array.call("hello")     # => ["hello"]
+      #   Array.call(42)          # => [42]
+      #   Array.call(nil)         # => []
+      def call(value, options = {})
         if value.is_a?(::String) && value.start_with?("[")
           JSON.parse(value)
         else

data/lib/cmdx/coercions/big_decimal.rb

@@ -2,41 +2,37 @@
 
 module CMDx
   module Coercions
-    # Coercion class for converting values to BigDecimal.
+    # Converts various input types to BigDecimal format
     #
-    # 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
+    # Handles conversion from numeric strings, integers, floats, and other
+    # values that can be converted to BigDecimal using Ruby's BigDecimal() method.
+    module BigDecimal
+
+      extend self
 
       DEFAULT_PRECISION = 14
 
-      # 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
+      # Converts a value to a BigDecimal
       #
-      # @raise [CoercionError] if the value cannot be converted to a BigDecimal
+      # @param value [Object] The value to convert to BigDecimal
+      # @param options [Hash] Optional configuration parameters
+      # @option options [Integer] :precision The precision to use (defaults to DEFAULT_PRECISION)
       #
-      # @example Converting a string
-      #   Coercions::BigDecimal.call('123.45') #=> #<BigDecimal:...,'0.12345E3',18(27)>
+      # @return [BigDecimal] The converted BigDecimal value
       #
-      # @example Converting with custom precision
-      #   Coercions::BigDecimal.call('123.456789', precision: 10) #=> #<BigDecimal:...,'0.123456789E3',18(27)>
+      # @raise [CoercionError] If the value cannot be converted to BigDecimal
       #
-      # @example Converting an integer
-      #   Coercions::BigDecimal.call(100) #=> #<BigDecimal:...,'0.1E3',9(18)>
+      # @example Convert numeric strings to BigDecimal
+      #   BigDecimal.call("123.45")                   # => #<BigDecimal:7f8b8c0d8e0f '0.12345E3',9(18)>
+      #   BigDecimal.call("0.001", precision: 6)      # => #<BigDecimal:7f8b8c0d8e0f '0.1E-2',9(18)>
+      # @example Convert other numeric types
+      #   BigDecimal.call(42)                         # => #<BigDecimal:7f8b8c0d8e0f '0.42E2',9(18)>
+      #   BigDecimal.call(3.14159)                    # => #<BigDecimal:7f8b8c0d8e0f '0.314159E1',9(18)>
       def call(value, options = {})
         BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
       rescue ArgumentError, TypeError
-        raise CoercionError, I18n.t(
-          "cmdx.coercions.into_a",
-          type: "big decimal",
-          default: "could not coerce into a big decimal"
-        )
+        type = Locale.t("cmdx.types.big_decimal")
+        raise CoercionError, Locale.t("cmdx.coercions.into_a", type:)
       end
 
     end

data/lib/cmdx/coercions/boolean.rb

@@ -2,44 +2,45 @@
 
 module CMDx
   module Coercions
-    # Coercion class for converting values to booleans.
+    # Converts various input types to Boolean format
     #
-    # This coercion handles conversion of various string representations to
-    # boolean values, supporting common true/false variations like "yes/no",
-    # "1/0", and "t/f".
-    class Boolean < Coercion
+    # Handles conversion from strings, numbers, and other values to boolean
+    # using predefined truthy and falsey patterns.
+    module Boolean
+
+      extend self
 
       FALSEY = /^(false|f|no|n|0)$/i
       TRUTHY = /^(true|t|yes|y|1)$/i
 
-      # Converts the given value to a boolean.
-      #
-      # @param value [Object] the value to convert to a boolean
-      # @param _options [Hash] optional configuration (currently unused)
+      # Converts a value to a Boolean
       #
-      # @return [Boolean] the converted boolean value
+      # @param value [Object] The value to convert to boolean
+      # @param options [Hash] Optional configuration parameters (currently unused)
+      # @option options [Object] :unused Currently no options are used
       #
-      # @raise [CoercionError] if the value cannot be converted to a boolean
+      # @return [Boolean] The converted boolean value
       #
-      # @example Converting truthy values
-      #   Coercions::Boolean.call('true') #=> true
-      #   Coercions::Boolean.call('yes') #=> true
-      #   Coercions::Boolean.call('1') #=> true
+      # @raise [CoercionError] If the value cannot be converted to boolean
       #
-      # @example Converting falsey values
-      #   Coercions::Boolean.call('false') #=> false
-      #   Coercions::Boolean.call('no') #=> false
-      #   Coercions::Boolean.call('0') #=> false
-      def call(value, _options = {})
+      # @example Convert truthy strings to true
+      #   Boolean.call("true")   # => true
+      #   Boolean.call("yes")    # => true
+      #   Boolean.call("1")      # => true
+      # @example Convert falsey strings to false
+      #   Boolean.call("false")  # => false
+      #   Boolean.call("no")     # => false
+      #   Boolean.call("0")      # => false
+      # @example Handle case-insensitive input
+      #   Boolean.call("TRUE")   # => true
+      #   Boolean.call("False")  # => false
+      def call(value, options = {})
         case value.to_s.downcase
         when FALSEY then false
         when TRUTHY then true
         else
-          raise CoercionError, I18n.t(
-            "cmdx.coercions.into_a",
-            type: "boolean",
-            default: "could not coerce into a boolean"
-          )
+          type = Locale.t("cmdx.types.boolean")
+          raise CoercionError, Locale.t("cmdx.coercions.into_a", type:)
         end
       end
 

data/lib/cmdx/coercions/complex.rb

@@ -2,36 +2,35 @@
 
 module CMDx
   module Coercions
-    # Coercion class for converting values to complex numbers.
+    # Converts various input types to Complex number format
     #
-    # This coercion handles conversion of various types to complex numbers,
-    # including strings, integers, floats, and other numeric types.
-    class Complex < Coercion
+    # Handles conversion from numeric strings, integers, floats, and other
+    # values that can be converted to Complex using Ruby's Complex() method.
+    module Complex
 
-      # Converts the given value to a complex number.
-      #
-      # @param value [Object] the value to convert to a complex number
-      # @param _options [Hash] optional configuration (currently unused)
+      extend self
+
+      # Converts a value to a Complex number
       #
-      # @return [Complex] the converted complex number value
+      # @param value [Object] The value to convert to Complex
+      # @param options [Hash] Optional configuration parameters (currently unused)
       #
-      # @raise [CoercionError] if the value cannot be converted to a complex number
+      # @return [Complex] The converted Complex number value
       #
-      # @example Converting numeric values
-      #   Coercions::Complex.call(5) #=> (5+0i)
-      #   Coercions::Complex.call(3.14) #=> (3.14+0i)
+      # @raise [CoercionError] If the value cannot be converted to Complex
       #
-      # @example Converting string representations
-      #   Coercions::Complex.call("2+3i") #=> (2+3i)
-      #   Coercions::Complex.call("1-2i") #=> (1-2i)
-      def call(value, _options = {})
+      # @example Convert numeric strings to Complex
+      #   Complex.call("3+4i")                     # => (3+4i)
+      #   Complex.call("2.5")                      # => (2.5+0i)
+      # @example Convert other numeric types
+      #   Complex.call(5)                          # => (5+0i)
+      #   Complex.call(3.14)                       # => (3.14+0i)
+      #   Complex.call(Complex(1, 2))              # => (1+2i)
+      def call(value, options = {})
         Complex(value)
       rescue ArgumentError, TypeError
-        raise CoercionError, I18n.t(
-          "cmdx.coercions.into_a",
-          type: "complex",
-          default: "could not coerce into a complex"
-        )
+        type = Locale.t("cmdx.types.complex")
+        raise CoercionError, Locale.t("cmdx.coercions.into_a", type:)
       end
 
     end