cmdx 1.9.0 → 1.9.1

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,109 @@ 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
+    # 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
 
     # Initializes a new Configuration instance with default values.
     #
@@ -23,6 +121,8 @@ module CMDx
     #   config = Configuration.new
     #   config.middlewares.class # => MiddlewareRegistry
     #   config.task_breakpoints # => ["failed"]
+    #
+    # @rbs () -> void
     def initialize
       @middlewares = MiddlewareRegistry.new
       @callbacks = CallbackRegistry.new
@@ -52,6 +152,8 @@ module CMDx
     #   config = Configuration.new
     #   config.to_h
     #   # => { middlewares: #<MiddlewareRegistry>, callbacks: #<CallbackRegistry>, ... }
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
         middlewares: @middlewares,
@@ -78,6 +180,8 @@ module CMDx
   # @example
   #   config = CMDx.configuration
   #   config.middlewares # => #<MiddlewareRegistry>
+  #
+  # @rbs () -> Configuration
   def configuration
     return @configuration if @configuration
 
@@ -99,6 +203,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 +220,8 @@ module CMDx
   # @example
   #   CMDx.reset_configuration!
   #   # Configuration is now reset to defaults
+  #
+  # @rbs () -> Configuration
   def reset_configuration!
     @configuration = Configuration.new
   end

data/lib/cmdx/context.rb

@@ -11,6 +11,14 @@ module CMDx
 
     extend Forwardable
 
+    # Returns the internal hash storing context data.
+    #
+    # @return [Hash{Symbol => Object}] The internal hash table
+    #
+    # @example
+    #   context.table # => { name: "John", age: 30 }
+    #
+    # @rbs @table: Hash[Symbol, untyped]
     attr_reader :table
     alias to_h table
 
@@ -28,6 +36,8 @@ module CMDx
     # @example
     #   context = Context.new(name: "John", age: 30)
     #   context[:name] # => "John"
+    #
+    # @rbs (untyped args) -> void
     def initialize(args = {})
       @table =
         if args.respond_to?(:to_hash)
@@ -50,6 +60,8 @@ module CMDx
     #   existing = Context.new(name: "John")
     #   built = Context.build(existing) # reuses existing context
     #   built.object_id == existing.object_id # => true
+    #
+    # @rbs (untyped context) -> Context
     def self.build(context = {})
       if context.is_a?(self) && !context.frozen?
         context
@@ -70,6 +82,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context[:name] # => "John"
     #   context["name"] # => "John" (automatically converted to symbol)
+    #
+    # @rbs ((String | Symbol) key) -> untyped
     def [](key)
       table[key.to_sym]
     end
@@ -85,6 +99,8 @@ module CMDx
     #   context = Context.new
     #   context.store(:name, "John")
     #   context[:name] # => "John"
+    #
+    # @rbs ((String | Symbol) key, untyped value) -> untyped
     def store(key, value)
       table[key.to_sym] = value
     end
@@ -104,6 +120,8 @@ module CMDx
     #   context.fetch(:name) # => "John"
     #   context.fetch(:age, 25) # => 25
     #   context.fetch(:city) { |key| "Unknown #{key}" } # => "Unknown city"
+    #
+    # @rbs ((String | Symbol) key, *untyped) ?{ ((String | Symbol)) -> untyped } -> untyped
     def fetch(key, ...)
       table.fetch(key.to_sym, ...)
     end
@@ -122,6 +140,8 @@ module CMDx
     #   context.fetch_or_store(:name, "Default") # => "John" (existing value)
     #   context.fetch_or_store(:age, 25) # => 25 (stored and returned)
     #   context.fetch_or_store(:city) { |key| "Unknown #{key}" } # => "Unknown city" (stored and returned)
+    #
+    # @rbs ((String | Symbol) key, ?untyped value) ?{ () -> untyped } -> untyped
     def fetch_or_store(key, value = nil)
       table.fetch(key.to_sym) do
         table[key.to_sym] = block_given? ? yield : value
@@ -139,6 +159,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context.merge!(age: 30, city: "NYC")
     #   context.to_h # => {name: "John", age: 30, city: "NYC"}
+    #
+    # @rbs (?untyped args) -> self
     def merge!(args = {})
       args.to_h.each { |key, value| self[key.to_sym] = value }
       self
@@ -156,6 +178,8 @@ module CMDx
     #   context = Context.new(name: "John", age: 30)
     #   context.delete!(:age) # => 30
     #   context.delete!(:city) { |key| "Key #{key} not found" } # => "Key city not found"
+    #
+    # @rbs ((String | Symbol) key) ?{ ((String | Symbol)) -> untyped } -> untyped
     def delete!(key, &)
       table.delete(key.to_sym, &)
     end
@@ -170,6 +194,8 @@ module CMDx
     #   context1 = Context.new(name: "John")
     #   context2 = Context.new(name: "John")
     #   context1 == context2 # => true
