cmdx 1.9.0 → 1.10.0

data/README.md

@@ -6,7 +6,7 @@
 
   Build business logic that’s powerful, predictable, and maintainable.
 
-  [Documentation](https://drexed.github.io/cmdx) · [Changelog](./CHANGELOG.md) · [Report Bug](https://github.com/drexed/cmdx/issues) · [Request Feature](https://github.com/drexed/cmdx/issues)
+  [Documentation](https://drexed.github.io/cmdx) · [Changelog](./CHANGELOG.md) · [Report Bug](https://github.com/drexed/cmdx/issues) · [Request Feature](https://github.com/drexed/cmdx/issues) · [LLM.md](https://raw.githubusercontent.com/drexed/cmdx/refs/heads/main/LLM.md)
 
   <img alt="Version" src="https://img.shields.io/gem/v/cmdx">
   <img alt="Build" src="https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg">
@@ -17,6 +17,9 @@
 
 Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
 
+> [!NOTE]
+> Documentation reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
+
 ## Requirements
 
 - Ruby: MRI 3.1+ or JRuby 9.4+.
@@ -105,6 +108,8 @@ I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
 index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
 ```
 
+Ready to dive in? Check out the [Getting Started](https://drexed.github.io/cmdx/getting_started/) guide to learn more.
+
 ## Ecosystem
 
 - [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
@@ -116,7 +121,7 @@ For backwards compatibility of certain functionality:
 
 ## Contributing
 
-Bug reports and pull requests are welcome at https://github.com/drexed/cmdx. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
 
 ## License
 

data/docs/basics/setup.md

@@ -24,6 +24,22 @@ end
 IncompleteTask.execute #=> raises CMDx::UndefinedMethodError
 ```
 
+## Rollback
+
+Undo any operations linked to the given status, helping to restore a pristine state.
+
+```ruby
+class ValidateDocument < CMDx::Task
+  def work
+    # Your logic here...
+  end
+
+  def rollback
+    # Your undo logic...
+  end
+end
+```
+
 ## Inheritance
 
 Share configuration across tasks using inheritance:
@@ -65,3 +81,4 @@ Tasks follow a predictable execution pattern:
 | **Execution** | `executing` | `success`/`failed`/`skipped` | `work` method runs |
 | **Completion** | `executed` | `success`/`failed`/`skipped` | Result finalized |
 | **Freezing** | `executed` | `success`/`failed`/`skipped` | Task becomes immutable |
+| **Rollback** | `executed` | `failed`/`skipped` | Work undone |

data/docs/callbacks.md

@@ -73,7 +73,7 @@ end
 
 ### Class or Module
 
-Implement reusable callback logic in dedicated classes:
+Implement reusable callback logic in dedicated modules and classes:
 
 ```ruby
 class BookingConfirmationCallback

data/docs/getting_started.md

@@ -78,6 +78,16 @@ CMDx.configure do |config|
 end
 ```
 
+### Rollback
+
+Control when a `rollback` of task execution is called.
+
+```ruby
+CMDx.configure do |config|
+  config.rollback_on = ["failed"] # String or Array[String]
+end
+```
+
 ### Backtraces
 
 Enable detailed backtraces for non-fault exceptions to improve debugging. Optionally clean up stack traces to remove framework noise.
@@ -258,7 +268,8 @@ class GenerateInvoice < CMDx::Task
     deprecated: true,                            # Task deprecations
     retries: 3,                                  # Non-fault exception retries
     retry_on: [External::ApiError],              # List of exceptions to retry on
-    retry_jitter: 1                              # Space between retry iteration, eg: current retry num + 1
+    retry_jitter: 1,                             # Space between retry iteration, eg: current retry num + 1
+    rollback_on: ["failed", "skipped"],          # Rollback on override
   )
 
   def work
@@ -269,7 +280,7 @@ end
 
 !!! warning "Important"
 
-    Retries reuse the same context. By default, all `StandardError` exceptions are retried unless you specify `retry_on`.
+    Retries reuse the same context. By default, all `StandardError` exceptions (including faults) are retried unless you specify `retry_on` option for specific matches.
 
 ### Registrations
 
@@ -367,3 +378,12 @@ end
 !!! tip
 
     Use **present tense verbs + noun** for task names, eg: `ModerateBlogPost`, `ScheduleAppointment`, `ValidateDocument`
+
+## Type safety
+
+CMDx includes built-in RBS (Ruby Type Signature) inline annotations throughout the codebase, providing type information for static analysis and editor support.
+
+- **Type checking** — Catch type errors before runtime using tools like Steep or TypeProf
+- **Better IDE support** — Enhanced autocomplete, navigation, and inline documentation
+- **Self-documenting code** — Clear method signatures and return types
+- **Refactoring confidence** — Type-aware refactoring reduces bugs

data/docs/index.md

@@ -6,8 +6,20 @@ Build business logic that's powerful, predictable, and maintainable.
 [![Build](https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg)](https://github.com/drexed/cmdx/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/drexed/cmdx)](https://github.com/drexed/cmdx/blob/main/LICENSE.txt)
 
+---
+
 Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
 
+!!! note
+
+    Documentation reflects the latest code on `main`. For version-specific documentation, please refer to the `docs/` directory within that version's tag.
+
+## Requirements
+
+- Ruby: MRI 3.1+ or JRuby 9.4+.
+
+CMDx works with any Ruby framework. Rails support is built-in, but it's framework-agnostic at its core.
+
 ## Installation
 
 ```sh
@@ -113,7 +125,7 @@ For backwards compatibility of certain functionality:
 
 ## Contributing
 
-Bug reports and pull requests are welcome at https://github.com/drexed/cmdx. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome at <https://github.com/drexed/cmdx>. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
 
 ## License
 

data/docs/retries.md

@@ -0,0 +1,121 @@
+# Retries
+
+CMDx provides automatic retry functionality for tasks that encounter transient failures. This is essential for handling temporary issues like network timeouts, rate limits, or database locks without manual intervention.
+
+## Basic Usage
+
+Configure retries upto n attempts without any delay.
+
+```ruby
+class FetchExternalData < CMDx::Task
+  settings retries: 3
+
+  def work
+    response = HTTParty.get("https://api.example.com/data")
+    context.data = response.parsed_response
+  end
+end
+```
+
+When an exception occurs during execution, CMDx automatically retries up to the configured limit.
+
+## Selective Retries
+
+By default, CMDx retries on `StandardError` and its subclasses. Narrow this to specific exception types:
+
+```ruby
+class ProcessPayment < CMDx::Task
+  settings retries: 5, retry_on: [Stripe::RateLimitError, Net::ReadTimeout]
+
+  def work
+    # Your logic here...
+  end
+end
+```
+
+!!! warning "Important"
+
+    Only exceptions matching the `retry_on` configuration will trigger retries. Uncaught exceptions immediately fail the task.
+
+## Retry Jitter
+
+Add delays between retry attempts to avoid overwhelming external services or to implement exponential backoff strategies.
+
+### Fixed Value
+
+Use a numeric value to calculate linear delay (`jitter * current_retry`):
+
+```ruby
+class ImportRecords < CMDx::Task
+  settings retries: 3, retry_jitter: 0.5
+
+  def work
+    # Delays: 0s, 0.5s (retry 1), 1.0s (retry 2), 1.5s (retry 3)
+    context.records = ExternalAPI.fetch_records
+  end
+end
+```
+
+### Symbol References
+
+Define an instance method for custom delay logic:
+
+```ruby
+class SyncInventory < CMDx::Task
+  settings retries: 5, retry_jitter: :exponential_backoff
+
+  def work
+    context.inventory = InventoryAPI.sync
+  end
+
+  private
+
+  def exponential_backoff(current_retry)
+    2 ** current_retry # 2s, 4s, 8s, 16s, 32s
+  end
+end
+```
+
+### Proc or Lambda
+
+Pass a proc for inline delay calculations:
+
+```ruby
+class PollJobStatus < CMDx::Task
+  # Proc
+  settings retries: 10, retry_jitter: proc { |retry_count| [retry_count * 0.5, 5.0].min }
+
+  # Lambda
+  settings retries: 10, retry_jitter: ->(retry_count) { [retry_count * 0.5, 5.0].min }
+
+  def work
+    # Delays: 0.5s, 1.0s, 1.5s, 2.0s, 2.5s, 3.0s, 3.5s, 4.0s, 4.5s, 5.0s (capped)
+    context.status = JobAPI.check_status(context.job_id)
+  end
+end
+```
+
+### Class or Module
+
+Implement reusable delay logic in dedicated modules and classes:
+
+```ruby
+class ExponentialBackoff
+  def call(task, retry_count)
+    base_delay = task.context.base_delay || 1.0
+    [base_delay * (2 ** retry_count), 60.0].min
+  end
+end
+
+class FetchUserProfile < CMDx::Task
+  # Class or Module
+  settings retries: 4, retry_jitter: ExponentialBackoff
+
+  # Instance
+  settings retries: 4, retry_jitter: ExponentialBackoff.new
+
+  def work
+    # Your logic here...
+  end
+end
+```

data/docs/tips_and_tricks.md

@@ -145,7 +145,8 @@ class ConfigureCompany < CMDx::Task
 end
 ```
 
-## Advanced Examples
+## More Examples
 
 - [Active Record Query Tagging](https://github.com/drexed/cmdx/blob/main/examples/active_record_query_tagging.md)
 - [Paper Trail Whatdunnit](https://github.com/drexed/cmdx/blob/main/examples/paper_trail_whatdunnit.md)
+- [Stoplight Circuit Breaker](https://github.com/drexed/cmdx/blob/main/examples/stoplight_circuit_breaker.md)

data/examples/stoplight_circuit_breaker.md

@@ -0,0 +1,36 @@
+# Stoplight Circuit Breaker
+
+Integrate circuit breakers to protect external service calls and prevent cascading failures when dependencies are unavailable.
+
+<https://github.com/bolshakov/stoplight>
+
+### Setup
+
+```ruby
+# lib/cmdx_stoplight_middleware.rb
+class CmdxStoplightMiddleware
+  def self.call(task, **options, &)
+    light = Stoplight(options[:name] || task.class.name, **options)
+    light.run(&)
+  rescue Stoplight::Error::RedLight => e
+    task.result.tap { |r| r.fail!("[#{e.class}] #{e.message}", cause: e) }
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  # With default options
+  register :middleware, CmdxStoplightMiddleware
+
+  # With stoplight options
+  register :middleware, CmdxStoplightMiddleware, cool_off_time: 10
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/lib/cmdx/attribute.rb

@@ -6,14 +6,71 @@ module CMDx
   # They can be nested to create complex hierarchical data structures.
   class Attribute
 
+    # @rbs AFFIX: Proc
     AFFIX = proc do |value, &block|
       value == true ? block.call : value
     end.freeze
     private_constant :AFFIX
 
+    # Returns the task instance associated with this attribute.
+    #
+    # @return [CMDx::Task] The task instance
+    #
+    # @example
+    #   attribute.task.context[:user_id] # => 42
+    #
+    # @rbs @task: Task
     attr_accessor :task
 
-    attr_reader :name, :options, :children, :parent, :types
+    # Returns the name of this attribute.
+    #
+    # @return [Symbol] The attribute name
+    #
+    # @example
+    #   attribute.name # => :user_id
+    #
+    # @rbs @name: Symbol
+    attr_reader :name
+
+    # Returns the configuration options for this attribute.
+    #
+    # @return [Hash{Symbol => Object}] Configuration options hash
+    #
+    # @example
+    #   attribute.options # => { required: true, default: 0 }
+    #
+    # @rbs @options: Hash[Symbol, untyped]
+    attr_reader :options
+
+    # Returns the child attributes for nested structures.
+    #
+    # @return [Array<Attribute>] Array of child attributes
+    #
+    # @example
+    #   attribute.children # => [#<Attribute @name=:street>, #<Attribute @name=:city>]
+    #
+    # @rbs @children: Array[Attribute]
+    attr_reader :children
+
+    # Returns the parent attribute if this is a nested attribute.
+    #
+    # @return [Attribute, nil] The parent attribute, or nil if root-level
+    #
+    # @example
+    #   attribute.parent # => #<Attribute @name=:address>
+    #
+    # @rbs @parent: (Attribute | nil)
+    attr_reader :parent
+
+    # Returns the expected type(s) for this attribute's value.
+    #
+    # @return [Array<Class>] Array of expected type classes
+    #
+    # @example
+    #   attribute.types # => [Integer, String]
+    #
+    # @rbs @types: Array[Class]
+    attr_reader :types
 
     # Creates a new attribute with the specified name and configuration.
     #
@@ -35,6 +92,8 @@ module CMDx
     #     required :name, types: String
     #     optional :email, types: String
     #   end
+    #
+    # @rbs ((Symbol | String) name, ?Hash[Symbol, untyped] options) ?{ () -> void } -> void
     def initialize(name, options = {}, &)
       @parent = options.delete(:parent)
       @required = options.delete(:required) || false
@@ -62,6 +121,8 @@ module CMDx
       #
       # @example
       #   Attribute.build(:first_name, :last_name, required: true, types: String)
+      #
+      # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
       def build(*names, **options, &)
         if names.none?
           raise ArgumentError, "no attributes given"
@@ -83,6 +144,8 @@ module CMDx
       #
       # @example
       #   Attribute.optional(:description, :tags, types: String)
+      #
+      # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
       def optional(*names, **options, &)
         build(*names, **options.merge(required: false), &)
       end
@@ -98,6 +161,8 @@ module CMDx
       #
       # @example
       #   Attribute.required(:id, :name, types: [Integer, String])
+      #
+      # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
       def required(*names, **options, &)
         build(*names, **options.merge(required: true), &)
       end
@@ -110,6 +175,8 @@ module CMDx
     #
     # @example
     #   attribute.required? # => true
+    #
+    # @rbs () -> bool
     def required?
       !!@required
     end
@@ -120,6 +187,8 @@ module CMDx
     #
     # @example
     #   attribute.source # => :context
+    #
+    # @rbs () -> untyped
     def source
       @source ||= parent&.method_name || begin
         value = options[:source]
@@ -140,6 +209,8 @@ module CMDx
     #
     # @example
     #   attribute.method_name # => :user_name
+    #
+    # @rbs () -> Symbol
     def method_name
       @method_name ||= options[:as] || begin
         prefix = AFFIX.call(options[:prefix]) { "#{source}_" }
@@ -150,6 +221,8 @@ module CMDx
     end
 
     # Defines and verifies the entire attribute tree including nested children.
+    #
+    # @rbs () -> void
     def define_and_verify_tree
       define_and_verify
 
@@ -172,6 +245,8 @@ module CMDx
     #
     # @example
     #   attributes :street, :city, :zip, types: String
+    #
+    # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
     def attributes(*names, **options, &)
       attrs = self.class.build(*names, **options.merge(parent: self), &)
       children.concat(attrs)
@@ -189,6 +264,8 @@ module CMDx
     #
     # @example
     #   optional :middle_name, :nickname, types: String
+    #
+    # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
     def optional(*names, **options, &)
       attributes(*names, **options.merge(required: false), &)
     end
@@ -204,6 +281,8 @@ module CMDx
     #
     # @example
     #   required :first_name, :last_name, types: String
+    #
+    # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
     def required(*names, **options, &)
       attributes(*names, **options.merge(required: true), &)
     end
@@ -211,6 +290,8 @@ module CMDx
     # Defines the attribute method on the task and validates the configuration.
     #
     # @raise [RuntimeError] When the method name is already defined on the task
+    #
+    # @rbs () -> void
     def define_and_verify
       if task.respond_to?(method_name, true)
         raise <<~MESSAGE

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)
 
@@ -64,6 +78,8 @@ module CMDx
     # @example
     #   attr_value.validate
     #   # Validates value against :presence, :format, etc.
+    #
+    # @rbs () -> void
     def validate
       registry = task.class.settings[:validators]
 
@@ -86,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
@@ -115,6 +132,8 @@ module CMDx
     # @example
     #   # Default can be symbol, proc, or direct value
     #   -> { rand(100) } # => 23
+    #
+    # @rbs () -> untyped
     def default_value
       default = options[:default]
 
@@ -140,6 +159,8 @@ module CMDx
     # @example
     #   # Derives from hash key, method call, or proc execution
     #   context.user_id # => 42
+    #
+    # @rbs (untyped source_value) -> untyped
     def derive_value(source_value)
       derived_value =
         case source_value
@@ -163,6 +184,8 @@ module CMDx
     #
     # @example
     #   :downcase # => "hello"
+    #
+    # @rbs (untyped derived_value) -> untyped
     def transform_value(derived_value)
       transform = options[:transform]
 
@@ -186,6 +209,8 @@ module CMDx
     # @example
     #   # Coerces "42" to Integer, "true" to Boolean, etc.
     #   coerce_value("42") # => 42
+    #
+    # @rbs (untyped transformed_value) -> untyped
     def coerce_value(transformed_value)
       return transformed_value if types.empty?