cmdx 1.9.1 → 1.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9220688eed061c4c48562665fe9c2c780a2ecc08642eeaedb095d6bfc312e643
-  data.tar.gz: f470f2ccebce524942277865f2967979244dde07ba1a43095c7f95209127c635
+  metadata.gz: 8c19fc5a6ffdcec800571b94fb0d1ac43eb82ae771388ad69b2d5cd4293ef1b1
+  data.tar.gz: bee42f15d1cee3a969495d2267b702e311a6121ec684f1806d3dd82aff7b2bb1
 SHA512:
-  metadata.gz: 155e2d09a4ca6147a7df578b0f2952ab81e781d5c492d821a4b71b08b41ef510cfccade001cc2e593f08ea1876ba6e5b658595a2bddaf6919f243c8df07d0569
-  data.tar.gz: fd0dba94495d6d139dc13507169143ee83f13dfac521d6ef607800c6d6e4cfd13e47cc03e2f27e047b185a0b9ebfc0a9d080143f7c6c2ec61aec139f38ea17cd
+  metadata.gz: 934ebc5db4d532e7ab0254e34851910dba35ba86e0cf9f6b8462c24bdeab3cbd94ac588c791f67e31f188f0f09270489a168591cb4656e923811cd1cad9c883f
+  data.tar.gz: 69d7f39f7167bc045e86ae0f23c655dd8bebcb6e176963a981be17cd29e39025116ccb5f2fa2273a6d1b505eb76ec2fc846850b45d19c0f8423547931b95d383

data/.cursor/prompts/llms.md

@@ -2,17 +2,7 @@ Process the following instructions in the order given:
 
 1. Create an `LLM.md` file
 2. Append all files within `docs/**/*.md` into @LLM.md
-  2a. Use order outlined in the table of contents of @README.md
+  2a. Use order outlined under the nav key in @mkdocs.yml
   2b. Process one file at a time faster performance and improved accuracy
-  2c. Wrap the chunk the files GitHub url the top and a spacer at the bottom like so:
-      ```
-
-      ---
-      url: https://github.com/drexed/cmdx/blob/main/docs/callbacks.md
-      ---
-
-      {{ chunk }}
-
-      ---
-
-      ```
+  2c. Exclude @index.md and @LLM.md files
+  2d. All URLs should be absolute

data/.yardopts

@@ -0,0 +1,7 @@
+--no-private
+--output-dir
+docs/api
+--exclude
+lib/generators/**/*.rb
+lib/cmdx/railtie.rb
+lib/**/*.rb

data/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
+## [1.10.1] - 2025-11-06
+
+### Added
+- Added Sidekiq async integration example
+- Added YARDoc documentation to docs site
+
+### Removed
+- Removed `Executor#repeator` method (never used)
+
+## [1.10.0] - 2025-10-26
+
+### Added
+- Added `rollback` ability to undo on matching status
+- Added documentation for retries
+- Added Stoplight circuit breaker integration example
+
+### Updated
+- Updated `retry_jitter` option to support symbol, proc, and callables on top of fixed values
+
 ## [1.9.1] - 2025-10-22
 
 ### Added

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">

data/Rakefile

@@ -9,4 +9,25 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+desc "Generate YARD API documentation"
+task :yard do
+  require "yard"
+  require "fileutils"
+
+  YARD::CLI::Yardoc.run(*File.readlines(".yardopts", chomp: true).reject(&:empty?))
+
+  api_dir = "docs/api"
+
+  # Remove unwanted files
+  FileUtils.rm_f("#{api_dir}/Cmdx_.html")
+  FileUtils.rm_f("#{api_dir}/top-level-namespace.html")
+  FileUtils.rm_f("#{api_dir}/CMDx/InstallGenerator.html")
+  FileUtils.rm_f("#{api_dir}/CMDx/LocaleGenerator.html")
+  FileUtils.rm_f("#{api_dir}/CMDx/TaskGenerator.html")
+  FileUtils.rm_f("#{api_dir}/CMDx/WorkflowGenerator.html")
+
+  # Make CMDx.html the default index
+  FileUtils.cp("#{api_dir}/CMDx.html", "#{api_dir}/index.html") if File.exist?("#{api_dir}/CMDx.html")
+end
+
 task default: %i[spec rubocop]

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/configuration.md

