cmdx 1.8.0 → 1.9.1

data/lib/cmdx/attribute_registry.rb

@@ -6,6 +6,14 @@ module CMDx
   # in a hierarchical structure, supporting nested attribute definitions.
   class AttributeRegistry
 
+    # Returns the collection of registered attributes.
+    #
+    # @return [Array<Attribute>] Array of registered attributes
+    #
+    # @example
+    #   registry.registry # => [#<Attribute @name=:name>, #<Attribute @name=:email>]
+    #
+    # @rbs @registry: Array[Attribute]
     attr_reader :registry
     alias to_a registry
 
@@ -18,6 +26,8 @@ module CMDx
     # @example
     #   registry = AttributeRegistry.new
     #   registry = AttributeRegistry.new([attr1, attr2])
+    #
+    # @rbs (?Array[Attribute] registry) -> void
     def initialize(registry = [])
       @registry = registry
     end
@@ -28,6 +38,8 @@ module CMDx
     #
     # @example
     #   new_registry = registry.dup
+    #
+    # @rbs () -> AttributeRegistry
     def dup
       self.class.new(registry.dup)
     end
@@ -41,6 +53,8 @@ module CMDx
     # @example
     #   registry.register(attribute)
     #   registry.register([attr1, attr2])
+    #
+    # @rbs (Attribute | Array[Attribute] attributes) -> self
     def register(attributes)
       @registry.concat(Array(attributes))
       self
@@ -56,6 +70,8 @@ module CMDx
     # @example
     #   registry.deregister(:name)
     #   registry.deregister(['name1', 'name2'])
+    #
+    # @rbs ((Symbol | String | Array[Symbol | String]) names) -> self
     def deregister(names)
       Array(names).each do |name|
         @registry.reject! { |attribute| matches_attribute_tree?(attribute, name.to_sym) }
@@ -69,6 +85,8 @@ module CMDx
     # and validate the attribute hierarchy.
     #
     # @param task [Task] The task to associate with all attributes
+    #
+    # @rbs (Task task) -> void
     def define_and_verify(task)
       registry.each do |attribute|
         attribute.task = task
@@ -84,6 +102,8 @@ module CMDx
     # @param name [Symbol] The name to match against
     #
     # @return [Boolean] True if the attribute or any child matches the name
+    #
+    # @rbs (Attribute attribute, Symbol name) -> bool
     def matches_attribute_tree?(attribute, name)
       return true if attribute.method_name == name
 

data/lib/cmdx/attribute_value.rb

@@ -8,6 +8,14 @@ module CMDx
 
     extend Forwardable
 
+    # Returns the attribute managed by this value handler.
+    #
+    # @return [Attribute] The attribute instance
+    #
+    # @example
+    #   attr_value.attribute.name # => :user_id
+    #
+    # @rbs @attribute: Attribute
     attr_reader :attribute
 
     def_delegators :attribute, :task, :parent, :name, :options, :types, :source, :method_name, :required?
@@ -20,6 +28,8 @@ module CMDx
     # @example
     #   attr = Attribute.new(:user_id, required: true)
     #   attr_value = AttributeValue.new(attr)
+    #
+    # @rbs (Attribute attribute) -> void
     def initialize(attribute)
       @attribute = attribute
     end
@@ -30,6 +40,8 @@ module CMDx
     #
     # @example
     #   attr_value.value # => "john_doe"
+    #
+    # @rbs () -> untyped
     def value
       attributes[method_name]
     end
@@ -41,6 +53,8 @@ module CMDx
     #
     # @example
     #   attr_value.generate # => 42
+    #
+    # @rbs () -> untyped
     def generate
       return value if attributes.key?(method_name)
 
@@ -51,9 +65,10 @@ module CMDx
       return if errors.for?(method_name)
 
       coerced_value = coerce_value(derived_value)
+      transformed_value = transform_value(coerced_value)
       return if errors.for?(method_name)
 
-      attributes[method_name] = coerced_value
+      attributes[method_name] = transformed_value
     end
 
     # Validates the current attribute value against configured validators.
@@ -63,6 +78,8 @@ module CMDx
     # @example
     #   attr_value.validate
     #   # Validates value against :presence, :format, etc.
+    #
+    # @rbs () -> void
     def validate
       registry = task.class.settings[:validators]
 