+    #
+    # @rbs (untyped other) -> bool
     def eql?(other)
       other.is_a?(self.class) && (to_h == other.to_h)
     end
@@ -185,6 +211,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context.key?(:name) # => true
     #   context.key?(:age) # => false
+    #
+    # @rbs ((String | Symbol) key) -> bool
     def key?(key)
       table.key?(key.to_sym)
     end
@@ -200,6 +228,8 @@ module CMDx
     #   context = Context.new(user: {profile: {name: "John"}})
     #   context.dig(:user, :profile, :name) # => "John"
     #   context.dig(:user, :profile, :age) # => nil
+    #
+    # @rbs ((String | Symbol) key, *(String | Symbol) keys) -> untyped
     def dig(key, *keys)
       table.dig(key.to_sym, *keys)
     end
@@ -211,6 +241,8 @@ module CMDx
     # @example
     #   context = Context.new(name: "John", age: 30)
     #   context.to_s # => "name: John, age: 30"
+    #
+    # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h)
     end
@@ -227,6 +259,8 @@ module CMDx
     # @yield [Object] optional block
     #
     # @return [Object] the result of the method call
+    #
+    # @rbs (Symbol method_name, *untyped args, **untyped _kwargs) ?{ () -> untyped } -> untyped
     def method_missing(method_name, *args, **_kwargs, &)
       fetch(method_name) do
         store(method_name[0..-2], args.first) if method_name.end_with?("=")
@@ -244,6 +278,8 @@ module CMDx
     #   context = Context.new(name: "John")
     #   context.respond_to?(:name) # => true
     #   context.respond_to?(:age) # => false
+    #
+    # @rbs (Symbol method_name, ?bool include_private) -> bool
     def respond_to_missing?(method_name, include_private = false)
       key?(method_name) || super
     end

data/lib/cmdx/deprecator.rb

@@ -10,6 +10,7 @@ module CMDx
 
     extend self
 
+    # @rbs EVAL: Proc
     EVAL = proc do |target, callable|
       case callable
       when /raise|log|warn/ then callable
@@ -45,6 +46,8 @@ module CMDx
     #   end
     #
     #   MyTask.new # => [MyTask] DEPRECATED: migrate to a replacement or discontinue use
+    #
+    # @rbs (Task task) -> void
     def restrict(task)
       type = EVAL.call(task, task.class.settings[:deprecate])
 

data/lib/cmdx/errors.rb

@@ -8,11 +8,21 @@ module CMDx
 
     extend Forwardable
 
+    # Returns the internal hash of error messages by attribute.
+    #
+    # @return [Hash{Symbol => Set<String>}] Hash mapping attribute names to error message sets
+    #
+    # @example
+    #   errors.messages # => { email: #<Set: ["must be valid", "is required"]> }
+    #
+    # @rbs @messages: Hash[Symbol, Set[String]]
     attr_reader :messages
 
     def_delegators :messages, :empty?
 
     # Initialize a new error collection.
+    #
+    # @rbs () -> void
     def initialize
       @messages = {}
     end
@@ -26,6 +36,8 @@ module CMDx
     #   errors = CMDx::Errors.new
     #   errors.add(:email, "must be valid format")
     #   errors.add(:email, "cannot be blank")
+    #
+    # @rbs (Symbol attribute, String message) -> void
     def add(attribute, message)
       return if message.empty?
 
@@ -42,6 +54,8 @@ module CMDx
     # @example
     #   errors.for?(:email) # => true
     #   errors.for?(:name)  # => false
+    #
+    # @rbs (Symbol attribute) -> bool
     def for?(attribute)
       return false unless messages.key?(attribute)
 
@@ -54,6 +68,8 @@ module CMDx
     #
     # @example
     #   errors.full_messages # => { email: ["email must be valid format", "email cannot be blank"] }
+    #
+    # @rbs () -> Hash[Symbol, Array[String]]
     def full_messages
       messages.each_with_object({}) do |(attribute, messages), hash|
         hash[attribute] = messages.map { |message| "#{attribute} #{message}" }
@@ -66,6 +82,8 @@ module CMDx
     #
     # @example
     #   errors.to_h # => { email: ["must be valid format", "cannot be blank"] }
+    #
+    # @rbs () -> Hash[Symbol, Array[String]]
     def to_h
       messages.transform_values(&:to_a)
     end
@@ -78,6 +96,8 @@ module CMDx
     # @example
     #   errors.to_hash # => { email: ["must be valid format", "cannot be blank"] }
     #   errors.to_hash(true) # => { email: ["email must be valid format", "email cannot be blank"] }
+    #
+    # @rbs (?bool full) -> Hash[Symbol, Array[String]]
     def to_hash(full = false)
       full ? full_messages : to_h
     end
@@ -88,6 +108,8 @@ module CMDx
     #
     # @example
     #   errors.to_s # => "email must be valid format. email cannot be blank"
+    #
+    # @rbs () -> String
     def to_s
       full_messages.values.flatten.join(". ")
     end