cmdx 1.0.0 → 1.1.0

data/lib/cmdx/coercions/hash.rb

@@ -2,47 +2,33 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Hash type.
+    # Coercion class for converting values to hashes.
     #
-    # The Hash coercion converts parameter values to Hash objects
-    # with support for various input formats including JSON strings,
-    # arrays (converted to hash), and Rails parameters.
-    #
-    # @example Basic hash coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     optional :metadata, type: :hash, default: {}
-    #     optional :options, type: :hash
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Hash.call({a: 1})              # => {a: 1}
-    #   Coercions::Hash.call('{"a":1,"b":2}')     # => {"a"=>1, "b"=>2} (JSON)
-    #   Coercions::Hash.call([:a, 1, :b, 2])     # => {:a=>1, :b=>2} (Array)
-    #   Coercions::Hash.call("invalid")           # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Hash
-
-      extend self
+    # This coercion handles conversion of various types to hashes, with special
+    # handling for JSON-formatted strings that start with "{" and array-to-hash
+    # conversion using array splatting.
+    class Hash < Coercion
 
-      # Coerce a value to Hash.
+      # Converts the given value to a hash.
       #
-      # Supports multiple input formats:
-      # - Hash objects (returned as-is)
-      # - ActionController::Parameters (returned as-is)
-      # - JSON strings starting with '{' (parsed as JSON)
-      # - Arrays (converted using Hash[*array])
+      # @param value [Object] the value to convert to a hash
+      # @param _options [Hash] optional configuration (currently unused)
       #
-      # @param value [Object] value to coerce to hash
-      # @param _options [Hash] coercion options (unused)
-      # @return [Hash] coerced hash value
-      # @raise [CoercionError] if coercion fails
+      # @return [Hash] the converted hash value
       #
-      # @example
-      #   Coercions::Hash.call({key: "value"})      # => {key: "value"}
-      #   Coercions::Hash.call('{"a": 1}')          # => {"a" => 1}
-      #   Coercions::Hash.call([:a, 1, :b, 2])     # => {:a => 1, :b => 2}
+      # @raise [CoercionError] if the value cannot be converted to a hash
+      # @raise [JSON::ParserError] if value is a JSON string that cannot be parsed
+      # @raise [ArgumentError] if array cannot be converted to hash pairs
+      # @raise [TypeError] if the value type is not supported
+      #
+      # @example Converting a JSON string
+      #   Coercions::Hash.call('{"a": 1, "b": 2}') #=> {"a" => 1, "b" => 2}
+      #
+      # @example Converting an array to hash
+      #   Coercions::Hash.call(["a", 1, "b", 2]) #=> {"a" => 1, "b" => 2}
+      #
+      # @example Passing through existing hashes
+      #   Coercions::Hash.call({"key" => "value"}) #=> {"key" => "value"}
       def call(value, _options = {})
         case value.class.name
         when "Hash", "ActionController::Parameters"
@@ -60,11 +46,6 @@ module CMDx
 
       private
 
-      # Raise a standardized coercion error.
-      #
-      # @return [void]
-      # @raise [CoercionError] always raises coercion error
-      # @api private
       def raise_coercion_error!
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_a",

data/lib/cmdx/coercions/integer.rb

@@ -2,45 +2,32 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Integer type.
+    # Coercion class for converting values to integers.
     #
-    # The Integer coercion converts parameter values to Integer objects
-    # using Ruby's built-in Integer() method, with proper error handling
-    # for values that cannot be converted.
-    #
-    # @example Basic integer coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_id, type: :integer
-    #     optional :quantity, type: :integer, default: 1
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Integer.call("123")     # => 123
-    #   Coercions::Integer.call("0x10")    # => 16 (hex)
-    #   Coercions::Integer.call("0b1010")  # => 10 (binary)
-    #   Coercions::Integer.call(45.7)      # => 45 (truncated)
-    #   Coercions::Integer.call("invalid") # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Integer
-
-      module_function
+    # This coercion handles conversion of various types to integers using Ruby's
+    # built-in Integer() method, which provides strict type conversion.
+    class Integer < Coercion
 
-      # Coerce a value to Integer.
+      # Converts the given value to an integer.
+      #
+      # @param value [Object] the value to convert to an integer
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Integer] the converted integer value
+      #
+      # @raise [CoercionError] if the value cannot be converted to an integer
       #
-      # @param value [Object] value to coerce to integer
-      # @param _options [Hash] coercion options (unused)
-      # @return [Integer] coerced integer value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting numeric strings
+      #   Coercions::Integer.call("123") #=> 123
+      #   Coercions::Integer.call("-456") #=> -456
       #
-      # @example
-      #   Coercions::Integer.call("123")   # => 123
-      #   Coercions::Integer.call(45.9)    # => 45
-      #   Coercions::Integer.call("0xFF")  # => 255
+      # @example Converting other numeric types
+      #   Coercions::Integer.call(123.45) #=> 123
+      #   Coercions::Integer.call(Time.now) #=> 1672574400 (timestamp)
+      #   Coercions::Integer.call(Complex(42, 0)) #=> 42
       def call(value, _options = {})
         Integer(value)
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, FloatDomainError, RangeError, TypeError # rubocop:disable Lint/ShadowedException
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_an",
           type: "integer",

