cmdx 1.9.0 → 1.10.0

data/lib/cmdx/middlewares/timeout.rb

@@ -21,6 +21,8 @@ module CMDx
       extend self
 
       # Default timeout limit in seconds when none is specified.
+      #
+      # @rbs DEFAULT_LIMIT: Integer
       DEFAULT_LIMIT = 3
 
       # Middleware entry point that enforces execution time limits.
@@ -51,6 +53,8 @@ module CMDx
       #   Timeout.call(task, seconds: -> { calculate_timeout }, &block)
       # @example Conditional timeout control
       #   Timeout.call(task, if: :enable_timeout, &block)
+      #
+      # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
       def call(task, **options, &)
         return yield unless Utils::Condition.evaluate(task, options)
 

data/lib/cmdx/pipeline.rb

@@ -6,7 +6,14 @@ module CMDx
   # and handling breakpoints that can interrupt execution at specific task statuses.
   class Pipeline
 
-    # @return [Workflow] The workflow instance being executed
+    # Returns the workflow being executed by this pipeline.
+    #
+    # @return [Workflow] The workflow instance
+    #
+    # @example
+    #   pipeline.workflow.context[:status] # => "processing"
+    #
+    # @rbs @workflow: Workflow
     attr_reader :workflow
 
     # @param workflow [Workflow] The workflow to execute
@@ -15,6 +22,8 @@ module CMDx
     #
     # @example
     #   pipeline = Pipeline.new(my_workflow)
+    #
+    # @rbs (Workflow workflow) -> void
     def initialize(workflow)
       @workflow = workflow
     end
@@ -27,6 +36,8 @@ module CMDx
     #
     # @example
     #   Pipeline.execute(my_workflow)
+    #
+    # @rbs (Workflow workflow) -> void
     def self.execute(workflow)
       new(workflow).execute
     end
@@ -40,6 +51,8 @@ module CMDx
     # @example
     #   pipeline = Pipeline.new(my_workflow)
     #   pipeline.execute
+    #
+    # @rbs () -> void
     def execute
       workflow.class.pipeline.each do |group|
         next unless Utils::Condition.evaluate(workflow, group.options)
@@ -65,6 +78,8 @@ module CMDx
     #
     # @example
     #   execute_group_tasks(group, ["failed", "skipped"])
+    #
+    # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_group_tasks(group, breakpoints)
       case strategy = group.options[:strategy]
       when NilClass, /sequential/ then execute_tasks_in_sequence(group, breakpoints)
@@ -85,6 +100,8 @@ module CMDx
     #
     # @example
     #   execute_tasks_in_sequence(group, ["failed", "skipped"])
+    #
+    # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_tasks_in_sequence(group, breakpoints)
       group.tasks.each do |task|
         task_result = task.execute(workflow.context)
@@ -107,6 +124,8 @@ module CMDx
     #
     # @example
     #   execute_tasks_in_parallel(group, ["failed"])
+    #
+    # @rbs (untyped group, Array[String] breakpoints) -> void
     def execute_tasks_in_parallel(group, breakpoints)
       raise "install the `parallel` gem to use this feature" unless defined?(Parallel)
 

data/lib/cmdx/railtie.rb

@@ -21,6 +21,8 @@ module CMDx
     #   # This initializer runs automatically when Rails starts
     #   # It will load locales like en.yml, es.yml, fr.yml if they exist
     #   # in the CMDx gem's locales directory
+    #
+    # @rbs (untyped app) -> void
     initializer("cmdx.configure_locales") do |app|
       Array(app.config.i18n.available_locales).each do |locale|
         path = CMDx.gem_path.join("lib/locales/#{locale}.yml")
@@ -35,6 +37,8 @@ module CMDx
     # Configures the backtrace cleaner for CMDx in a Rails environment.
     #
     # Sets the backtrace cleaner to the Rails backtrace cleaner.
+    #
+    # @rbs () -> void
     initializer("cmdx.backtrace_cleaner") do
       CMDx.configuration.backtrace_cleaner = lambda do |backtrace|
         Rails.backtrace_cleaner.clean(backtrace)

data/lib/cmdx/result.rb

@@ -11,18 +11,22 @@ module CMDx
 
     extend Forwardable
 
+    # @rbs STATES: Array[String]
     STATES = [
       INITIALIZED = "initialized",  # Initial state before execution
       EXECUTING = "executing",      # Currently executing task logic
       COMPLETE = "complete",        # Successfully completed execution
       INTERRUPTED = "interrupted"   # Execution was halted due to failure
     ].freeze