@@ -85,6 +102,7 @@ module CMDx
     # @example
     #   # Sources from task method, proc, or direct value
     #   source_value # => "raw_value"
+    # @rbs () -> untyped
     def source_value
       sourced_value =
         case source
@@ -113,7 +131,9 @@ module CMDx
     #
     # @example
     #   # Default can be symbol, proc, or direct value
-    #   default_value # => "default_value"
+    #   -> { rand(100) } # => 23
+    #
+    # @rbs () -> untyped
     def default_value
       default = options[:default]
 
@@ -138,7 +158,9 @@ module CMDx
     #
     # @example
     #   # Derives from hash key, method call, or proc execution
-    #   derive_value({user_id: 42}) # => 42
+    #   context.user_id # => 42
+    #
+    # @rbs (untyped source_value) -> untyped
     def derive_value(source_value)
       derived_value =
         case source_value
@@ -154,9 +176,31 @@ module CMDx
       nil
     end
 
+    # Transforms the derived value using the transform option.
+    #
+    # @param derived_value [Object] The value to transform
+    #
+    # @return [Object, nil] The transformed value or nil if transformation failed
+    #
+    # @example
+    #   :downcase # => "hello"
+    #
+    # @rbs (untyped derived_value) -> untyped
+    def transform_value(derived_value)
+      transform = options[:transform]
+
+      if transform.is_a?(Symbol) && derived_value.respond_to?(transform, true)
+        derived_value.send(transform)
+      elsif transform.respond_to?(:call)
+        transform.call(derived_value)
+      else
+        derived_value
+      end
+    end
+
     # Coerces the derived value to the expected type(s) using the coercion registry.
     #
-    # @param derived_value [Object] The value to coerce
+    # @param transformed_value [Object] The value to coerce
     #
     # @return [Object, nil] The coerced value or nil if coercion failed
     #
@@ -165,14 +209,16 @@ module CMDx
     # @example
     #   # Coerces "42" to Integer, "true" to Boolean, etc.
     #   coerce_value("42") # => 42
-    def coerce_value(derived_value)
-      return derived_value if attribute.types.empty?
+    #
+    # @rbs (untyped transformed_value) -> untyped
+    def coerce_value(transformed_value)
+      return transformed_value if types.empty?
 
       registry = task.class.settings[:coercions]
-      last_idx = attribute.types.size - 1
+      last_idx = types.size - 1
 
-      attribute.types.find.with_index do |type, i|
-        break registry.coerce(type, task, derived_value, options)
+      types.find.with_index do |type, i|
+        break registry.coerce(type, task, transformed_value, options)
       rescue CoercionError => e
         next if i != last_idx
 
@@ -180,7 +226,7 @@ module CMDx
           if last_idx.zero?
             e.message
           else
-            tl = attribute.types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
+            tl = types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
             Locale.t("cmdx.coercions.into_any", types: tl)
           end
 

data/lib/cmdx/callback_registry.rb

@@ -7,6 +7,7 @@ module CMDx
   # Each callback type represents a specific execution phase or outcome.
   class CallbackRegistry
 
+    # @rbs TYPES: Array[Symbol]
     TYPES = %i[
       before_validation
       before_execution
@@ -20,10 +21,20 @@ module CMDx
       on_bad
     ].freeze
 
+    # Returns the internal registry of callbacks organized by type.
+    #
+    # @return [Hash{Symbol => Set<Array>}] Hash mapping callback types to their registered callables
+    #
+    # @example
+    #   registry.registry # => { before_execution: #<Set: [[[:validate], {}]]> }
+    #
+    # @rbs @registry: Hash[Symbol, Set[Array[untyped]]]
     attr_reader :registry
     alias to_h registry
 
     # @param registry [Hash] Initial registry hash, defaults to empty
+    #
+    # @rbs (?Hash[Symbol, Set[Array[untyped]]] registry) -> void
     def initialize(registry = {})
       @registry = registry
     end
@@ -31,6 +42,8 @@ module CMDx
     # Creates a deep copy of the registry with duplicated callable sets
     #
     # @return [CallbackRegistry] A new instance with duplicated registry contents
+    #
+    # @rbs () -> CallbackRegistry
     def dup
       self.class.new(registry.transform_values(&:dup))
     end
@@ -54,6 +67,8 @@ module CMDx
     #   registry.register(:on_success, if: { status: :completed }) do |task|
     #     task.log("Success callback executed")
     #   end