data/lib/cmdx/coercions/rational.rb

@@ -2,44 +2,32 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Rational type.
+    # Coercion class for converting values to rational numbers.
     #
-    # The Rational coercion converts parameter values to Rational number objects
-    # using Ruby's built-in Rational() method, with proper error handling
-    # for values that cannot be converted to rational numbers.
-    #
-    # @example Basic rational coercion
-    #   class MathTask < CMDx::Task
-    #     required :fraction, type: :rational
-    #     optional :ratio, type: :rational, default: Rational(1, 2)
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Rational.call("1/2")      # => (1/2)
-    #   Coercions::Rational.call("3/4")      # => (3/4)
-    #   Coercions::Rational.call(0.5)        # => (1/2)
-    #   Coercions::Rational.call("invalid")  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Rational
-
-      module_function
+    # This coercion handles conversion of various types to rational numbers,
+    # using Ruby's built-in Rational() method for type conversion.
+    class Rational < Coercion
 
-      # Coerce a value to Rational.
+      # Converts the given value to a rational number.
+      #
+      # @param value [Object] the value to convert to a rational number
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [Rational] the converted rational value
+      #
+      # @raise [CoercionError] if the value cannot be converted to a rational number
+      #
+      # @example Converting a string fraction
+      #   Coercions::Rational.call('1/2') #=> (1/2)
       #
-      # @param value [Object] value to coerce to rational number
-      # @param _options [Hash] coercion options (unused)
-      # @return [Rational] coerced rational number value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting an integer
+      #   Coercions::Rational.call(5) #=> (5/1)
       #
-      # @example
-      #   Coercions::Rational.call("1/2")    # => (1/2)
-      #   Coercions::Rational.call(0.75)     # => (3/4)
-      #   Coercions::Rational.call("3.5")    # => (7/2)
+      # @example Converting a float
+      #   Coercions::Rational.call(0.25) #=> (1/4)
       def call(value, _options = {})
         Rational(value)