@@ -0,0 +1,314 @@
+# Configuration
+
+Configure CMDx to customize framework behavior, register components, and control execution flow through global defaults with task-level overrides.
+
+## Configuration Hierarchy
+
+CMDx uses a straightforward two-tier configuration system:
+
+1. **Global Configuration** — Framework-wide defaults
+2. **Task Settings** — Class-level overrides using `settings`
+
+!!! warning "Important"
+
+    Task settings take precedence over global config. Settings are inherited from parent classes and can be overridden in subclasses.
+
+## Global Configuration
+
+Configure framework-wide defaults that apply to all tasks. These settings come with sensible defaults out of the box.
+
+### Breakpoints
+
+Control when `execute!` raises a `CMDx::Fault` based on task status.
+
+```ruby
+CMDx.configure do |config|
+  config.task_breakpoints = "failed" # String or Array[String]
+end
+```
+
+For workflows, configure which statuses halt the execution pipeline:
+
+```ruby
+CMDx.configure do |config|
+  config.workflow_breakpoints = ["skipped", "failed"]
+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.
+
+!!! note
+
+    In Rails environments, `backtrace_cleaner` defaults to `Rails.backtrace_cleaner.clean`.
+
+```ruby
+CMDx.configure do |config|
+  # Truthy
+  config.backtrace = true
+
+  # Via callable (must respond to `call(backtrace)`)
+  config.backtrace_cleaner = AdvanceCleaner.new
+
+  # Via proc or lambda
+  config.backtrace_cleaner = ->(backtrace) { backtrace[0..5] }
+end
+```
+
+### Exception Handlers
+
+Register handlers that run when non-fault exceptions occur.
+
+!!! tip
+
+    Use exception handlers to send errors to your APM of choice.
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(task, exception)`)
+  config.exception_handler = NewRelicReporter
+
+  # Via proc or lambda
+  config.exception_handler = proc do |task, exception|
+    APMService.report(exception, extra_data: { task: task.name, id: task.id })
+  end
+end
+```
+
+### Logging
+
+```ruby
+CMDx.configure do |config|
+  config.logger = CustomLogger.new($stdout)
+end
+```
+
+### Middlewares
+
+See the [Middlewares](middlewares.md#declarations) docs for task level configurations.
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(task, options)`)
+  config.middlewares.register CMDx::Middlewares::Timeout
+
+  # Via proc or lambda
+  config.middlewares.register proc { |task, options|
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    result = yield
+    end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    Rails.logger.debug { "task completed in #{((end_time - start_time) * 1000).round(2)}ms" }
+    result
+  }
+
+  # With options
+  config.middlewares.register AuditTrailMiddleware, service_name: "document_processor"
+
+  # Remove middleware
+  config.middlewares.deregister CMDx::Middlewares::Timeout
+end
+```
+
+!!! note
+
+    Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
+
+### Callbacks
+
+See the [Callbacks](callbacks.md#declarations) docs for task level configurations.
+
+```ruby
+CMDx.configure do |config|
+  # Via method
+  config.callbacks.register :before_execution, :initialize_user_session
+
+  # Via callable (must respond to `call(task)`)
+  config.callbacks.register :on_success, LogUserActivity
+
+  # Via proc or lambda
+  config.callbacks.register :on_complete, proc { |task|
+    execution_time = task.metadata[:runtime]
+    Metrics.timer("task.execution_time", execution_time, tags: ["task:#{task.class.name.underscore}"])
+  }
+
+  # With options
+  config.callbacks.register :on_failure, :send_alert_notification, if: :critical_task?
+
+  # Remove callback
+  config.callbacks.deregister :on_success, LogUserActivity
+end
+```
+
+### Coercions
+
+See the [Attributes - Coercions](attributes/coercions.md#declarations) docs for task level configurations.
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(value, options)`)
+  config.coercions.register :currency, CurrencyCoercion
+
+  # Via method (must match signature `def coordinates_coercion(value, options)`)
+  config.coercions.register :coordinates, :coordinates_coercion
+
+  # Via proc or lambda
+  config.coercions.register :tag_list, proc { |value, options|
+    delimiter = options[:delimiter] || ','
+    max_tags = options[:max_tags] || 50
+
+    tags = value.to_s.split(delimiter).map(&:strip).reject(&:empty?)
+    tags.first(max_tags)
+  }
+
+  # Remove coercion
+  config.coercions.deregister :currency
+end
+```
+
+### Validators
+
+See the [Attributes - Validations](attributes/validations.md#declarations) docs for task level configurations.
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(value, options)`)
+  config.validators.register :username, UsernameValidator
+
+  # Via method (must match signature `def url_validator(value, options)`)
+  config.validators.register :url, :url_validator
+
+  # Via proc or lambda
+  config.validators.register :access_token, proc { |value, options|
+    expected_prefix = options[:prefix] || "tok_"
+    minimum_length = options[:min_length] || 40
+
+    value.start_with?(expected_prefix) && value.length >= minimum_length
+  }
+
+  # Remove validator
+  config.validators.deregister :username
+end
+```
+
+## Task Configuration
+
+### Settings
+
+Override global configuration for specific tasks using `settings`:
+
+```ruby
+class GenerateInvoice < CMDx::Task
+  settings(
+    # Global configuration overrides
+    task_breakpoints: ["failed"],                # Breakpoint override
+    workflow_breakpoints: [],                    # Breakpoint override
+    backtrace: true,                             # Toggle backtrace
+    backtrace_cleaner: ->(bt) { bt[0..5] },      # Backtrace cleaner
+    logger: CustomLogger.new($stdout),           # Custom logger
+
+    # Task configuration settings
+    breakpoints: ["failed"],                     # Contextual pointer for :task_breakpoints and :workflow_breakpoints
+    log_level: :info,                            # Log level override
+    log_formatter: CMDx::LogFormatters::Json.new # Log formatter override
+    tags: ["billing", "financial"],              # Logging tags
+    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
+    rollback_on: ["failed", "skipped"],          # Rollback on override
+  )
+
+  def work
+    # Your logic here...
+  end
+end
+```
+
+!!! warning "Important"
+
+    Retries reuse the same context. By default, all `StandardError` exceptions (including faults) are retried unless you specify `retry_on` option for specific matches.
+
+### Registrations
+
+Register or deregister middlewares, callbacks, coercions, and validators for specific tasks:
+
+```ruby
+class SendCampaignEmail < CMDx::Task
+  # Middlewares
+  register :middleware, CMDx::Middlewares::Timeout
+  deregister :middleware, AuditTrailMiddleware
+
+  # Callbacks
+  register :callback, :on_complete, proc { |task|
+    runtime = task.metadata[:runtime]
+    Analytics.track("email_campaign.sent", runtime, tags: ["task:#{task.class.name}"])
+  }
+  deregister :callback, :before_execution, :initialize_user_session
+
+  # Coercions
+  register :coercion, :currency, CurrencyCoercion
+  deregister :coercion, :coordinates
+
+  # Validators
+  register :validator, :username, :username_validator
+  deregister :validator, :url
+
+  def work
+    # Your logic here...
+  end
+end
+```
+
+## Configuration Management
+
+### Access
+
+```ruby
+# Global configuration access
+CMDx.configuration.logger               #=> <Logger instance>
+CMDx.configuration.task_breakpoints     #=> ["failed"]
+CMDx.configuration.middlewares.registry #=> [<Middleware>, ...]
+
+# Task configuration access
+class ProcessUpload < CMDx::Task
+  settings(tags: ["files", "storage"])
+
+  def work
+    self.class.settings[:logger] #=> Global configuration value
+    self.class.settings[:tags]   #=> Task configuration value => ["files", "storage"]
+  end
+end
+```
+
+### Resetting
+
+!!! warning
+
+    Resetting affects your entire application. Use this primarily in test environments.
+
+```ruby
+# Reset to framework defaults
+CMDx.reset_configuration!
+
+# Verify reset
+CMDx.configuration.task_breakpoints     #=> ["failed"] (default)
+CMDx.configuration.middlewares.registry #=> Empty registry
+
+# Commonly used in test setup (RSpec example)
+RSpec.configure do |config|
+  config.before(:each) do
+    CMDx.reset_configuration!
+  end
+end
+```