+
+    # @rbs STATUSES: Array[String]
     STATUSES = [
       SUCCESS = "success",  # Task completed successfully
       SKIPPED = "skipped",  # Task was skipped intentionally
       FAILED = "failed"     # Task failed due to error or validation
     ].freeze
 
+    # @rbs STRIP_FAILURE: Proc
     STRIP_FAILURE = proc do |hash, result, key|
       unless result.send(:"#{key}?")
         # Strip caused/threw failures since its the same info as the log line
@@ -31,7 +35,65 @@ module CMDx
     end.freeze
     private_constant :STRIP_FAILURE
 
-    attr_reader :task, :state, :status, :metadata, :reason, :cause
+    # Returns the task instance associated with this result.
+    #
+    # @return [CMDx::Task] The task instance
+    #
+    # @example
+    #   result.task.id # => "users/create"
+    #
+    # @rbs @task: Task
+    attr_reader :task
+
+    # Returns the current execution state of the result.
+    #
+    # @return [String] One of: "initialized", "executing", "complete", "interrupted"
+    #
+    # @example
+    #   result.state # => "complete"
+    #
+    # @rbs @state: String
+    attr_reader :state
+
+    # Returns the execution status of the result.
+    #
+    # @return [String] One of: "success", "skipped", "failed"
+    #
+    # @example
+    #   result.status # => "success"
+    #
+    # @rbs @status: String
+    attr_reader :status
+
+    # Returns additional metadata about the result.
+    #
+    # @return [Hash{Symbol => Object}] Metadata hash
+    #
+    # @example
+    #   result.metadata # => { duration: 1.5, retries: 2 }
+    #
+    # @rbs @metadata: Hash[Symbol, untyped]
+    attr_reader :metadata
+
+    # Returns the reason for interruption (skip or failure).
+    #
+    # @return [String, nil] The reason message, or nil if not interrupted
+    #
+    # @example
+    #   result.reason # => "Validation failed"
+    #
+    # @rbs @reason: (String | nil)
+    attr_reader :reason
+
+    # Returns the exception that caused the interruption.
+    #
+    # @return [Exception, nil] The causing exception, or nil if not interrupted
+    #
+    # @example
+    #   result.cause # => #<StandardError: Connection timeout>
+    #
+    # @rbs @cause: (Exception | nil)
+    attr_reader :cause
 
     def_delegators :task, :context, :chain, :errors
     alias ctx context
@@ -45,6 +107,8 @@ module CMDx
     # @example
     #   result = CMDx::Result.new(my_task)
     #   result.state # => "initialized"
+    #
+    # @rbs (Task) -> void
     def initialize(task)
       raise TypeError, "must be a CMDx::Task" unless task.is_a?(CMDx::Task)
 
@@ -62,6 +126,8 @@ module CMDx
       # @example
       #   result.initialized? # => true
       #   result.executing?   # => false
+      #
+      # @rbs () -> bool
       define_method(:"#{s}?") { state == s }
 
       # @param block [Proc] Block to execute conditionally
@@ -75,6 +141,8 @@ module CMDx
       # @example
       #   result.handle_initialized { |r| puts "Starting execution" }
       #   result.handle_complete { |r| puts "Task completed" }
+      #
+      # @rbs () { (Result) -> void } -> self
       define_method(:"handle_#{s}") do |&block|
         raise ArgumentError, "block required" unless block
 
@@ -87,6 +155,8 @@ module CMDx
     #
     # @example
     #   result.executed! # Transitions to complete or interrupted
+    #
+    # @rbs () -> self
     def executed!
       success? ? complete! : interrupt!
     end
@@ -95,6 +165,8 @@ module CMDx
     #
     # @example
     #   result.executed? # => true if complete? || interrupted?
+    #
+    # @rbs () -> bool
     def executed?
       complete? || interrupted?
     end
@@ -109,6 +181,8 @@ module CMDx
     #
     # @example
     #   result.handle_executed { |r| puts "Task finished: #{r.outcome}" }