-      rescue ArgumentError, TypeError
+      rescue ArgumentError, FloatDomainError, RangeError, TypeError, ZeroDivisionError # rubocop:disable Lint/ShadowedException
         raise CoercionError, I18n.t(
           "cmdx.coercions.into_a",
           type: "rational",

data/lib/cmdx/coercions/string.rb

@@ -2,41 +2,33 @@
 
 module CMDx
   module Coercions
-    # Coerces values to String type.
+    # Coercion class for converting values to strings.
     #
-    # The String coercion converts parameter values to String objects
-    # using Ruby's built-in String() method, which handles various
-    # input types safely.
-    #
-    # @example Basic string coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order_id, type: :string
-    #     optional :notes, type: :string
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::String.call(123)        # => "123"
-    #   Coercions::String.call(:symbol)    # => "symbol"
-    #   Coercions::String.call(true)       # => "true"
-    #   Coercions::String.call(nil)        # => ""
-    #   Coercions::String.call([1, 2])     # => "12" (array to_s)
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module String
-
-      module_function
+    # This coercion handles conversion of various types to strings using Ruby's
+    # built-in String() method, which provides consistent string conversion
+    # behavior across different object types.
+    class String < Coercion
 
-      # Coerce a value to String.
+      # Converts the given value to a string.
+      #
+      # @param value [Object] the value to convert to a string
+      # @param _options [Hash] optional configuration (currently unused)
+      #
+      # @return [String] the converted string value
+      #
+      # @raise [TypeError] if the value cannot be converted to a string
+      #
+      # @example Converting numbers
+      #   Coercions::String.call(123) #=> "123"
+      #   Coercions::String.call(45.67) #=> "45.67"
       #
-      # @param value [Object] value to coerce to string
-      # @param _options [Hash] coercion options (unused)
-      # @return [String] coerced string value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting symbols and nil
+      #   Coercions::String.call(:symbol) #=> "symbol"
+      #   Coercions::String.call(nil) #=> ""
       #
-      # @example
-      #   Coercions::String.call(123)    # => "123"
-      #   Coercions::String.call(:test)  # => "test"
+      # @example Converting boolean values
+      #   Coercions::String.call(true) #=> "true"
+      #   Coercions::String.call(false) #=> "false"
       def call(value, _options = {})
         String(value)
       end

data/lib/cmdx/coercions/time.rb

@@ -2,54 +2,38 @@
 
 module CMDx
   module Coercions
-    # Coerces values to Time type.
+    # Coercion class for converting values to Time objects.
     #
-    # The Time coercion converts parameter values to Time objects
-    # with support for time parsing, custom format strings, and
-    # automatic handling of time-like objects.
-    #
-    # @example Basic time coercion
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :created_at, type: :time
-    #     optional :scheduled_at, type: :time, format: "%Y-%m-%d %H:%M:%S"
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Time.call("2023-12-25 14:30:00")                      # => Time object
-    #   Coercions::Time.call("25/12/2023 2:30 PM", format: "%d/%m/%Y %l:%M %p") # Custom format
-    #   Coercions::Time.call(Date.today)                                 # => Time (from Date)
-    #   Coercions::Time.call("invalid")                                  # => raises CoercionError
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions
-    module Time
-
-      # Time-compatible class names that are passed through unchanged
-      # @return [Array<String>] class names that represent time-like objects
-      ANALOG_TYPES = %w[Date DateTime Time].freeze
+    # This coercion handles conversion of various types to Time objects, with special
+    # handling for analog types (DateTime, Time) and custom format parsing.
+    class Time < Coercion
 
-      module_function
+      ANALOG_TYPES = %w[DateTime Time].freeze
 
-      # Coerce a value to Time.
+      # Converts the given value to a Time object.
+      #
+      # @param value [Object] the value to convert to a Time object
+      # @param options [Hash] optional configuration
+      # @option options [String] :strptime custom format string for parsing
+      #
+      # @return [Time] the converted Time object
+      #
+      # @raise [CoercionError] if the value cannot be converted to a Time object
       #
-      # Handles multiple input formats:
-      # - Date, DateTime, Time objects (returned as-is)
-      # - String with custom format (parsed using strptime)
-      # - String with standard format (parsed using Time.parse)
+      # @example Converting with custom format
+      #   Coercions::Time.call('2023-12-25 14:30', strptime: '%Y-%m-%d %H:%M') #=> 2023-12-25 14:30:00
       #
-      # @param value [Object] value to coerce to time
-      # @param options [Hash] coercion options
-      # @option options [String] :format custom time format string
-      # @return [Time] coerced time value
-      # @raise [CoercionError] if coercion fails
+      # @example Converting standard time strings
+      #   Coercions::Time.call('2023-12-25 14:30:00') #=> 2023-12-25 14:30:00
+      #   Coercions::Time.call('Dec 25, 2023') #=> 2023-12-25 00:00:00
       #
-      # @example
-      #   Coercions::Time.call("2023-12-25 14:30:00")                        # => Time
-      #   Coercions::Time.call("25/12/2023 14:30", format: "%d/%m/%Y %H:%M") # => Time with custom format
-      #   Coercions::Time.call(DateTime.now)                                 # => Time from DateTime
+      # @example Analog types pass through unchanged
+      #   time = Time.now
+      #   Coercions::Time.call(time) #=> time (unchanged)
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
-        return ::Time.strptime(value, options[:format]) if options[:format]
+        return value.to_time if value.respond_to?(:to_time)
+        return ::Time.strptime(value, options[:strptime]) if options[:strptime]
 
         ::Time.parse(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/virtual.rb

@@ -2,41 +2,24 @@
 
 module CMDx
   module Coercions
-    # Virtual coercion that returns values unchanged.
+    # Coercion class for virtual values that performs no conversion.
     #
-    # The Virtual coercion is a pass-through that returns the input value
-    # without any transformation. This is useful for parameters that should
-    # not undergo type coercion or when you want to preserve the original
-    # value type and structure.
-    #
-    # @example Virtual coercion usage
-    #   class ProcessOrderTask < CMDx::Task
-    #     required :order  # defaults to virtual type
-    #     optional :metadata, type: :virtual
-    #     optional :config, type: :virtual
-    #   end
-    #
-    # @example Coercion behavior
-    #   Coercions::Virtual.call("string")     # => "string"
-    #   Coercions::Virtual.call(123)          # => 123
-    #   Coercions::Virtual.call([1, 2, 3])    # => [1, 2, 3]
-    #   Coercions::Virtual.call({a: 1})       # => {a: 1}
-    #   Coercions::Virtual.call(nil)          # => nil
-    #
-    # @see ParameterValue Parameter value coercion
-    # @see Parameter Parameter type definitions (defaults to virtual)
-    module Virtual
+    # This coercion acts as a pass-through, returning the input value unchanged.
+    # It's useful when you want to maintain the original value type and format
+    # without any transformation.
+    class Virtual < Coercion
 
-      module_function
-
-      # Return the value unchanged (no coercion).
+      # Returns the given value unchanged.
+      #
+      # @param value [Object] the value to return as-is
+      # @param _options [Hash] optional configuration (currently unused)
       #
-      # @param value [Object] value to pass through unchanged
-      # @param _options [Hash] coercion options (unused)
-      # @return [Object] the original value without modification
+      # @return [Object] the original value without any conversion
       #
-      # @example
-      #   Coercions::Virtual.call(anything)  # => anything
+      # @example Returning values unchanged
+      #   Coercions::Virtual.call("hello") #=> "hello"
+      #   Coercions::Virtual.call(123) #=> 123
+      #   Coercions::Virtual.call(nil) #=> nil
       def call(value, _options = {})
         value
       end