+    #
+    # @rbs (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self
     def register(type, *callables, **options, &block)
       callables << block if block_given?
 
@@ -73,6 +88,8 @@ module CMDx
     #
     # @example Remove a specific callback
     #   registry.deregister(:before_execution, :validate_inputs)
+    #
+    # @rbs (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self
     def deregister(type, *callables, **options, &block)
       callables << block if block_given?
       return self unless registry[type]
@@ -91,13 +108,25 @@ module CMDx
     #
     # @example Invoke all before_execution callbacks
     #   registry.invoke(:before_execution, task)
+    #
+    # @rbs (Symbol type, Task task) -> void
     def invoke(type, task)
       raise TypeError, "unknown callback type #{type.inspect}" unless TYPES.include?(type)
 
       Array(registry[type]).each do |callables, options|
-        next unless Utils::Condition.evaluate(task, options, task)
+        next unless Utils::Condition.evaluate(task, options)
 
-        Array(callables).each { |callable| Utils::Call.invoke(task, callable, task) }
+        Array(callables).each do |callable|
+          if callable.is_a?(Symbol)
+            task.send(callable)
+          elsif callable.is_a?(Proc)
+            task.instance_exec(&callable)
+          elsif callable.respond_to?(:call)
+            callable.call(task)
+          else
+            raise "cannot invoke #{callable}"
+          end
+        end
       end
     end
 

data/lib/cmdx/chain.rb

@@ -8,9 +8,28 @@ module CMDx
 
     extend Forwardable
 
+    # @rbs THREAD_KEY: Symbol
     THREAD_KEY = :cmdx_chain
 
-    attr_reader :id, :results
+    # Returns the unique identifier for this chain.
+    #
+    # @return [String] The chain identifier
+    #
+    # @example
+    #   chain.id # => "abc123xyz"
+    #
+    # @rbs @id: String
+    attr_reader :id
+
+    # Returns the collection of execution results in this chain.
+    #
+    # @return [Array<Result>] Array of task results
+    #
+    # @example
+    #   chain.results # => [#<Result>, #<Result>]
+    #
+    # @rbs @results: Array[Result]
+    attr_reader :results
 
     def_delegators :results, :index, :first, :last, :size
     def_delegators :first, :state, :status, :outcome, :runtime
@@ -18,6 +37,8 @@ module CMDx
     # Creates a new chain with a unique identifier and empty results collection.
     #
     # @return [Chain] A new chain instance
+    #
+    # @rbs () -> void
     def initialize
       @id = Identifier.generate
       @results = []
@@ -34,6 +55,8 @@ module CMDx
       #   if chain
       #     puts "Current chain: #{chain.id}"
       #   end
+      #
+      # @rbs () -> Chain?
       def current
         Thread.current[THREAD_KEY]
       end
@@ -46,6 +69,8 @@ module CMDx
       #
       # @example
       #   Chain.current = my_chain
+      #
+      # @rbs (Chain chain) -> Chain
       def current=(chain)
         Thread.current[THREAD_KEY] = chain
       end
@@ -56,6 +81,8 @@ module CMDx
       #
       # @example
       #   Chain.clear
+      #
+      # @rbs () -> nil
       def clear
         Thread.current[THREAD_KEY] = nil
       end
@@ -73,6 +100,8 @@ module CMDx
       #   result = task.execute
       #   chain = Chain.build(result)
       #   puts "Chain size: #{chain.size}"
+      #
+      # @rbs (Result result) -> Chain
       def build(result)
         raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
@@ -95,6 +124,8 @@ module CMDx
     #   chain_hash = chain.to_h
     #   puts chain_hash[:id]
     #   puts chain_hash[:results].size
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
         id: id,
@@ -108,6 +139,8 @@ module CMDx
     #
     # @example
     #   puts chain.to_s
+    #
+    # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h)
     end

data/lib/cmdx/coercion_registry.rb

@@ -7,6 +7,14 @@ module CMDx
   # for various data types including arrays, numbers, dates, and other primitives.
   class CoercionRegistry
 
+    # Returns the internal registry mapping coercion types to handler classes.
+    #
+    # @return [Hash{Symbol => Class}] Hash of coercion type names to coercion classes
+    #
+    # @example
+    #   registry.registry # => { integer: Coercions::Integer, boolean: Coercions::Boolean }
+    #
+    # @rbs @registry: Hash[Symbol, Class]
     attr_reader :registry
     alias to_h registry
 