+    #
+    # @rbs () { (Result) -> void } -> self
     def handle_executed(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -120,6 +194,8 @@ module CMDx
     #
     # @example
     #   result.executing! # Transitions from initialized to executing
+    #
+    # @rbs () -> void
     def executing!
       return if executing?
 
@@ -132,6 +208,8 @@ module CMDx
     #
     # @example
     #   result.complete! # Transitions from executing to complete
+    #
+    # @rbs () -> void
     def complete!
       return if complete?
 
@@ -144,6 +222,8 @@ module CMDx
     #
     # @example
     #   result.interrupt! # Transitions from executing to interrupted
+    #
+    # @rbs () -> void
     def interrupt!
       return if interrupted?
 
@@ -158,6 +238,8 @@ module CMDx
       # @example
       #   result.success? # => true
       #   result.failed?  # => false
+      #
+      # @rbs () -> bool
       define_method(:"#{s}?") { status == s }
 
       # @param block [Proc] Block to execute conditionally
@@ -171,6 +253,8 @@ module CMDx
       # @example
       #   result.handle_success { |r| puts "Task succeeded" }
       #   result.handle_failed { |r| puts "Task failed: #{r.reason}" }
+      #
+      # @rbs () { (Result) -> void } -> self
       define_method(:"handle_#{s}") do |&block|
         raise ArgumentError, "block required" unless block
 
@@ -183,6 +267,8 @@ module CMDx
     #
     # @example
     #   result.good? # => true if !failed?
+    #
+    # @rbs () -> bool
     def good?
       !failed?
     end
@@ -198,6 +284,8 @@ module CMDx
     #
     # @example
     #   result.handle_good { |r| puts "Task completed successfully" }
+    #
+    # @rbs () { (Result) -> void } -> self
     def handle_good(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -209,6 +297,8 @@ module CMDx
     #
     # @example
     #   result.bad? # => true if !success?
+    #
+    # @rbs () -> bool
     def bad?
       !success?
     end
@@ -223,6 +313,8 @@ module CMDx
     #
     # @example
     #   result.handle_bad { |r| puts "Task had issues: #{r.reason}" }
+    #
+    # @rbs () { (Result) -> void } -> self
     def handle_bad(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -240,6 +332,8 @@ module CMDx
     # @example
     #   result.skip!("Dependencies not met", cause: dependency_error)
     #   result.skip!("Already processed", halt: false)
+    #
+    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
     def skip!(reason = nil, halt: true, cause: nil, **metadata)
       return if skipped?
 
@@ -264,6 +358,8 @@ module CMDx
     # @example
     #   result.fail!("Validation failed", cause: validation_error)
     #   result.fail!("Network timeout", halt: false, timeout: 30)
+    #
+    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
     def fail!(reason = nil, halt: true, cause: nil, **metadata)
       return if failed?
 
@@ -283,6 +379,8 @@ module CMDx
     #
     # @example
     #   result.halt! # Raises appropriate fault based on status
+    #
+    # @rbs () -> void
     def halt!
       return if success?
 
@@ -315,6 +413,8 @@ module CMDx
     # @example
     #   other_result = OtherTask.execute
     #   result.throw!(other_result, cause: upstream_error)
+    #
+    # @rbs (Result result, halt: bool, cause: Exception?, **untyped metadata) -> void
     def throw!(result, halt: true, cause: nil, **metadata)
       raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
@@ -332,6 +432,8 @@ module CMDx
     # @example
     #   cause = result.caused_failure
     #   puts "Caused by: #{cause.task.id}" if cause
+    #
+    # @rbs () -> Result?
     def caused_failure
       return unless failed?
 
@@ -344,6 +446,8 @@ module CMDx
     #   if result.caused_failure?
     #     puts "This task caused the failure"
     #   end
+    #
+    # @rbs () -> bool
     def caused_failure?
       return false unless failed?
 
@@ -355,6 +459,8 @@ module CMDx
     # @example
     #   thrown = result.threw_failure
     #   puts "Thrown by: #{thrown.task.id}" if thrown
+    #
+    # @rbs () -> Result?
     def threw_failure
       return unless failed?
 
@@ -369,6 +475,8 @@ module CMDx
     #   if result.threw_failure?
     #     puts "This task threw the failure"
     #   end
+    #
+    # @rbs () -> bool
     def threw_failure?
       return false unless failed?
 
@@ -381,6 +489,8 @@ module CMDx
     #   if result.thrown_failure?
     #     puts "This failure was thrown from another task"
     #   end
+    #
+    # @rbs () -> bool
     def thrown_failure?
       failed? && !caused_failure?
     end
@@ -390,6 +500,8 @@ module CMDx
     # @example
     #   position = result.index
     #   puts "Task #{position + 1} of #{chain.results.count}"
+    #
+    # @rbs () -> Integer
     def index
       chain.index(self)
     end
@@ -398,6 +510,8 @@ module CMDx
     #
     # @example
     #   result.outcome # => "success" or "interrupted"
+    #
+    # @rbs () -> String
     def outcome
       initialized? || thrown_failure? ? state : status
     end
@@ -407,6 +521,8 @@ module CMDx
     # @example
     #   result.to_h
     #   # => {state: "complete", status: "success", outcome: "success", metadata: {}}
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       task.to_h.merge!(
         state:,
@@ -430,6 +546,8 @@ module CMDx
     #
     # @example
     #   result.to_s # => "task_id=my_task state=complete status=success"
+    #
+    # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h) do |key, value|
         case key
@@ -446,6 +564,8 @@ module CMDx
     # @example
     #   state, status = result.deconstruct
     #   puts "State: #{state}, Status: #{status}"
+    #
+    # @rbs (*untyped) -> Array[untyped]
     def deconstruct(*)
       [state, status, reason, cause, metadata]
     end
@@ -461,6 +581,8 @@ module CMDx
     #   in {bad: true}
     #     puts "Task had issues"
     #   end
+    #
+    # @rbs (*untyped) -> Hash[Symbol, untyped]
     def deconstruct_keys(*)
       {
         state: state,

data/lib/cmdx/task.rb

@@ -8,10 +8,68 @@ module CMDx
 
     extend Forwardable
 
-    attr_reader :attributes, :errors, :id, :context, :result, :chain
+    # Returns the hash of processed attribute values for this task.
+    #
+    # @return [Hash{Symbol => Object}] Hash of attribute names to their values
+    #
+    # @example
+    #   task.attributes # => { user_id: 42, user_name: "John" }
+    #
+    # @rbs @attributes: Hash[Symbol, untyped]
+    attr_reader :attributes
+
+    # Returns the collection of validation and execution errors.
+    #
+    # @return [Errors] The errors collection
+    #
+    # @example
+    #   task.errors.to_h # => { email: ["must be valid"] }
+    #
+    # @rbs @errors: Errors
+    attr_reader :errors
+
+    # Returns the unique identifier for this task instance.
+    #
+    # @return [String] The task identifier
+    #
+    # @example
+    #   task.id # => "abc123xyz"
+    #
+    # @rbs @id: String
+    attr_reader :id
+
+    # Returns the execution context for this task.
+    #
+    # @return [Context] The context instance
+    #
+    # @example
+    #   task.context[:user_id] # => 42
+    #
+    # @rbs @context: Context
+    attr_reader :context
     alias ctx context
+
+    # Returns the execution result for this task.
+    #
+    # @return [Result] The result instance
+    #
+    # @example
+    #   task.result.status # => "success"
+    #
+    # @rbs @result: Result
+    attr_reader :result
     alias res result
 
+    # Returns the execution chain containing all task results.
+    #
+    # @return [Chain] The chain instance
+    #
+    # @example
+    #   task.chain.results.size # => 3
+    #
+    # @rbs @chain: Chain
+    attr_reader :chain
+
     def_delegators :result, :skip!, :fail!, :throw!
 
     # @param context [Hash, Context] The initial context for the task
@@ -25,6 +83,8 @@ module CMDx
     # @example
     #   task = MyTask.new(name: "example", priority: :high)
     #   task = MyTask.new(Context.build(name: "example"))
+    #
+    # @rbs (untyped context) -> void
     def initialize(context = {})
       Deprecator.restrict(self)
 
@@ -47,6 +107,8 @@ module CMDx
       #   class MyTask < Task
       #     settings deprecate: true, tags: [:experimental]
       #   end
+      #
+      # @rbs (**untyped options) -> Hash[Symbol, untyped]
       def settings(**options)
         @settings ||= begin
           hash =
@@ -81,6 +143,8 @@ module CMDx
       # @example
       #   register(:attribute, MyAttribute.new)
       #   register(:callback, :before, -> { puts "before" })
+      #
+      # @rbs (Symbol type, untyped object, *untyped) -> void
       def register(type, object, ...)
         case type
         when :attribute then settings[:attributes].register(object, ...)
@@ -101,6 +165,8 @@ module CMDx
       # @example
       #   deregister(:attribute, :name)
       #   deregister(:callback, :before, MyCallback)
+      #
+      # @rbs (Symbol type, untyped object, *untyped) -> void
       def deregister(type, object, ...)
         case type
         when :attribute then settings[:attributes].deregister(object, ...)
@@ -117,6 +183,8 @@ module CMDx
       # @example
       #   attributes :name, :email
       #   attributes :age, type: Integer, default: 18
+      #
+      # @rbs (*untyped) -> void
       def attributes(...)
         register(:attribute, Attribute.build(...))
       end
@@ -127,6 +195,8 @@ module CMDx
       # @example
       #   optional :description, :notes
       #   optional :priority, type: Symbol, default: :normal
+      #
+      # @rbs (*untyped) -> void
       def optional(...)
         register(:attribute, Attribute.optional(...))
       end
@@ -136,6 +206,8 @@ module CMDx
       # @example
       #   required :name, :email
       #   required :age, type: Integer, min: 0
+      #
+      # @rbs (*untyped) -> void
       def required(...)
         register(:attribute, Attribute.required(...))
       end
@@ -144,6 +216,8 @@ module CMDx
       #
       # @example
       #   remove_attributes :old_field, :deprecated_field
+      #
+      # @rbs (*Symbol names) -> void
       def remove_attributes(*names)
         deregister(:attribute, names)
       end
@@ -160,6 +234,8 @@ module CMDx
         #   before { puts "before execution" }
         #   after :cleanup, priority: :high
         #   around ->(task) { task.logger.info("starting") }
+        #
+        # @rbs (*untyped callables, **untyped options) ?{ () -> void } -> void
         define_method(callback) do |*callables, **options, &block|
           register(:callback, callback, *callables, **options, &block)
         end
@@ -174,6 +250,8 @@ module CMDx
       #   if result.success?
       #     puts "Task completed successfully"
       #   end
+      #
+      # @rbs (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result
       def execute(*args, **kwargs)
         task = new(*args, **kwargs)
         task.execute(raise: false)
@@ -189,6 +267,8 @@ module CMDx
       # @example
       #   result = MyTask.execute!(name: "example")
       #   # Will raise an exception if execution fails
+      #
+      # @rbs (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result
       def execute!(*args, **kwargs)
         task = new(*args, **kwargs)
         task.execute(raise: true)
@@ -204,6 +284,8 @@ module CMDx
     # @example
     #   result = task.execute
     #   result = task.execute(raise: true)
+    #
+    # @rbs (raise: bool) ?{ (Result) -> void } -> Result
     def execute(raise: false)
       Executor.execute(self, raise:)
       block_given? ? yield(result) : result
@@ -218,6 +300,8 @@ module CMDx
     #       puts "Performing work..."
     #     end
     #   end
+    #
+    # @rbs () -> void
     def work
       raise UndefinedMethodError, "undefined method #{self.class.name}#work"
     end
@@ -227,6 +311,8 @@ module CMDx
     # @example
     #   logger.info "Starting task execution"
     #   logger.error "Task failed", error: exception
+    #
+    # @rbs () -> Logger
     def logger
       @logger ||= begin
         logger = self.class.settings[:logger] || CMDx.configuration.logger
@@ -249,6 +335,8 @@ module CMDx
     #   task_hash = task.to_h
     #   puts "Task type: #{task_hash[:type]}"
     #   puts "Task tags: #{task_hash[:tags].join(', ')}"
+    #
+    # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
         index: result.index,
@@ -265,6 +353,8 @@ module CMDx
     # @example
     #   puts task.to_s
     #   # Output: "Task[MyTask] tags: [:important] id: abc123"
+    #
+    # @rbs () -> String
     def to_s
       Utils::Format.to_str(to_h)
     end

data/lib/cmdx/utils/call.rb

@@ -32,6 +32,8 @@ module CMDx
       # @example Invoking a callable object
       #   callable = MyCallable.new
       #   Call.invoke(user, callable, 'data')
+      #
+      # @rbs (untyped target, (Symbol | Proc | untyped) callable, *untyped args, **untyped kwargs) ?{ () -> untyped } -> untyped
       def invoke(target, callable, *args, **kwargs, &)
         if callable.is_a?(Symbol)
           target.send(callable, *args, **kwargs, &)

data/lib/cmdx/utils/condition.rb

@@ -11,6 +11,7 @@ module CMDx
 
       extend self
 
+      # @rbs EVAL: Proc
       EVAL = proc do |target, callable, *args, **kwargs, &block|
         case callable
         when NilClass, FalseClass, TrueClass then !!callable
@@ -53,6 +54,8 @@ module CMDx
       # @example With arguments and block
       #   Condition.evaluate(user, if: ->(u) { u.has_permission?(:admin) }, :admin)
       #   # => true if the proc returns true when called with user and :admin
+      #
+      # @rbs (untyped target, Hash[Symbol, untyped] options, *untyped) ?{ () -> untyped } -> bool
       def evaluate(target, options, ...)
         case options
         in if: if_cond, unless: unless_cond