cmdx 1.9.0 → 1.10.0

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,6 +108,8 @@ 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)
 

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?
           {}

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)

data/lib/cmdx/configuration.rb

@@ -6,11 +6,122 @@ module CMDx
   # callbacks, coercions, validators, breakpoints, backtraces, and logging.
   class Configuration
 
+    # @rbs DEFAULT_BREAKPOINTS: Array[String]
     DEFAULT_BREAKPOINTS = %w[failed].freeze
 
-    attr_accessor :middlewares, :callbacks, :coercions, :validators,
-                  :task_breakpoints, :workflow_breakpoints, :logger,
-                  :backtrace, :backtrace_cleaner, :exception_handler
+    # @rbs DEFAULT_ROLLPOINTS: Array[String]
+    DEFAULT_ROLLPOINTS = %w[failed].freeze
+
+    # Returns the middleware registry for task execution.
+    #
+    # @return [MiddlewareRegistry] The middleware registry
+    #
+    # @example
+    #   config.middlewares.register(CustomMiddleware)
+    #
+    # @rbs @middlewares: MiddlewareRegistry
+    attr_accessor :middlewares
+
+    # Returns the callback registry for task lifecycle hooks.
+    #
+    # @return [CallbackRegistry] The callback registry
+    #
+    # @example
+    #   config.callbacks.register(:before_execution, :log_start)
+    #
+    # @rbs @callbacks: CallbackRegistry
+    attr_accessor :callbacks
+
+    # Returns the coercion registry for type conversions.
+    #
+    # @return [CoercionRegistry] The coercion registry
+    #
+    # @example
+    #   config.coercions.register(:custom, CustomCoercion)
+    #
+    # @rbs @coercions: CoercionRegistry
+    attr_accessor :coercions
+
+    # Returns the validator registry for attribute validation.
+    #
+    # @return [ValidatorRegistry] The validator registry
+    #
+    # @example
+    #   config.validators.register(:email, EmailValidator)
+    #
+    # @rbs @validators: ValidatorRegistry
+    attr_accessor :validators
+
+    # Returns the breakpoint statuses for task execution interruption.
+    #
+    # @return [Array<String>] Array of status names that trigger breakpoints
+    #
+    # @example
+    #   config.task_breakpoints = ["failed", "skipped"]
+    #
+    # @rbs @task_breakpoints: Array[String]
+    attr_accessor :task_breakpoints
+
+    # Returns the breakpoint statuses for workflow execution interruption.
+    #
+    # @return [Array<String>] Array of status names that trigger breakpoints
+    #
+    # @example
+    #   config.workflow_breakpoints = ["failed", "skipped"]
+    #
+    # @rbs @task_breakpoints: Array[String]
+    # @rbs @workflow_breakpoints: Array[String]
+    attr_accessor :workflow_breakpoints
+
+    # Returns the logger instance for CMDx operations.
+    #
+    # @return [Logger] The logger instance
+    #
+    # @example
+    #   config.logger.level = Logger::DEBUG
+    #
+    # @rbs @logger: Logger
+    attr_accessor :logger
+
+    # Returns whether to log backtraces for failed tasks.
+    #
+    # @return [Boolean] true if backtraces should be logged
+    #
+    # @example
+    #   config.backtrace = true
+    #
+    # @rbs @backtrace: bool
+    attr_accessor :backtrace
+
+    # Returns the proc used to clean backtraces before logging.
+    #
+    # @return [Proc, nil] The backtrace cleaner proc, or nil if not set
+    #
+    # @example
+    #   config.backtrace_cleaner = ->(bt) { bt.first(5) }
+    #
+    # @rbs @backtrace_cleaner: (Proc | nil)
+    attr_accessor :backtrace_cleaner
+
+    # Returns the proc called when exceptions occur during execution.
+    #
+    # @return [Proc, nil] The exception handler proc, or nil if not set
+    #
+    # @example
+    #   config.exception_handler = ->(task, error) { Sentry.capture_exception(error) }
+    #
+    # @rbs @exception_handler: (Proc | nil)
+    attr_accessor :exception_handler
+
+    # Returns the statuses that trigger a task execution rollback.
+    #
+    # @return [Array<String>] Array of status names that trigger rollback
+    #
+    # @example
+    #   config.rollback_on = ["failed", "skipped"]
+    #
+    # @rbs @rollback_on: Array[String]
+    attr_accessor :rollback_on
 
     # Initializes a new Configuration instance with default values.
     #
@@ -23,6 +134,8 @@ module CMDx
     #   config = Configuration.new
     #   config.middlewares.class # => MiddlewareRegistry
     #   config.task_breakpoints # => ["failed"]
+    #
+    # @rbs () -> void
     def initialize
       @middlewares = MiddlewareRegistry.new
       @callbacks = CallbackRegistry.new
@@ -31,6 +144,7 @@ module CMDx
 
       @task_breakpoints = DEFAULT_BREAKPOINTS
       @workflow_breakpoints = DEFAULT_BREAKPOINTS
+      @rollback_on = DEFAULT_ROLLPOINTS
 
       @backtrace = false
       @backtrace_cleaner = nil
@@ -52,6 +166,8 @@ module CMDx
     #   config = Configuration.new
     #   config.to_h
     #   # => { middlewares: #<MiddlewareRegistry>, callbacks: #<CallbackRegistry>, ... }
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
         middlewares: @middlewares,
@@ -60,6 +176,7 @@ module CMDx
         validators: @validators,
         task_breakpoints: @task_breakpoints,
         workflow_breakpoints: @workflow_breakpoints,
+        rollback_on: @rollback_on,
         backtrace: @backtrace,
         backtrace_cleaner: @backtrace_cleaner,
         exception_handler: @exception_handler,
@@ -78,6 +195,8 @@ module CMDx
   # @example
   #   config = CMDx.configuration
   #   config.middlewares # => #<MiddlewareRegistry>
+  #
+  # @rbs () -> Configuration
   def configuration
     return @configuration if @configuration
 
@@ -99,6 +218,8 @@ module CMDx
   #     config.task_breakpoints = ["failed", "skipped"]
   #     config.logger.level = Logger::DEBUG
   #   end
+  #
+  # @rbs () { (Configuration) -> void } -> Configuration
   def configure
     raise ArgumentError, "block required" unless block_given?
 
@@ -114,6 +235,8 @@ module CMDx
   # @example
   #   CMDx.reset_configuration!
   #   # Configuration is now reset to defaults
+  #
+  # @rbs () -> Configuration
   def reset_configuration!
     @configuration = Configuration.new
   end