@@ -17,6 +25,8 @@ module CMDx
     # @example
     #   registry = CoercionRegistry.new
     #   registry = CoercionRegistry.new(custom: CustomCoercion)
+    #
+    # @rbs (?Hash[Symbol, Class]? registry) -> void
     def initialize(registry = nil)
       @registry = registry || {
         array: Coercions::Array,
@@ -40,6 +50,8 @@ module CMDx
     #
     # @example
     #   new_registry = registry.dup
+    #
+    # @rbs () -> CoercionRegistry
     def dup
       self.class.new(registry.dup)
     end
@@ -54,6 +66,8 @@ module CMDx
     # @example
     #   registry.register(:custom_type, CustomCoercion)
     #   registry.register("another_type", AnotherCoercion)
+    #
+    # @rbs ((Symbol | String) name, Class coercion) -> self
     def register(name, coercion)
       registry[name.to_sym] = coercion
       self
@@ -68,6 +82,8 @@ module CMDx
     # @example
     #   registry.deregister(:custom_type)
     #   registry.deregister("another_type")
+    #
+    # @rbs ((Symbol | String) name) -> self
     def deregister(name)
       registry.delete(name.to_sym)
       self
@@ -87,6 +103,8 @@ module CMDx
     # @example
     #   result = registry.coerce(:integer, task, "42")
     #   result = registry.coerce(:boolean, task, "true", strict: true)
+    #
+    # @rbs (Symbol type, untyped task, untyped value, ?Hash[Symbol, untyped] options) -> untyped
     def coerce(type, task, value, options = {})
       raise TypeError, "unknown coercion type #{type.inspect}" unless registry.key?(type)
 

data/lib/cmdx/coercions/array.rb

@@ -26,6 +26,8 @@ module CMDx
       #   Array.call("hello")     # => ["hello"]
       #   Array.call(42)          # => [42]
       #   Array.call(nil)         # => []
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Array[untyped]
       def call(value, options = {})
         if value.is_a?(::String) && value.start_with?("[")
           JSON.parse(value)

data/lib/cmdx/coercions/big_decimal.rb

@@ -10,6 +10,7 @@ module CMDx
 
       extend self
 
+      # @rbs DEFAULT_PRECISION: Integer
       DEFAULT_PRECISION = 14
 
       # Converts a value to a BigDecimal
@@ -28,6 +29,8 @@ module CMDx
       # @example Convert other numeric types
       #   BigDecimal.call(42)                         # => #<BigDecimal:7f8b8c0d8e0f '0.42E2',9(18)>
       #   BigDecimal.call(3.14159)                    # => #<BigDecimal:7f8b8c0d8e0f '0.314159E1',9(18)>
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> BigDecimal
       def call(value, options = {})
         BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/boolean.rb

@@ -10,7 +10,10 @@ module CMDx
 
       extend self
 
+      # @rbs FALSEY: Regexp
       FALSEY = /^(false|f|no|n|0)$/i
+
+      # @rbs TRUTHY: Regexp
       TRUTHY = /^(true|t|yes|y|1)$/i
 
       # Converts a value to a Boolean
@@ -34,6 +37,8 @@ module CMDx
       # @example Handle case-insensitive input
       #   Boolean.call("TRUE")   # => true
       #   Boolean.call("False")  # => false
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> bool
       def call(value, options = {})
         case value.to_s.downcase
         when FALSEY then false

data/lib/cmdx/coercions/complex.rb

@@ -26,6 +26,8 @@ module CMDx
       #   Complex.call(5)                          # => (5+0i)
       #   Complex.call(3.14)                       # => (3.14+0i)
       #   Complex.call(Complex(1, 2))              # => (1+2i)
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Complex
       def call(value, options = {})
         Complex(value)
       rescue ArgumentError, TypeError

data/lib/cmdx/coercions/date.rb

@@ -12,6 +12,8 @@ module CMDx
       extend self
 
       # Types that are already date-like and don't need conversion
+      #
+      # @rbs ANALOG_TYPES: Array[String]
       ANALOG_TYPES = %w[Date DateTime Time].freeze
 
       # Converts a value to a Date object
@@ -33,6 +35,8 @@ module CMDx
       # @example Return existing Date objects unchanged
       #   Date.call(Date.new(2023, 12, 25)) # => #<Date: 2023-12-25>
       #   Date.call(DateTime.new(2023, 12, 25)) # => #<Date: 2023-12-25>
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Date
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
         return ::Date.strptime(value, options[:strptime]) if options[:strptime]

data/lib/cmdx/coercions/date_time.rb

@@ -11,6 +11,9 @@ module CMDx
 
       extend self
 
+      # Types that are already date-time-like and don't need conversion
+      #
+      # @rbs ANALOG_TYPES: Array[String]
       ANALOG_TYPES = %w[Date DateTime Time].freeze
 
       # Converts a value to a DateTime
@@ -32,6 +35,8 @@ module CMDx
       # @example Convert existing date objects
       #   DateTime.call(Date.new(2023, 12, 25))     # => #<DateTime: 2023-12-25T00:00:00+00:00>
       #   DateTime.call(Time.new(2023, 12, 25))     # => #<DateTime: 2023-12-25T00:00:00+00:00>
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> DateTime
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
         return ::DateTime.strptime(value, options[:strptime]) if options[:strptime]

data/lib/cmdx/coercions/float.rb

@@ -30,6 +30,8 @@ module CMDx
       #   Float.call(BigDecimal("123.456")) # => 123.456
       #   Float.call(Rational(3, 4))       # => 0.75
       #   Float.call(Complex(5.0, 0))      # => 5.0
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Float
       def call(value, options = {})
         Float(value)
       rescue ArgumentError, RangeError, TypeError

data/lib/cmdx/coercions/hash.rb

@@ -30,6 +30,8 @@ module CMDx
       #   Hash.call([:a, 1, :b, 2]) # => {a: 1, b: 2}
       # @example Coerce from JSON string
       #   Hash.call('{"key": "value"}') # => {"key" => "value"}
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Hash[untyped, untyped]
       def call(value, options = {})
         if value.nil?
           {}
@@ -39,6 +41,8 @@ module CMDx
           ::Hash[*value]
         elsif value.is_a?(::String) && value.start_with?("{")
           JSON.parse(value)
+        elsif value.respond_to?(:to_h)
+          value.to_h
         else
           raise_coercion_error!
         end

data/lib/cmdx/coercions/integer.rb

@@ -34,6 +34,8 @@ module CMDx
       #   Integer.call(nil)       # => 0
       #   Integer.call(false)     # => 0
       #   Integer.call(true)      # => 1
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Integer
       def call(value, options = {})
         Integer(value)
       rescue ArgumentError, FloatDomainError, RangeError, TypeError

data/lib/cmdx/coercions/rational.rb

@@ -33,6 +33,8 @@ module CMDx
       #   Rational.call("")        # => (0/1)
       #   Rational.call(nil)       # => (0/1)
       #   Rational.call(0)         # => (0/1)
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Rational
       def call(value, options = {})
         Rational(value)
       rescue ArgumentError, FloatDomainError, RangeError, TypeError, ZeroDivisionError

data/lib/cmdx/coercions/string.rb

@@ -26,6 +26,8 @@ module CMDx
       #   String.call([1, 2, 3])         # => "[1, 2, 3]"
       #   String.call(nil)               # => ""
       #   String.call(true)              # => "true"
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> String
       def call(value, options = {})
         String(value)
       end

data/lib/cmdx/coercions/symbol.rb

@@ -25,6 +25,8 @@ module CMDx
       #   Symbol.call("user_id")         # => :user_id
       #   Symbol.call("")                # => :""
       #   Symbol.call(:existing)         # => :existing
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Symbol
       def call(value, options = {})
         value.to_sym
       rescue NoMethodError

data/lib/cmdx/coercions/time.rb

@@ -11,6 +11,9 @@ module CMDx
 
       extend self
 
+      # Types that are already time-like and don't need conversion
+      #
+      # @rbs ANALOG_TYPES: Array[String]
       ANALOG_TYPES = %w[DateTime Time].freeze
 
       # Converts a value to a Time object
@@ -34,6 +37,8 @@ module CMDx
       # @example Convert strings with custom format
       #   Time.call("25/12/2023", strptime: "%d/%m/%Y")  # => Time object
       #   Time.call("12-25-2023", strptime: "%m-%d-%Y")  # => Time object
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> Time
       def call(value, options = {})
         return value if ANALOG_TYPES.include?(value.class.name)
         return value.to_time if value.respond_to?(:to_time)